diff --git a/.changelog/consumer-template-skill.md b/.changelog/consumer-template-skill.md
new file mode 100644
index 0000000..2ff788c
--- /dev/null
+++ b/.changelog/consumer-template-skill.md
@@ -0,0 +1,6 @@
+---
+category: added
+type: minor
+---
+
+Bundle a portable consumer skill with checked phpDocumentor examples, DevTools reports guidance and optional llm/skills discovery metadata.
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index c74c91a..641180c 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -30,11 +30,14 @@ jobs:
- run: composer install --no-scripts --no-interaction --prefer-dist --no-progress
- name: Validate rendered checkout
run: php tests/generate-fixture.php
+ - name: Validate bundled consumer example
+ run: php tests/verify-consumer-skill.php
- name: Validate rendered release archive
run: |
mkdir -p "$RUNNER_TEMP/template-archive"
git archive HEAD | tar -x -C "$RUNNER_TEMP/template-archive"
php tests/generate-fixture.php "$RUNNER_TEMP/template-archive"
+ php tests/verify-consumer-skill.php "$RUNNER_TEMP/template-archive"
actions:
name: Analyze (actions)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..94bb8a1
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,27 @@
+# Template maintenance
+
+This repository owns a phpDocumentor Twig/Bootstrap template, not a PHP service
+library. Preserve the Composer type `phpdocumentor-template` and existing public
+template path. Follow `CONTRIBUTING.md` for change fragments and `DESIGN.md` for
+visual identity. Merge, release and deployment require maintainer authorization.
+
+## Bundled consumer skill
+
+Read [the consumer skill](resources/skills/fast-forward-phpdoc-bootstrap-template/SKILL.md)
+when changing consumer configuration, integration examples, guides or the skill.
+Keep its version contract, references and checked examples aligned with public
+template behavior. Its canonical distributable source is `resources/skills`;
+do not add a second copy or host aliases. Package procedures belong in `SKILL.md`.
+
+## Validation
+
+Run `composer validate --strict`, `php tests/generate-fixture.php` and
+`php tests/verify-consumer-skill.php` after installing development dependencies.
+Check the archive too: `.gitattributes` excludes `/docs/`, so consumer skill
+references and examples must remain inside their package. The CI workflow owns
+the PHP matrix and archive rendering checks. Keep unrelated worktree changes.
+
+## Child DOX Index
+
+No child instruction contracts. The consumer package owns its procedure through
+its linked `SKILL.md`; ordinary template and test folders share this root contract.
diff --git a/README.md b/README.md
index c87829d..6525b3b 100644
--- a/README.md
+++ b/README.md
@@ -103,6 +103,18 @@ Typical customization points include:
- cards and content sections
- Bootstrap styling
+## Consumer agent skill
+
+The package bundles [fast-forward-phpdoc-bootstrap-template](resources/skills/fast-forward-phpdoc-bootstrap-template/SKILL.md)
+for agents configuring guide homepages, API generation and output checks. It
+supports template `^2.1.1`, PHP `^8.3` and phpDocumentor shim `^3.9`, and includes
+an [existing DevTools reports route](resources/skills/fast-forward-phpdoc-bootstrap-template/references/dev-tools.md).
+The template itself does not install phpDocumentor or activate an agent skill.
+
+See [skill installation and lifecycle](resources/skills/fast-forward-phpdoc-bootstrap-template/references/installation.md)
+for optional project synchronization with `llm/skills ^1.15`, guarded manual
+project/global copies and a pinned Skills CLI alternative.
+
## Contributing
Contributions are welcome. Please open an issue or submit a pull request.
diff --git a/composer.json b/composer.json
index ff5cf49..397856d 100644
--- a/composer.json
+++ b/composer.json
@@ -31,6 +31,14 @@
"require": {
"php": "^8.3"
},
+ "suggest": {
+ "llm/skills": "Optionally synchronize the bundled consumer skill in your project."
+ },
+ "extra": {
+ "skills": {
+ "source": "resources/skills"
+ }
+ },
"minimum-stability": "stable",
"prefer-stable": true,
"config": {
diff --git a/composer.lock b/composer.lock
index 18096a7..83ebb9b 100644
--- a/composer.lock
+++ b/composer.lock
@@ -4,7 +4,7 @@
"Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
"This file is @generated automatically"
],
- "content-hash": "27cf07ecfb860cbf86f8a878c6a05e00",
+ "content-hash": "fe1b3da1089559c1934ad34bdd396896",
"packages": [],
"packages-dev": [
{
diff --git a/resources/skills/fast-forward-phpdoc-bootstrap-template/LICENSE b/resources/skills/fast-forward-phpdoc-bootstrap-template/LICENSE
new file mode 100644
index 0000000..6374901
--- /dev/null
+++ b/resources/skills/fast-forward-phpdoc-bootstrap-template/LICENSE
@@ -0,0 +1,19 @@
+Copyright (c) 2026 Felipe Sayão Lobato Abreu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
diff --git a/resources/skills/fast-forward-phpdoc-bootstrap-template/SKILL.md b/resources/skills/fast-forward-phpdoc-bootstrap-template/SKILL.md
new file mode 100644
index 0000000..70bc6d5
--- /dev/null
+++ b/resources/skills/fast-forward-phpdoc-bootstrap-template/SKILL.md
@@ -0,0 +1,160 @@
+---
+name: fast-forward-phpdoc-bootstrap-template
+description: Configure and generate PHP API documentation and guides with the Fast Forward phpDocumentor Bootstrap template. Use for phpdoc.xml setup, guide homepages, template assets, output verification, or an existing Fast Forward DevTools reports integration.
+license: MIT; see LICENSE
+compatibility: Supports fast-forward/phpdoc-bootstrap-template ^2.1.1, PHP ^8.3 and phpDocumentor shim ^3.9. Requires Composer and phpDocumentor extensions; the verification example also uses DOM. Earlier template releases are outside this contract.
+metadata:
+ author: Fast Forward
+ api-baseline: fast-forward/phpdoc-bootstrap-template ^2.1.1
+---
+
+# Generate Fast Forward documentation
+
+Use this skill in a PHP project consuming `fast-forward/phpdoc-bootstrap-template
+^2.1.1`. Inspect `composer.json`, `composer.lock`, existing documentation commands
+and CI before editing. Run `composer show fast-forward/phpdoc-bootstrap-template`
+and `composer show phpdocumentor/shim` to check installed versions. If they fall
+outside this contract, inspect the matching version's documentation; do not
+upgrade dependencies just to use this skill. The template has no PHP namespace,
+container registration or application autoloader requirement: phpDocumentor
+loads its `template.xml` and Twig files.
+
+## Configure a guide homepage and API
+
+Prefer an existing DevTools route if the project already uses it; load
+[DevTools integration](references/dev-tools.md) for that case. Otherwise use the
+direct route below. Preserve existing source exclusions and project conventions.
+
+Prerequisites: PHP ^8.3, Composer, phpDocumentor's required extensions (including
+DOM/XML, mbstring and intl), and trusted project sources. Graphviz `dot` is needed
+for class diagrams. The template package alone does not install the generator.
+With authority to install the project's development tooling, review/merge the
+specific shim plugin approval and install:
+
+```sh
+composer config allow-plugins.phpdocumentor/shim true
+composer require --dev 'fast-forward/phpdoc-bootstrap-template:^2.1.1' 'phpdocumentor/shim:^3.9'
+```
+
+From the project root, create `phpdoc.xml`:
+
+```xml
+
+
+ Example documentation
+
+
+ build/phpdoc-cache
+
+
+
+ true
+ src
+
+
+ docs
+
+
+
+
+
+```
+
+Use the real PHP source directory in ``. `include-source` exposes source
+code in the generated public documentation; remove it if that is inappropriate.
+Never scan private configuration, credentials, `vendor/` or test data as sources.
+The example's single explicit `src` path bounds the scan.
+
+Create `docs/index.rst`:
+
+```rst
+Example documentation
+=====================
+
+Welcome to the project documentation.
+
+.. toctree::
+ :maxdepth: 2
+
+ guides/installation
+```
+
+Create `docs/guides/installation.rst`:
+
+```rst
+Installation
+============
+
+Install the project dependencies with Composer.
+
+.. code-block:: shell
+
+ composer install
+```
+
+Add a documented public PHP class in `src/` (one same-named class per file), or
+use the project's existing classes. A complete minimal class and these exact
+configuration/guide files are bundled under [examples](examples/phpdoc.xml).
+No application bootstrap is executed to render this example; phpDocumentor
+parses PHP sources. Use the existing Composer autoload configuration if the
+application itself needs to execute those classes.
+
+Generate from the project root:
+
+```sh
+vendor/bin/phpdoc --config phpdoc.xml
+test -f build/docs/index.html
+test -f build/docs/guides/installation.html
+test -f build/docs/css/base.css
+test -f build/docs/js/searchIndex.js
+test -f build/docs/images/fast-forward-logo-dark.svg
+test -f build/docs/images/dash-reading.png
+```
+
+`docs/index.rst` becomes `build/docs/index.html` because the guide output is `.`.
+Keep this guide index: the template's transformations do not generate an API-only
+root homepage. For an API-only project, provide a small landing guide or verify
+and configure a separate landing-page strategy. Do not promise an automatic
+fallback from the unused `index.html.twig` file.
+
+## Check the generated site
+
+Serve `build/docs` with the project's static preview tooling, or temporarily use
+`php -S 127.0.0.1:8080 -t build/docs`. Check the homepage, nested guide, API class,
+navigation, search, light/navy theme, narrow viewport and source links. Stop the
+preview server after use. Publish the entire output tree so relative links,
+search data and identity images survive nested hosting paths. Generation does
+not authorize a Pages deployment.
+
+For the bundled example, also run:
+
+```sh
+php /path/to/fast-forward-phpdoc-bootstrap-template/examples/verify.php build/docs
+```
+
+This verifier expects the bundled `Example` class and guide text. For a real
+project adapt checks to its API names; a passing command with no generated HTML
+is insufficient. It checks files/content, not browser behavior.
+
+## Diagnose and customize
+
+- Missing homepage: check the guide source, `docs/index.rst` and ``.
+- Missing API: inspect the `` source path, PHP extensions/exclusions and
+ phpDocumentor diagnostics; the template does not discover application sources.
+- Missing template/assets: confirm the installed package and actual vendor path.
+ For custom Composer `vendor-dir`, change both binary and template paths.
+- Stale output: use a new disposable cache/output directory to compare; do not
+ delete an existing public site or unrelated caches as a diagnostic step.
+- Invalid XML or generator failure: retain diagnostics, correct inputs and check
+ output again. For diagrams, inspect Graphviz availability separately.
+- Markdown guides: the minimal route uses reStructuredText. Markdown requires a
+ compatible phpDocumentor guide renderer; do not treat the template as a parser.
+- Styling: inspect the installed Twig inheritance and `css/base.css.twig`. Make
+ deliberate overrides in a project-owned complete template or maintained fork;
+ pass its path as the template. Editing `vendor/` is overwritten by Composer.
+ Copy runtime `data/` assets and `template.xml` transformations together. There
+ is no promised configuration key for arbitrary Twig overrides.
+
+For optional copying/synchronization of this skill, load
+[installation and lifecycle](references/installation.md). Installing the template,
+copying this skill and having an agent load it are separate steps.
diff --git a/resources/skills/fast-forward-phpdoc-bootstrap-template/examples/docs/guides/installation.rst b/resources/skills/fast-forward-phpdoc-bootstrap-template/examples/docs/guides/installation.rst
new file mode 100644
index 0000000..aac4768
--- /dev/null
+++ b/resources/skills/fast-forward-phpdoc-bootstrap-template/examples/docs/guides/installation.rst
@@ -0,0 +1,8 @@
+Installation
+============
+
+Install the project dependencies with Composer.
+
+.. code-block:: shell
+
+ composer install
diff --git a/resources/skills/fast-forward-phpdoc-bootstrap-template/examples/docs/index.rst b/resources/skills/fast-forward-phpdoc-bootstrap-template/examples/docs/index.rst
new file mode 100644
index 0000000..20ee8de
--- /dev/null
+++ b/resources/skills/fast-forward-phpdoc-bootstrap-template/examples/docs/index.rst
@@ -0,0 +1,9 @@
+Example documentation
+=====================
+
+Welcome to the project documentation.
+
+.. toctree::
+ :maxdepth: 2
+
+ guides/installation
diff --git a/resources/skills/fast-forward-phpdoc-bootstrap-template/examples/phpdoc.xml b/resources/skills/fast-forward-phpdoc-bootstrap-template/examples/phpdoc.xml
new file mode 100644
index 0000000..cad2ccb
--- /dev/null
+++ b/resources/skills/fast-forward-phpdoc-bootstrap-template/examples/phpdoc.xml
@@ -0,0 +1,19 @@
+
+
+ Example documentation
+
+
+ build/phpdoc-cache
+
+
+
+ true
+ src
+
+
+ docs
+
+
+
+
+
diff --git a/resources/skills/fast-forward-phpdoc-bootstrap-template/examples/src/Example.php b/resources/skills/fast-forward-phpdoc-bootstrap-template/examples/src/Example.php
new file mode 100644
index 0000000..342f30b
--- /dev/null
+++ b/resources/skills/fast-forward-phpdoc-bootstrap-template/examples/src/Example.php
@@ -0,0 +1,15 @@
+ 'Welcome to the project documentation.',
+ 'guides/installation.html' => 'composer install',
+ 'classes/Example-Documentation-Example.html' => 'greet',
+ 'css/base.css' => '#6d28d9',
+ 'js/searchIndex.js' => 'Example',
+ 'js/template.js' => 'fast-forward-documentation-theme',
+ 'images/fast-forward-logo-dark.svg' => ' "\x89PNG",
+] as $path => $expected) {
+ $file = $output . '/' . $path;
+ $contents = is_file($file) ? file_get_contents($file) : false;
+ if ($contents === false || !str_contains($contents, $expected)) {
+ fwrite(STDERR, "Missing or invalid generated artifact: {$path}\n");
+ exit(1);
+ }
+}
+echo "PASS: consumer homepage, nested guide, API, search and theme assets\n";
diff --git a/resources/skills/fast-forward-phpdoc-bootstrap-template/references/dev-tools.md b/resources/skills/fast-forward-phpdoc-bootstrap-template/references/dev-tools.md
new file mode 100644
index 0000000..e5b277d
--- /dev/null
+++ b/resources/skills/fast-forward-phpdoc-bootstrap-template/references/dev-tools.md
@@ -0,0 +1,75 @@
+# Existing Fast Forward DevTools integration
+
+Load when the consumer already uses `fast-forward/dev-tools` or asks about its
+reports workflow. This skill supports template ^2.1.1. Check the separate
+DevTools surface with `dev-tools reports:docs --help`: its template constraint
+`^2.0` alone does not guarantee this skill's minimum version. It also requires
+phpDocumentor shim `^3.9`.
+
+## Generate locally
+
+Run from the consumer using its existing DevTools launcher:
+
+```sh
+dev-tools reports:docs --help
+dev-tools reports:docs --source=docs --target=build/docs
+test -f build/docs/index.html
+```
+
+Use `vendor/bin/dev-tools` for a project-local binary. Keep the existing
+installation mode; the direct phpDocumentor route does not require DevTools.
+
+The command defaults to guides in `docs`, resolves API directories from the
+consumer's Composer autoload configuration and writes its own phpDocumentor XML
+in its managed cache. It includes ``, using
+`vendor/fast-forward/phpdoc-bootstrap-template` by default and resolving the
+preferred vendor location for its installation mode. `--template=/absolute/path`
+selects an alternative. `--source` chooses guides, not the API directory.
+
+A root `phpdoc.xml` does not override this generated configuration. Use supported
+command options, or invoke phpDocumentor directly with that XML for custom
+settings. Do not edit cached generated XML as permanent configuration.
+
+An explicitly requested missing guide directory fails. With the default path,
+DevTools may generate API-only output or skip successfully when neither API nor
+guides are detected. A success/skip message does not establish a root homepage:
+supply a guide index for this template and verify generated files. Use isolated
+cache/output paths for diagnosis.
+
+## Reports workflow
+
+The reusable `php-fast-forward/dev-tools/.github/workflows/reports.yml` invokes
+`dev-tools reports --target="${REPORTS_TARGET}"`, with `.dev-tools` as report root,
+alongside coverage and metrics. The docs command selects this template, rather
+than a separate template setting in YAML. The workflow also manages Pages, PR
+previews and cleanup: it has deployment permissions and side effects.
+
+For an already approved reusable-workflow integration, a minimal caller is:
+
+```yaml
+name: Reports
+on:
+ workflow_dispatch:
+permissions:
+ contents: write
+ pull-requests: write
+jobs:
+ reports:
+ uses: php-fast-forward/dev-tools/.github/workflows/reports.yml@35d27ee20066fd9e234d228bb866102c64c7ef1a
+```
+
+This pins the inspected source revision. Before adopting it, review its
+full job permissions, PHP/Composer setup, Pages settings and preview policy.
+Keep existing triggers; this example requires manual dispatch. Do not dispatch
+or deploy merely to test the skill. The reusable workflow can check out helper
+actions from `main`; pinning the caller does not necessarily freeze helpers.
+
+For generation-only CI, install approved locked dev dependencies, run
+`vendor/bin/phpdoc --config phpdoc.xml`, check files and retain artifacts under
+project policy. Pages publication is a separate maintainer decision.
+
+Inspected primary source entrypoints (recheck the installed version/selected ref):
+
+- [DocsCommand](https://github.com/php-fast-forward/dev-tools/blob/35d27ee20066fd9e234d228bb866102c64c7ef1a/src/Console/Command/DocsCommand.php)
+- [Generated XML](https://github.com/php-fast-forward/dev-tools/blob/35d27ee20066fd9e234d228bb866102c64c7ef1a/resources/phpdocumentor.xml)
+- [Reports workflow](https://github.com/php-fast-forward/dev-tools/blob/35d27ee20066fd9e234d228bb866102c64c7ef1a/.github/workflows/reports.yml)
diff --git a/resources/skills/fast-forward-phpdoc-bootstrap-template/references/installation.md b/resources/skills/fast-forward-phpdoc-bootstrap-template/references/installation.md
new file mode 100644
index 0000000..e631e05
--- /dev/null
+++ b/resources/skills/fast-forward-phpdoc-bootstrap-template/references/installation.md
@@ -0,0 +1,134 @@
+# Install the consumer skill
+
+Supports `fast-forward/phpdoc-bootstrap-template ^2.1.1`; earlier versions are
+outside this contract. Inspect the installed version and source directory:
+`vendor/fast-forward/phpdoc-bootstrap-template/resources/skills/fast-forward-phpdoc-bootstrap-template`.
+If absent, inspect that distribution or obtain the skill from a reviewed
+immutable revision. Do not upgrade application dependencies just for instructions.
+Composer-shipped files, a discovery copy and agent activation are separate steps.
+Prefer project scope for team review; global use is an explicit personal choice.
+
+## Optional llm/skills ^1.15 project route
+
+Requires Composer, compatible PHP, the installed donor and the consumer's approval
+to execute the development plugin. Merge this `skills.json` before first
+installation/sync, preserving existing settings and intentional aliases:
+
+```json
+{
+ "target": ".agents/skills",
+ "aliases": [],
+ "discovery": false,
+ "auto-sync": true,
+ "vendor-sources": false,
+ "dependencies": {
+ "composer": {
+ "trusted": ["fast-forward/phpdoc-bootstrap-template"],
+ "trusted-replace": true
+ }
+ }
+}
+```
+
+With the project's specific plugin trust decision:
+
+```sh
+composer config allow-plugins.llm/skills true
+composer require --dev 'llm/skills:^1.15'
+composer skills:show
+```
+
+Preserve other approvals. The donor's `suggest` neither installs nor approves the
+plugin. Commit intended configuration/lockfile under project policy. Approved
+install/update synchronizes the donor into
+`.agents/skills/fast-forward-phpdoc-bootstrap-template`; no cleanup hook is needed.
+For explicit sync, set `auto-sync:false` before plugin installation:
+
+```sh
+composer skills:show
+composer skills:update fast-forward/phpdoc-bootstrap-template --dry-run
+composer skills:update fast-forward/phpdoc-bootstrap-template
+```
+
+A named package intentionally selects/trusts it for that run. With Composer
+2.10.3 and llm/skills 1.15.0, `--no-scripts` alone does not suppress automatic
+sync. Use `auto-sync:false`, or `--no-plugins` to prevent plugin execution.
+
+Copies are donor-managed: same-path files overwrite local edits; extra local
+files and files removed upstream can remain. Removing donor or plugin leaves
+copies behind. Inspect diffs and record source versions on updates. Keep local
+instructions under a separate skill name.
+
+Preview cleanup only: `composer skills:update --clean --dry-run`. Unscoped clean
+can delete handwritten skills. Scoped clean reinstalls selected donors; it does
+not identify an already removed donor. Inventory/archive the exact stale package
+outside discovery before authorized cleanup. Never add a blanket clean hook.
+
+## Manual project copy or explicit global copy
+
+Copy the complete package, refusing existing directories and dangling symlinks:
+
+```sh
+skill_source="vendor/fast-forward/phpdoc-bootstrap-template/resources/skills/fast-forward-phpdoc-bootstrap-template"
+skill_target=".agents/skills/fast-forward-phpdoc-bootstrap-template"
+test -f "$skill_source/SKILL.md" &&
+test ! -e "$skill_target" && test ! -L "$skill_target" &&
+mkdir -p "$(dirname "$skill_target")" &&
+cp -R "$skill_source" "$skill_target"
+```
+
+For explicit global Codex scope choose
+`$HOME/.agents/skills/fast-forward-phpdoc-bootstrap-template` as `skill_target`.
+For Claude Code choose `.claude/skills/fast-forward-phpdoc-bootstrap-template`
+or its home counterpart. Verify host discovery roots and avoid duplicate copies.
+Do not symlink into replaceable `vendor/` files.
+
+For update/removal, archive only the selected package outside discovery:
+
+```sh
+skill_backup="$HOME/.agent-skill-backups/fast-forward-phpdoc-bootstrap-template-$(date +%Y%m%d%H%M%S)-$$"
+test -d "$skill_target" && test ! -L "$skill_target" &&
+test ! -e "$skill_backup" && test ! -L "$skill_backup" &&
+mkdir -p "$(dirname "$skill_backup")" &&
+mv "$skill_target" "$skill_backup"
+```
+
+For update review the new donor and repeat the guarded copy. To roll back,
+archive any replacement first, restore the complete saved directory to its
+original destination and refresh the session. For removal leave it outside
+discovery. Managed copies may return on sync until donor/trust selection changes.
+Never put backups under a discovery root.
+
+## Optional pinned Skills CLI
+
+Requires Node.js 22.20.0+, npm and Git for repository sources. Review the tool
+before execution. The local donor avoids a moving remote source:
+
+```sh
+npx --yes skills@1.7.2 add ./vendor/fast-forward/phpdoc-bootstrap-template/resources/skills/fast-forward-phpdoc-bootstrap-template --skill fast-forward-phpdoc-bootstrap-template --agent codex --copy --yes
+npx --yes skills@1.7.2 list --agent codex
+```
+
+For a repository source set `SKILL_REF` to a reviewed full commit SHA and use
+`https://github.com/php-fast-forward/phpdoc-bootstrap-template/tree/$SKILL_REF/resources/skills/fast-forward-phpdoc-bootstrap-template`
+as the source argument. Choose the actual host (`claude-code` for Claude Code).
+Add `--global` to both add/list commands only for global scope. `--copy` avoids
+links into Composer-managed files. Back up edits before replacing with a reviewed
+source; commit intended copies/CLI lockfiles. Remove only the selected name/scope:
+
+```sh
+npx --yes skills@1.7.2 remove fast-forward-phpdoc-bootstrap-template --agent codex --yes
+# Explicit global alternative:
+npx --yes skills@1.7.2 remove fast-forward-phpdoc-bootstrap-template --agent codex --global --yes
+```
+
+A globally installed Composer plugin is not global host skill installation.
+After any route inspect files, refresh the agent session, confirm discovery and
+request a bounded documentation task. Copy success does not prove activation.
+
+The Skills CLI 1.7.2 removal report is not proof that the canonical project
+`.agents/skills` directory disappeared. A Codex project exercise reported one
+removal while that copied package remained. Inspect the actual target and CLI
+lockfiles afterwards. If an obsolete copy remains, verify that no other host
+uses it, then archive only that selected directory outside discovery using the
+manual recovery procedure above. Do not run a blanket clean to compensate.
diff --git a/tests/verify-consumer-skill.php b/tests/verify-consumer-skill.php
new file mode 100644
index 0000000..aa338bc
--- /dev/null
+++ b/tests/verify-consumer-skill.php
@@ -0,0 +1,43 @@
+load($example . '/phpdoc.xml', LIBXML_NONET)) {
+ throw new RuntimeException('Cannot load consumer configuration.');
+}
+$xpath = new DOMXPath($config);
+$xpath->query('/phpdocumentor/paths/output')->item(0)->textContent = $temporary . '/output';
+$xpath->query('/phpdocumentor/paths/cache')->item(0)->textContent = $temporary . '/cache';
+$xpath->query('/phpdocumentor/template')->item(0)->setAttribute('name', $template);
+foreach ($xpath->query('//source') as $source) {
+ $source->setAttribute('dsn', $example);
+}
+if ($config->save($temporary . '/phpdoc.xml') === false) {
+ throw new RuntimeException('Cannot save consumer configuration.');
+}
+foreach ([
+ [PHP_BINARY, $root . '/vendor/bin/phpdoc', '--config', $temporary . '/phpdoc.xml'],
+ [PHP_BINARY, $example . '/verify.php', $temporary . '/output'],
+] as $command) {
+ $process = proc_open($command, [STDIN, STDOUT, STDERR], $pipes, $example);
+ if (!is_resource($process)) {
+ throw new RuntimeException('Cannot start consumer validation.');
+ }
+ $result = proc_close($process);
+ if ($result !== 0) {
+ exit($result === -1 ? 1 : $result);
+ }
+}
+printf("Consumer output: %s/output\n", $temporary);