Initial conventions for AI agents and humans: AGENTS.md, SKILLS.md, instructions.md (#8478)

Not stable yet, but initial structure
https://agents.md
https://agentskills.io/specification
https://code.visualstudio.com/docs/copilot/customization/custom-instructions
https://code.visualstudio.com/docs/copilot/customization/agent-skills

.github/instructions/_general.instructions.md

@@ -0,0 +1,23 @@
+---
+applyTo: "**"
+description: General instructions
+---
+
+# FreshRSS General instructions
+
+## KISS principle: Keep It Simple
+
+* Prioritise simplicity, brevity, and clarity in code and documentation.
+* Avoid premature abstractions or over-engineering.
+* Reuse and adapt existing code where possible, avoiding duplication.
+* Keep changes minimal and focused.
+* Favour vanilla solutions: avoid adding third-party dependencies and frameworks.
+* Overall, reduce the number of lines and quantity of code (including dependencies).
+
+## Style and formatting
+
+* When editing files, obey indentation and white-space as defined in [`.editorconfig`](../../.editorconfig) (some of it can be automatically fixed with `make fix-all`).
+
+## Spelling
+
+* Favour British English spelling and conventions in code, comments, and documentation.

.github/instructions/css.instructions.md

@@ -0,0 +1,31 @@
+---
+applyTo: "**/*.css"
+description: Editing CSS files
+---
+
+# CSS files
+
+* Obey formatting rules defined in [`.stylelintrc.json`](../../.stylelintrc.json)
+* Automatic fixes can be done with:
+	```sh
+	npm run stylelint_fix
+	# or (targeting more than just CSS)
+	make fix-all
+	```
+* Validation can be done with:
+	```sh
+	npm run stylelint
+	# or (targeting more than just CSS)
+	make test-all
+	```
+
+## Right-to-left CSS files
+
+* Do not edit RTL CSS `*.rtl.css` files manually.
+* RTL CSS files are auto-generated from LTR CSS files using the `rtlcss` tool.
+* Run the following command to regenerate the RTL files:
+	```sh
+	npm run rtlcss
+	# or
+	make rtl
+	```

.github/instructions/i18n.instructions.md

@@ -0,0 +1,55 @@
+---
+applyTo: "app/i18n/*/*.php"
+description: Editing FreshRSS translations
+---
+
+# FreshRSS translations (i18n)
+
+* Favour commands over manual edits to add, move, or delete translation keys:
+	* Use the `cli/manipulate.translation.php` script or the corresponding `make` commands.
+
+## Commands
+
+### Add a new translation key
+
+To add a new translatable string across all languages:
+
+```sh
+./cli/manipulate.translation.php --action add --key 'example.of.key' --value 'Example of text'
+# or
+make i18n-add-key key='example.of.key' value='Example of text'
+```
+
+This will:
+1. Add the key to English (`app/i18n/en/gen.php`) with the provided value
+2. Add the key to all other languages marked as `// TODO` for translators
+
+You should then:
+1. Remove the `// TODO` comment in English `en/`
+2. Update to `// IGNORE` comment in US English `en-US/` or adapt the string in case of regional differences
+
+### Delete a translation key
+
+To delete a translation key from all languages:
+
+```sh
+./cli/manipulate.translation.php --action delete --key 'old.key.path'
+```
+
+### Other commands
+
+See all available commands with:
+
+```sh
+./cli/manipulate.translation.php -a --help
+```
+
+## Post-fixing
+
+After manipulating translation, you should call the following to reformat and ensure consistency:
+
+```sh
+composer run-script translations
+# or (targeting more than just translations)
+make fix-all
+```

.github/instructions/javascript.instructions.md

@@ -0,0 +1,21 @@
+---
+applyTo: "**/*.js"
+description: Editing JavaScript files
+---
+
+# JavaScript files
+
+* Obey formatting rules defined in [`eslint.config.js`](../../eslint.config.js)
+* Automatic fixes can be done with:
+	```sh
+	npm run eslint_fix
+	# or (targeting more than just JavaScript)
+	make fix-all
+	```
+* Validation can be done with:
+	```sh
+	npm run eslint
+	# or (targeting more than just JavaScript)
+	make test-all
+	```
+* Check [`package.json`](../../package.json) scripts for details about available individual commands.

.github/instructions/markdown.instructions.md

@@ -0,0 +1,19 @@
+---
+applyTo: "**/*.md"
+description: Editing Markdown
+---
+
+# Markdown files
+
+* Obey formatting rules defined in [`.markdownlint.json`](../../.markdownlint.json)
+* For fenced code blocks:
+	* Use language identifiers as much as possible, e.g., `php`, `js`, `css`
+	* Favour `sh` over `bash`
+* Automatic fixes can be done with:
+	```sh
+	npm run markdownlint_fix
+	```
+* Validation can be done with:
+	```sh
+	npm run markdownlint
+	```

.github/instructions/php.instructions.md

@@ -0,0 +1,37 @@
+---
+applyTo: "**/*.php"
+description: Editing PHP files
+---
+
+# PHP files
+
+* See minimum PHP version and available PHP extensions in [`composer.json`](../../composer.json)
+* Obey formatting rules defined in [`phpcs.xml`](../../phpcs.xml)
+* Automatic fixes can be done with:
+	```sh
+	composer run-script fix
+	# or (targeting more than just PHP)
+	make fix-all
+	```
+* Validation can be done with:
+	```sh
+	composer test
+	# or (targeting more than just PHP)
+	make test-all
+	```
+* Check [`composer.json`](../../composer.json) scripts for details about available individual commands.
+* For instance, running a single unit test can be done with:
+	```sh
+	composer run-script phpunit -- tests/app/Models/SearchTest.php
+	```
+
+## Autoloader
+
+* `spl_autoload_register` is defined in [`lib/lib_rss.php`](../../lib/lib_rss.php)
+
+Minimal example:
+
+```php
+require dirname(__DIR__) . '/constants.php';
+require LIB_PATH . '/lib_rss.php';	//Includes class autoloader
+```

.github/skills/freshrss-git/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: freshrss-git
+description: FreshRSS version control, git workflow, branching strategy (edge/latest), diff/compare, PR changes.
+allowed-tools: Bash(git:*) Read Grep
+---
+
+# FreshRSS working with version control (git)
+
+FreshRSS uses a rolling-release approach with a main branch called `:edge`.
+This is the branch to target for most pull requests.
+
+Releases are tracked in a branch called `:latest`.
+
+## Check changes made in the current branch
+
+Also useful to locally check the state of a pull-request (PR).
+
+```sh
+git diff edge...HEAD
+```
+
+## Before commiting
+
+```sh
+make fix-all
+make test-all
+```

.github/skills/freshrss-i18n/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: freshrss-i18n
+description: Add, move, or format translation strings in FreshRSS. Use when modifying UI text that needs translation (i18n). Handles all supported languages automatically.
+allowed-tools: Bash(php:*) Bash(composer:*) Bash(make:*) Read Grep
+---
+
+# FreshRSS translation management (i18n)
+
+For instructions and commands to work with translations, make sure to obey [i18n.instructions.md](../../instructions/i18n.instructions.md).
+
+Translations strings are in `app/i18n/{lang}/` as PHP arrays, used with:
+
+```php
+_t('key.subkey')
+```
+
+## When to use this skill
+
+- Adding new user-facing text to the application
+- Moving/renaming or deleting existing translation keys
+- Adding a new translation file for a new feature area
+- Formatting translation files after manual edits
+
+## Workflow example
+
+When adding a new UI element:
+
+1. Identify the appropriate i18n file and section, in proximity of existing strings, avoiding duplication
+2. Add a key if an appropriate string does not already exist, using `cli/manipulate.translation.php` or the corresponding `make` commands as defined in the [instructions](../../instructions/i18n.instructions.md).
+3. Use in the code:
+	```php
+	<button><?= _t('gen.action.my_new_button') ?></button>
+	```