feat: Update documentation to include details about the new skills command for synchronizing packaged agent skills

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>

Author: coisa

README.md

@@ -1,5 +1,9 @@
 # FastForward\DevTools
 
+FastForward DevTools is a Composer plugin that standardizes quality checks,
+documentation builds, consumer repository bootstrap, and packaged agent skills
+across Fast Forward libraries.
+
 [![PHP Version](https://img.shields.io/badge/php-^8.3-777BB4?logo=php&logoColor=white)](https://www.php.net/releases/)
 [![Composer Package](https://img.shields.io/badge/composer-fast--forward%2Fdev--tools-F28D1A.svg?logo=composer&logoColor=white)](https://packagist.org/packages/fast-forward/dev-tools)
 [![Tests](https://img.shields.io/github/actions/workflow/status/php-fast-forward/dev-tools/tests.yml?logo=githubactions&logoColor=white&label=tests&color=22C55E)](https://github.com/php-fast-forward/dev-tools/actions/workflows/tests.yml)
@@ -10,11 +14,14 @@
 
 ## ✨ Features
 
-- Aggregates multiple development tools into a single command
-- Automates execution of tests, static analysis, and code styling
-- First-class support for automated refactoring and docblock generation
-- Integrates seamlessly as a Composer plugin without boilerplate
-- Configures default setups for QA tools out of the box
+- Aggregates refactoring, PHPDoc, code style, tests, and reporting under a
+  single Composer-facing command vocabulary
+- Ships shared workflow stubs, `.editorconfig`, Dependabot configuration, and
+  other onboarding defaults for consumer repositories
+- Synchronizes packaged agent skills into consumer `.agents/skills`
+  directories using safe link-based updates
+- Works both as a Composer plugin and as a local binary
+- Preserves local overrides through consumer-first configuration resolution
 
 ## 🚀 Installation
 
@@ -58,13 +65,48 @@ composer dev-tools wiki
 # Generate documentation frontpage and related reports
 composer dev-tools reports
 
+# Synchronize packaged agent skills into .agents/skills
+composer dev-tools skills
+
 # Merges and synchronizes .gitignore files
 composer dev-tools gitignore
 
-# Installs and synchronizes dev-tools scripts, GitHub Actions workflows, .editorconfig, and ensures the repository wiki is present as a git submodule in .github/wiki
+# Installs and synchronizes dev-tools scripts, GitHub Actions workflows,
+# .editorconfig, .gitignore rules, packaged skills, and the repository wiki
+# submodule in .github/wiki
 composer dev-tools:sync
 ```
 
+The `skills` command keeps `.agents/skills` aligned with the packaged Fast
+Forward skill set. It creates missing links, repairs broken links, and
+preserves existing non-symlink directories. The `dev-tools:sync` command calls
+`skills` automatically after refreshing the rest of the consumer-facing
+automation assets.
+
+## 🧰 Command Summary
+
+| Command | Purpose |
+|---------|---------|
+| `composer dev-tools` | Runs the full `standards` pipeline. |
+| `composer dev-tools tests` | Runs PHPUnit with local-or-packaged configuration. |
+| `composer dev-tools docs` | Builds the HTML documentation site from PSR-4 code and `docs/`. |
+| `composer dev-tools skills` | Creates or repairs packaged skill links in `.agents/skills`. |
+| `composer dev-tools:sync` | Updates scripts, workflow stubs, `.editorconfig`, `.gitignore`, wiki setup, and packaged skills. |
+
+## 🔌 Integration
+
+DevTools integrates with consumer repositories in two ways. The Composer plugin
+exposes the command set automatically after installation, and the local binary
+keeps the same command vocabulary when you prefer running tools directly from
+`vendor/bin/dev-tools`. The consumer sync flow also refreshes `.agents/skills`
+so agents can discover the packaged skills shipped with this repository.
+
+## 🤝 Contributing
+
+Run `composer dev-tools` before opening a pull request. If you change public
+commands or consumer onboarding behavior, update `README.md` and `docs/`
+together so downstream libraries keep accurate guidance.
+
 ## 📄 License
 
 This package is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
@@ -73,4 +115,5 @@ This package is licensed under the MIT License. See the [LICENSE](LICENSE) file
 
 - [Repository](https://github.com/php-fast-forward/dev-tools)
 - [Packagist](https://packagist.org/packages/fast-forward/dev-tools)
+- [Documentation](https://php-fast-forward.github.io/dev-tools/index.html)
 - [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119)

docs/advanced/consumer-automation.rst

@@ -5,8 +5,8 @@ FastForward DevTools plays two roles at once:
 
 - producer: this repository ships reusable workflow templates and default
   configuration files;
-- consumer helper: the ``dev-tools:sync`` command copies those assets into
-  other Fast Forward libraries.
+- consumer helper: the ``dev-tools:sync`` command copies those assets and links
+  packaged skills into other Fast Forward libraries.
 
 Reusable Workflows Versus Consumer Stubs
 ----------------------------------------
@@ -25,6 +25,9 @@ Reusable Workflows Versus Consumer Stubs
      - This repository's own Dependabot configuration.
    * - ``resources/dependabot.yml``
      - Template copied into consumer repositories.
+   * - ``.agents/skills/*``
+     - Packaged agent skills linked into consumer repositories by the
+       ``skills`` command.
    * - ``.github/wiki``
      - Generated Markdown API documentation locally and wiki submodule content
        in consumer repositories.
@@ -48,5 +51,6 @@ Producer Impact
 ---------------
 
 Any change to ``resources/github-actions``, ``resources/dependabot.yml``,
-``.github/workflows``, or ``FastForward\DevTools\Command\SyncCommand`` changes
-the default onboarding story for every consumer library.
+``.agents/skills``, ``.github/workflows``, or
+``FastForward\DevTools\Command\SyncCommand`` changes the default onboarding
+story for every consumer library.

docs/api/commands.rst

@@ -39,9 +39,13 @@ resolution, configuration fallback, PSR-4 lookup, and child-command dispatch.
    * - ``FastForward\DevTools\Command\ReportsCommand``
      - ``reports``
      - Combines the documentation build with coverage generation.
+   * - ``FastForward\DevTools\Command\SkillsCommand``
+     - ``skills``
+     - Synchronizes packaged agent skills into ``.agents/skills``.
    * - ``FastForward\DevTools\Command\SyncCommand``
      - ``dev-tools:sync``
-     - Synchronizes consumer-facing scripts and automation assets.
+     - Synchronizes consumer-facing scripts, automation assets, and packaged
+       skills.
    * - ``FastForward\DevTools\Command\GitIgnoreCommand``
      - ``gitignore``
      - Merges and synchronizes .gitignore files.

docs/configuration/overriding-defaults.rst

@@ -39,6 +39,10 @@ Commands and Their Configuration Files
    * - ``docs``
      - ``docs/`` or another path passed with ``--source``
      - The selected guide source must exist locally.
+   * - ``skills``
+     - ``.agents/skills/``
+     - Creates missing local links to packaged skills and preserves existing
+       non-symlink directories.
    * - ``dev-tools:sync``
      - Consumer repository files
      - Works directly against local project files such as ``composer.json`` and
@@ -106,6 +110,7 @@ What Is Not Overwritten Automatically
 - existing workflow files in ``.github/workflows/``;
 - an existing ``.editorconfig``;
 - an existing ``.github/dependabot.yml``;
+- an existing non-symlink directory inside ``.agents/skills/``;
 - an existing ``.github/wiki`` directory or submodule.
 
 .. tip::

docs/configuration/tooling-defaults.rst

@@ -28,6 +28,10 @@ create them on day one.
    * - ``.editorconfig``
      - ``dev-tools:sync``
      - Copied into the consumer root when missing.
+   * - ``.agents/skills/*``
+     - ``skills`` and ``dev-tools:sync``
+     - Packaged agent skill directories exposed to consumer repositories
+       through symlinks.
 
 Generated and Cache Directories
 -------------------------------
@@ -37,6 +41,8 @@ Generated and Cache Directories
   coverage data.
 - ``.github/wiki/`` contains generated Markdown API documentation and, in
   consumer repositories, the wiki submodule.
+- ``.agents/skills/`` contains symlinked packaged skills or consumer-owned
+  directories kept in place by the ``skills`` command.
 - ``tmp/cache/phpdoc``, ``tmp/cache/phpunit``, ``tmp/cache/rector``, and
   ``tmp/cache/.php-cs-fixer.cache`` store tool caches.
 

docs/faq.rst

@@ -20,7 +20,15 @@ Do I always need to run ``dev-tools:sync`` manually?
 Usually no. The plugin already runs it after ``composer install`` and
 ``composer update``. Manual sync is most useful when plugins were disabled or
 after upgrading ``fast-forward/dev-tools`` and wanting to refresh consumer
-automation.
+automation. That flow also runs ``skills`` so packaged skill links are kept up
+to date.
+
+When should I run ``composer dev-tools skills`` manually?
+---------------------------------------------------------
+
+Run it when you want to refresh ``.agents/skills`` without rerunning the full
+consumer sync flow, especially after upgrading ``fast-forward/dev-tools`` or
+after deleting a packaged skill link locally.
 
 Why does ``code-style`` touch ``composer.lock``?
 ------------------------------------------------
@@ -69,6 +77,13 @@ What happens if ``.github/wiki`` already exists?
 ``dev-tools:sync`` leaves it alone. The wiki submodule is only created when the
 directory is missing.
 
+What happens if ``.agents/skills/my-skill`` already exists?
+-----------------------------------------------------------
+
+If that path is a real directory instead of a symlink, the ``skills`` command
+preserves it and skips link creation. Broken symlinks are repaired, but
+consumer-owned directories are not overwritten automatically.
+
 How do I override only one tool without forking the whole package?
 ------------------------------------------------------------------
 

docs/getting-started/index.rst

@@ -11,7 +11,8 @@ By the end of this section you will know how to:
 - run the generated commands through Composer or directly through the binary;
 - prepare the minimum ``docs/`` structure required by the documentation
   pipeline;
-- understand which files ``dev-tools:sync`` creates or updates.
+- understand which files ``dev-tools:sync`` creates or updates, including
+  packaged skills under ``.agents/skills``.
 
 .. toctree::
    :maxdepth: 1

docs/getting-started/installation.rst

@@ -37,6 +37,10 @@ following steps:
    ``.github/dependabot.yml``.
 6. If ``.github/wiki`` is missing, ``dev-tools:sync`` adds it as a Git
    submodule that points to the repository wiki.
+7. ``dev-tools:sync`` runs ``gitignore`` to merge canonical ignore rules into
+   the consumer project.
+8. ``dev-tools:sync`` runs ``skills`` to create or repair packaged skill links
+   inside ``.agents/skills``.
 
 First commands to try
 ---------------------
@@ -45,6 +49,7 @@ After installation, these are the most useful sanity checks:
 
 .. code-block:: bash
 
+   composer dev-tools skills
    composer dev-tools tests
    composer dev-tools docs
    composer dev-tools
@@ -55,6 +60,12 @@ If Composer argument forwarding becomes awkward, call the binary directly:
 
    vendor/bin/dev-tools tests --filter=SyncCommandTest
 
+If you want to verify the packaged skills on their own, run:
+
+.. code-block:: bash
+
+   vendor/bin/dev-tools skills
+
 When manual sync is useful
 --------------------------
 
@@ -75,3 +86,5 @@ Or call the binary explicitly:
 
    The ``docs`` and ``reports`` commands require a ``docs/`` directory. If
    your package does not have one yet, create it before running those commands.
+   The ``skills`` command creates ``.agents/skills`` when needed, but it does
+   not overwrite an existing non-symlink directory inside that tree.

docs/getting-started/quickstart.rst

@@ -5,7 +5,7 @@ This walkthrough is the fastest way to get a new library into a healthy state.
 
 1. Install the package.
 2. Create a minimal guide directory.
-3. Synchronize shared automation.
+3. Synchronize shared automation and packaged skills.
 4. Run the focused commands once.
 5. Run the full suite before opening a pull request.
 
@@ -38,6 +38,7 @@ Once the package is installed and the guide directory exists, run:
 .. code-block:: bash
 
    composer dev-tools:sync
+   composer dev-tools skills
    composer dev-tools tests
    composer dev-tools docs
    composer dev-tools
@@ -46,7 +47,10 @@ What Each Command Proves
 ------------------------
 
 - ``composer dev-tools:sync`` proves the consumer repository can receive the
-  shared scripts and automation assets.
+  shared scripts, automation assets, and packaged skills during onboarding.
+- ``composer dev-tools skills`` proves the packaged skill set can be linked
+  safely into ``.agents/skills`` without copying files into the consumer
+  repository.
 - ``composer dev-tools tests`` proves the packaged or local PHPUnit
   configuration can execute the current test suite.
 - ``composer dev-tools docs`` proves the PSR-4 source paths and the guide

docs/index.rst

@@ -3,7 +3,7 @@ Documentation
 
 FastForward DevTools is infrastructure for Fast Forward libraries. It ships
 shared defaults, registers Composer commands, generates documentation, and
-synchronizes automation into consumer repositories.
+synchronizes automation plus packaged agent skills into consumer repositories.
 
 If you are new to the package, start with :doc:`getting-started/index` and
 :doc:`usage/index`. If you maintain Fast Forward libraries, continue with