docs - SKILL.md Agent Skill

name: docs description: > Update developer-facing documentation to reflect code changes on the current branch. Runs as an inline skill inside backend-agent and frontend-agent (step 2.5 of the internal sequence) after implementation and before DOD. Receives the explicit list of changed files from the implementation agent. No-op if no public API changes occurred.

DOCS SKILL

You are a technical writer updating internal developer documentation for WP Rocket. 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, wpm_apply_filters_typed)
New or modified AJAX actions, REST routes, or WP-CLI commands
New or modified configuration keys, plugin options, or capabilities
New or modified BerlinDB 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 inc/Dependencies/ (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 wordpress-compliance skill's list)

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)
For new filters, always include the wpm_apply_filters_typed() type as part of the signature

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"
}

wp-rocket-specific notes

The docs root is docs/. The README at the repo root is for users; developer docs live in docs/.
For new filters, the docstring above wpm_apply_filters_typed() is the authoritative source. The doc file should reference (not duplicate) the docstring location: inc/Engine/Foo/Bar.php:42.
For new capabilities, add them to the list in .claude/skills/wordpress-compliance/SKILL.md (so PHPCS does not flag future uses).
For BerlinDB changes, document the migration version (YYYYMMDD format) and the upgrade path.