docs - SKILL.md Agent Skill

name: docs description: Update developer-facing documentation to reflect code changes on the current branch.

DOCS SKILL

You are a technical writer updating internal developer documentation for this project. This skill runs inline inside the implementation agent and receives the list of changed files explicitly — do not infer scope from git.

When to run / when to skip

Run this skill if the implementation touched any of the following:

New or modified WordPress hooks (apply_filters, do_action, typed filter helpers)
New or modified AJAX actions, REST routes, or WP-CLI commands
New or modified configuration keys, plugin options, or capabilities
New or modified database tables, columns, or schemas
New or modified ServiceProvider bindings exposing a new public service
New or modified Subscriber get_subscribed_events() returns (new hooks subscribed)
New or modified plugin metadata (header constants, dependencies)
New or modified events / callbacks consumed by external integrations

Skip this skill (return no-op) if:

Implementation was internal refactoring only (private methods, no public surface change)
Only tests, build artifacts, or vendored code changed
Spec explicitly flags "no public API change"

When skipping, return:

{ "status": "SKIP", "reason": "No public API changes in this implementation" }

Process

Step 1 — Read the changed files

Use the Read tool on the explicit list provided by the implementation agent. Do not run git diff to discover scope — the agent already knows what changed.

Identify:

New or modified public API endpoints, hooks, AJAX actions, REST routes
Removed endpoints, hooks, or option keys (document as deprecated or removed)
New or modified capabilities (from the project's compliance skill)

Step 2 — Review existing documentation

find docs/ -name '*.md' -o -name '*.mdx' 2>/dev/null | head -50
ls -la README.md

Read relevant existing doc files. Understand what is already covered and what needs updating.

Step 3 — Identify gaps

For each significant public-facing change:

Is it documented? Is the existing doc current?
Which doc file should it go in? (existing or new)
For new hooks, follow the existing hook documentation convention (filter name, parameter types, return type, example).

Step 4 — Update documentation

For each gap:

Find the correct existing file, or create a new one under docs/
Write or update the content
Stage the changes alongside the implementation commit (the implementation agent handles the actual git add / git commit).

Style guidelines:

Purpose: help engineers get a high-level understanding and find the relevant code fast
Tone: neutral, technical, not promotional
Structure: prose for explanations; bullets for parallel items; numbered steps for flows
Length: concise — a few hundred lines per file max; split by topic if large
Avoid embedding large code blocks; prefer referencing class/function names with their full namespace
Document the current state, not the change history (the changelog handles history)

Step 5 — Return

{
  "status": "DONE|SKIP",
  "files_updated": ["docs/api/reports.md", "docs/configuration.md"],
  "files_created": ["docs/api/notifications.md"],
  "reason": "Populated if SKIP"
}

Notes

The docs root is docs/. The README at the repo root is for users; developer docs live in docs/.
For new capabilities, add them to the Project Config block in .claude/skills/orchestrator/SKILL.md under the CAPABILITIES entry so the compliance skill and PHPCS do not flag future uses.
For database schema changes, document the migration version and upgrade path.