[skills] Add packaged AGENTS.md skill (#128) (#129)

* [skills] Add create-agentsmd packaged skill (#128)

* Update wiki submodule pointer for PR #129

* [agents] Add agents-maintainer role (#128)

* [agents] Add canonical reference guidance (#128)

* [docs] Refresh AGENTS.md navigation guidance (#128)

---------

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: coisa

.agents/agents/agents-maintainer.md

@@ -0,0 +1,48 @@
+---
+name: agents-maintainer
+description: Keep repository AGENTS.md guidance aligned with the current Fast Forward DevTools workflows and packaged agent surfaces.
+primary-skill: create-agentsmd
+supporting-skills: []
+---
+
+# agents-maintainer
+
+## Purpose
+
+Maintain repository-root `AGENTS.md` guidance so coding agents can rely on
+accurate setup, workflow, testing, and contribution instructions.
+
+## Responsibilities
+
+- Refresh `AGENTS.md` when repository commands, workflows, or packaged skills
+  change.
+- Keep agent-facing guidance concise, specific, and aligned with the current
+  checkout.
+- Preserve the repository's existing instruction structure and terminology.
+- Cross-check referenced commands, paths, and generated artifacts before
+  finalizing updates.
+- Add or refresh notable repository references such as `README.md`, `docs/`,
+  workflow files, and other canonical local entrypoints when they help agents
+  navigate the project.
+
+## Use When
+
+- A PR changes setup, development, testing, sync, or contribution workflows
+  documented in `AGENTS.md`.
+- The repository adds, removes, or renames packaged skills or project agents.
+- `AGENTS.md` drifted from the current repository behavior.
+
+## Boundaries
+
+- Do not duplicate or replace `README.md` when a human-facing doc update is the
+  actual need.
+- Do not invent workflows or commands that are not present in the checkout.
+- Do not rewrite unrelated docs trees when only `AGENTS.md` needs maintenance.
+
+## Primary Skill
+
+- `create-agentsmd`
+
+## Supporting Skills
+
+- None by default.

.agents/skills/create-agentsmd/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: create-agentsmd
+description: Generate or refresh repository-level AGENTS.md files with actionable setup, workflow, testing, style, and contribution guidance for coding agents. Use when a repository is missing AGENTS.md, when an existing AGENTS.md is stale, or when agent-facing project instructions need to be aligned with the current checkout.
+---
+
+# Fast Forward AGENTS.md
+
+Use this skill to create or refresh a repository-root `AGENTS.md` that helps
+coding agents work effectively in the current project. Keep the file specific to
+the checked-out repository, verify commands and paths before writing them, and
+prefer concise instructions over generic explanations.
+
+## Workflow
+
+1. Inspect the repository first: language, package manager, build and test
+   entrypoints, CI workflows, docs, and any existing `AGENTS.md`.
+2. Decide whether to create or update:
+   - create `AGENTS.md` at the repository root when the file is missing;
+   - update the existing file in place when it already contains repository-specific
+     guidance worth preserving.
+3. Capture only repository-relevant instructions that an agent would not safely
+   infer from code alone.
+4. Verify every command, path, workflow name, and generated artifact reference
+   against the current checkout before finalizing the file.
+5. Keep the result aligned with the public `agents.md` guidance without copying
+   generic filler into the repository.
+
+## Required Coverage
+
+- Project overview and architecture cues that affect implementation work
+- Setup, installation, and local development commands
+- Testing commands, focused test patterns, and quality gates
+- Code style, file-organization, and naming expectations that matter in review
+- Build, release, or deployment behavior when the repository exposes one
+- Pull request or contribution rules when they are discoverable from local files
+- Notable repository references such as `README.md`, `docs/`, workflow files, or
+  generated-output locations when those links help an agent navigate the project
+
+## Writing Rules
+
+- Use direct, actionable language aimed at another coding agent.
+- Prefer exact commands in backticks instead of vague descriptions.
+- Mention real paths, scripts, workflow files, and generated outputs.
+- Keep `AGENTS.md` as a companion to `README.md`, not a duplicate of it.
+- Add links or path references to canonical repository surfaces when they are
+  useful entrypoints for agents, especially `README.md`, `docs/`, `.github/workflows/`,
+  and other notable local documentation or output directories.
+- Call out monorepo or nested-`AGENTS.md` precedence only when it actually applies.
+- Preserve valid repository-specific guidance when updating an existing file.
+- Do not invent commands, services, environment variables, or workflows that are
+  not present in the checkout.
+
+## Reference Guide
+
+| Need | Reference |
+|------|-----------|
+| Section planning and optional coverage | [references/content-outline.md](references/content-outline.md) |
+| Final quality checks before finishing the file | [references/content-outline.md](references/content-outline.md) |
+
+## Anti-patterns
+
+- Do not paste a generic AGENTS template without inspecting the repository.
+- Do not describe tools or frameworks that are not present in the checkout.
+- Do not duplicate large sections of `README.md` when a short cross-reference is
+  enough.
+- Do not leave placeholder text, TODO markers, or fake commands in the file.
+- Do not rewrite a good existing `AGENTS.md` from scratch when a focused refresh
+  is enough.

.agents/skills/create-agentsmd/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Fast Forward AGENTS.md"
+  short_description: "Create AGENTS.md files for repositories"
+  default_prompt: "Use $create-agentsmd to analyze this repository and write or refresh a focused AGENTS.md file at the project root."

.agents/skills/create-agentsmd/references/content-outline.md

@@ -0,0 +1,52 @@
+# AGENTS.md Content Outline
+
+Use this reference when planning or reviewing a repository-level `AGENTS.md`.
+
+## Core Sections
+
+Include the sections that materially fit the repository:
+
+- `Project Overview`
+- `Setup Commands`
+- `Development Workflow`
+- `Testing Instructions`
+- `Code Style`
+- `Build and Deployment`
+
+## Optional Sections
+
+Add these only when the repository clearly supports them:
+
+- `Security Considerations`
+- `Monorepo Instructions`
+- `Pull Request Guidelines`
+- `Debugging and Troubleshooting`
+- `Additional Notes`
+
+## What to Gather Before Writing
+
+- Package manager and install command
+- Main build, dev, and test entrypoints
+- Focused test commands or patterns
+- Lint, format, static-analysis, or code-style commands
+- CI workflow locations in `.github/workflows/`
+- Deployment, publishing, or release commands if present
+- Canonical human-facing entrypoints such as `README.md`, `docs/`, wiki content,
+  support files, or notable generated-output directories that agents may need to
+  consult
+- Existing repository conventions from `README.md`, `composer.json`, `package.json`,
+  `Makefile`, `pyproject.toml`, or similar project files
+
+## Quality Checklist
+
+- Every command exists in the checked-out repository.
+- Every referenced path is real and spelled correctly.
+- The file explains what agents need to know, not broad product marketing.
+- The guidance complements `README.md` instead of repeating it wholesale.
+- The instructions mention generated artifacts, sync workflows, or docs outputs
+  when agents can affect them.
+- Helpful canonical references such as `README.md`, `docs/`, workflow files, or
+  other notable repository paths are called out when they improve navigation.
+- The file uses concrete repository vocabulary rather than generic advice.
+- The final result is specific enough that another agent could start work without
+  guessing the workflow.

.github/wiki

@@ -45,6 +45,19 @@ composer dev-tools reports       # Generate docs frontpage and reports
 composer dev-tools:sync         # Sync scripts, GitHub Actions, .editorconfig, wiki
 ```
 
+**Notable Specialized Commands:**
+
+- `composer skills`: Synchronize packaged skills into consumer `.agents/skills`
+- `composer funding`: Sync funding metadata between `composer.json` and `.github/FUNDING.yml`
+- `composer codeowners`: Generate `.github/CODEOWNERS` from repository metadata
+- `composer gitattributes`: Manage export-ignore rules in `.gitattributes`
+- `composer gitignore`: Synchronize managed `.gitignore` content
+- `composer license`: Generate or refresh repository `LICENSE` files
+- `composer dependencies`: Run dependency analysis workflows
+- `composer metrics`: Generate PhpMetrics reports and related artifacts
+- `composer update-composer-json`: Normalize managed `composer.json` settings
+- `composer changelog:entry|check|next-version|promote|show`: Manage changelog-driven release workflows
+
 ## Testing Instructions
 
 ```bash
@@ -91,7 +104,7 @@ composer dev-tools tests -- --coverage=public/coverage
 
 - Source code: `src/` (PSR-4: `FastForward\DevTools\`)
 - Tests: `tests/` (PSR-4: `FastForward\DevTools\Tests\`)
-- Commands: `src/Command/`
+- Commands: `src/Console/Command/`
 - PHPUnit events: `src/PhpUnit/Event/`
 - Rector rules: `src/Rector/`
 - Composer plugin: `src/Composer/`
@@ -112,7 +125,15 @@ composer dev-tools tests -- --coverage=public/coverage
 
 ## Build and Deployment
 
-This is a Composer plugin - no build step required. The package is published to Packagist.
+This repository ships a Composer plugin plus the local `bin/dev-tools` binary,
+so there is no separate frontend or asset build step. The package is published
+to Packagist, while consumer repositories adopt workflows, packaged skills, and
+other managed assets through `composer dev-tools:sync`.
+
+Release and publishing behavior is driven primarily through
+`.github/workflows/changelog.yml`, `reports.yml`, and `wiki.yml`, with packaged
+skills living under `.agents/skills/` and mirrored project-agent prompts under
+`.agents/agents/`.
 
 **Package Details:**
 
@@ -122,8 +143,6 @@ This is a Composer plugin - no build step required. The package is published to
 
 ## Pull Request Guidelines
 
-**Title Format:** `[<area>] Brief description (#<issue-number>)`
-
 **Required Checks:**
 
 ```bash
@@ -138,6 +157,20 @@ composer dev-tools
 - PHPDoc must be valid
 - Coverage must meet threshold
 - Rector should handle refactoring automatically
+- Follow `.github/pull_request_template.md` and include issue linkage,
+  verification notes, documentation/generated-output review, and changelog
+  status
+
+## Canonical References
+
+- `README.md`: high-level command surface, architecture overview, and consumer-facing context
+- `docs/commands/`: command-specific behavior and option details
+- `docs/usage/` and `docs/internals/`: workflow, reporting, release, and implementation notes
+- `.github/workflows/`: CI and release automation truth, especially `tests.yml`, `reports.yml`, `wiki.yml`, and `changelog.yml`
+- `.github/pull_request_template.md`: expected PR structure and reviewer checklist
+- `.agents/skills/`: packaged procedural skills shipped to consumer repositories
+- `.agents/agents/`: repository-specific role prompts mirrored through `.github/agents`
+- `.github/wiki`: generated or synchronized wiki content published by repo workflows
 
 ## Additional Notes
 
@@ -150,6 +183,7 @@ composer dev-tools
 ## Skills Usage
 
 - **Creating/Updating Tests**: Use skill `phpunit-tests` in `.agents/skills/phpunit-tests/` for PHPUnit tests with Prophecy
+- **Creating/Refreshing AGENTS.md**: Use skill `create-agentsmd` in `.agents/skills/create-agentsmd/` to generate or update repository-root AGENTS instructions for coding agents
 - **Generating Documentation**: Use skill `sphinx-docs` in `.agents/skills/sphinx-docs/` for Sphinx documentation in `docs/`
 - **Updating README**: Use skill `package-readme` in `.agents/skills/package-readme/` for generating README.md files
 - **Updating PHPDoc / PHP Style**: Use skill `phpdoc-code-style` in `.agents/skills/phpdoc-code-style/` for PHPDoc cleanup and repository-specific PHP formatting
@@ -165,6 +199,7 @@ procedural source of truth.
 
 - Use `issue-editor` for issue drafting, refinement, comments, updates, and closure workflows.
 - Use `issue-implementer` for issue-to-branch-to-PR execution.
+- Delegate to `agents-maintainer` when repository `AGENTS.md` guidance needs to be created, refreshed, or realigned with current workflows.
 - Delegate to `test-guardian` whenever behavior changes, regressions, or missing coverage are involved.
 - Delegate to `php-style-curator` for PHPDoc cleanup, file-header normalization, and repository style conformance.
 - Delegate to `readme-maintainer` when public commands, installation, usage, links, or badges change.

AGENTS.md

@@ -10,6 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Add CODEOWNERS generation and sync support for consumer repositories (#67)
+- Package a create-agentsmd skill for repository-level AGENTS.md authoring (#128)
+- Add an agents-maintainer project agent for ongoing AGENTS.md upkeep (#128)
 
 ## [1.13.0] - 2026-04-19
 

CHANGELOG.md

@@ -224,7 +224,10 @@ 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.
+so agents can discover the packaged skills shipped with this repository,
+including workflows for GitHub issue/PR handling, changelog maintenance, PHP
+quality tasks, Sphinx docs, README generation, and repository `AGENTS.md`
+authoring.
 
 ## 🏗️ Architecture