getnao/sylph / .claude/skills/update-docs
update-docs
VerifiedDetect user-facing features in recently merged PRs and open a PR in the docs repo adding the missing documentation.
Update Docs
When the user runs /update-docs, scan recently merged PRs for user-facing
changes and open a documentation PR.
MCP connectors
| Connector | Purpose |
|---|---|
| GitHub | Read merged PRs, create docs PRs |
Prerequisites
Both repos must be cloned locally:
- Product repo: the main codebase (configured in CONTEXT.md)
- Docs repo: the documentation site (configured in CONTEXT.md or asked on first run)
State file: agents/cmo/_state/docs_last_refresh.txt (plain text, single ISO date).
Step 1: Determine the PR window
- Read
agents/cmo/_state/docs_last_refresh.txtif it exists - If the file exists, use its date as
SINCE - If it does NOT exist (first run), use
today - 15 daysasSINCE - Record
TODAYas the date to write back at the end
Step 2: List merged PRs
gh pr list -R <product-repo> \
--state merged \
--search "merged:>=<SINCE>" \
--limit 100 \
--json number,title,url,mergedAt,body,author,files
Keep the full list - every PR appears in the final summary, even those that don't need docs.
Step 3: Classify each PR
For each PR, decide: user-facing or not?
User-facing (needs docs):
- New feature in the UI, CLI, API, or configuration
- New command, flag, setting, integration, or UI element
- Behavior change that affects how users interact with the product
- New capability that a user would want to know about
- Anything that belongs in release notes
NOT user-facing (skip):
- Refactors, internal cleanups, tests, CI, infra
- Dependency bumps, lockfile updates
- Backend-only changes invisible to users
- Bug fixes that restore already-documented behavior
- Brand, marketing, or internal tooling changes
When unsure, read the PR body and changed files. If still ambiguous, err on no docs and note it in the summary.
Step 4: Fetch current docs state
Pull latest from the docs repo:
cd <docs-repo> && git checkout main && git pull
Before writing any new doc, search the repo for existing coverage (grep on keywords from the PR title/body). If a relevant page exists, update it instead of creating a new one.
Step 5: Write the docs
For each user-facing PR that needs docs:
- Identify the right section and subfolder
- Either update an existing page or create a new one
- Follow the style of neighboring pages - tone, frontmatter, headings, code blocks
- If you create a new page, add it to the navigation/sitemap config
- Keep docs factual and concise - no marketing voice, direct tone
- Only document what actually shipped - read the PR diff if the description is thin. Never invent behavior.
Step 6: Create a new branch and PR
cd <docs-repo>
git checkout -b docs/refresh-<TODAY>
git add <changed files>
git commit -m "docs: refresh for PRs merged since <SINCE>"
git push -u origin docs/refresh-<TODAY>
gh pr create -R <docs-repo> \
--title "docs: refresh for PRs merged since <SINCE>" \
--body "<PR summary - see template below>"
PR summary template
Every PR from Step 2 must appear in the list, in merge order. Use these exact shapes:
- PR merged #123 <PR title> - no docs added
- PR merged #124 <PR title> - added docs - <one-line description of what was documented and where>
No other bullet shapes. No section grouping. Keep it a flat list.
If zero PRs were user-facing, skip PR creation and just update the state file.
Step 7: Log the refresh
Write TODAY (ISO date) to agents/cmo/_state/docs_last_refresh.txt:
echo "<TODAY>" > agents/cmo/_state/docs_last_refresh.txt
git add agents/cmo/_state/docs_last_refresh.txt
git commit -m "chore(cmo): log docs refresh <TODAY>"
git push
The next run picks up from this date.
Step 8: Report back
Return to the user:
- Docs PR URL (or "no user-facing PRs this run" if none)
- Number of PRs reviewed / number that got docs
- The full PR summary list (same content as the PR body)
- New last-refresh date
Guardrails
- Never modify source code - docs changes only
- Link to source PRs in the docs PR description
- One docs PR per batch - group related changes together
- Flag ambiguity - if a PR's user impact is unclear, ask before documenting
- Never invent features - only document what the diff shows
Self-improvement
After the docs PR is reviewed and merged:
- If the reviewer requests changes to doc structure, tone, or coverage scope, update the relevant step in this skill file
- If a PR classification was wrong (documented something that didn't need docs, or missed something that did), refine the classification guide in Step 3
- Update
_insights.mdwith patterns: which PRs consistently need docs, which doc styles get approved without changes - If the PR summary format needs adjustment based on reviewer feedback, update the template in Step 6
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 196k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |