forked from bchanot/claude
refactor(skills): extract skill logic into standalone agent files
Skills now delegate to agent .md files instead of embedding logic inline. Added new agents (bugfixer, code-cleaner, commit-changer, doc-syncer, feater, hotfixer, seo-analyzer) and new skills (code-clean, doc, seo). Replaced /readme with /doc (broader scope). Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
bastien
@@ -0,0 +1,257 @@
|
||||
---
|
||||
name: doc-syncer
|
||||
description: Detect stale documentation by cross-referencing git history against doc files. Audit, report, and patch. Supports full audit and automatic (silent) mode.
|
||||
tools: Read, Write, Edit, Bash, Grep, Glob
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
# DOC SYNCER
|
||||
|
||||
## GOAL
|
||||
Keep documentation in sync with code. Detect drift, report it,
|
||||
and patch what can be patched automatically. Never invent content
|
||||
-- only reflect what actually changed in code.
|
||||
|
||||
## REQUEST
|
||||
$ARGUMENTS
|
||||
|
||||
---
|
||||
|
||||
## MODE DETECTION
|
||||
|
||||
Parse `$ARGUMENTS` to determine mode:
|
||||
|
||||
- **AUTO MODE** — `$ARGUMENTS` starts with `auto-mode scope:`
|
||||
Jump directly to AUTO MODE section below.
|
||||
- **FULL AUDIT** — anything else (empty, file list, description)
|
||||
Run the full audit workflow below.
|
||||
|
||||
---
|
||||
|
||||
## FULL AUDIT
|
||||
|
||||
### STEP 1 — DISCOVER DOCS
|
||||
|
||||
Find all documentation files in the project:
|
||||
|
||||
```bash
|
||||
# Standard doc files at root
|
||||
ls README.md CLAUDE.md INSTALL.md CONFIGURE.md USAGE.md \
|
||||
CONTRIBUTING.md CHANGELOG.md 2>/dev/null
|
||||
|
||||
# Docs directory
|
||||
find docs -name '*.md' 2>/dev/null | head -50
|
||||
```
|
||||
|
||||
Store the list as `DOC_FILES`.
|
||||
If no docs found at all, report and stop.
|
||||
|
||||
### STEP 2 — DETECT DRIFT PER DOC
|
||||
|
||||
For each file in `DOC_FILES`:
|
||||
|
||||
1. Get its last modification date:
|
||||
```bash
|
||||
git log -1 --format=%aI -- <file>
|
||||
```
|
||||
|
||||
2. Get all commits touching the codebase since that date:
|
||||
```bash
|
||||
git log --oneline --since="<date>" \
|
||||
--diff-filter=AMRD -- '*.py' '*.ts' '*.js' '*.tsx' \
|
||||
'*.jsx' '*.rs' '*.go' '*.java' '*.c' '*.cpp' '*.h' \
|
||||
'*.toml' '*.json' '*.yaml' '*.yml' '*.env.example' \
|
||||
'Dockerfile' 'docker-compose.yml' 'Makefile' \
|
||||
'package.json' 'Cargo.toml' 'pyproject.toml'
|
||||
```
|
||||
Adapt glob list to the project's actual stack.
|
||||
|
||||
3. For each commit, extract what changed:
|
||||
```bash
|
||||
git show --stat --name-only <hash>
|
||||
git diff <hash>~1..<hash> --unified=3
|
||||
```
|
||||
Look for: new/renamed/deleted functions, new config keys,
|
||||
new CLI flags, changed endpoints, breaking changes,
|
||||
dependency adds/removes/upgrades.
|
||||
|
||||
4. Cross-reference each change against the doc's content.
|
||||
Read the doc file and check if the change is reflected.
|
||||
|
||||
### STEP 3 — ANALYSIS PER DOC TYPE
|
||||
|
||||
Apply doc-specific checks:
|
||||
|
||||
**README.md**
|
||||
- Install steps: do commands still match package manifest and CLAUDE.md?
|
||||
- Feature list: does it cover current functionality?
|
||||
- Examples: do code snippets match current API/signatures?
|
||||
- Prerequisites: are versions and tools still accurate?
|
||||
- Docker section: present if Docker is used, absent if not?
|
||||
|
||||
**CLAUDE.md**
|
||||
- Norms: do coding conventions match current project patterns?
|
||||
- Stack description: still accurate?
|
||||
- Commands (build/test/lint): still runnable?
|
||||
- Folder tree: matches actual structure?
|
||||
- New patterns worth documenting?
|
||||
|
||||
**INSTALL.md / CONFIGURE.md**
|
||||
- Environment variables: do all referenced vars exist in .env.example?
|
||||
- Install steps: match current dependency manager and versions?
|
||||
- Configuration steps: reference current config file format?
|
||||
|
||||
**USAGE.md**
|
||||
- CLI flags and commands: match current implementation?
|
||||
- API endpoints: match current routes?
|
||||
- Code examples: match current signatures?
|
||||
|
||||
**CONTRIBUTING.md**
|
||||
- Branch workflow: still accurate?
|
||||
- Test commands: still correct?
|
||||
- Code style rules: still enforced?
|
||||
|
||||
**CHANGELOG.md**
|
||||
- Latest code changes: do they have corresponding entries?
|
||||
- Entry format: consistent with existing style?
|
||||
|
||||
**docs/**/*.md**
|
||||
- Technical accuracy: do references to code match reality?
|
||||
- Links: do internal links point to existing files/sections?
|
||||
|
||||
**Inline comments (JSDoc, docstrings, rustdoc, godoc)**
|
||||
- Only check files that changed since last doc update.
|
||||
- `@param` / `@return` types: match actual function signatures?
|
||||
- Description: still accurate after the change?
|
||||
|
||||
### STEP 4 — REPORT
|
||||
|
||||
Present a structured report:
|
||||
|
||||
```
|
||||
DOC SYNC REPORT
|
||||
===============
|
||||
|
||||
## <filename>
|
||||
Last updated: <date> (<N commits since>)
|
||||
|
||||
1. [AUTO] <section> — <what's wrong>
|
||||
Commit: <hash> — <message>
|
||||
Fix: <proposed change>
|
||||
|
||||
2. [HUMAN] <section> — <what's wrong>
|
||||
Commit: <hash> — <message>
|
||||
Reason: <why this needs human judgment>
|
||||
|
||||
---
|
||||
(repeat for each doc with drift)
|
||||
```
|
||||
|
||||
Tagging rules:
|
||||
- **AUTO** — factual update Claude can write: command changed,
|
||||
var renamed, param added, version bumped, file moved.
|
||||
- **HUMAN** — needs business context or judgment: feature
|
||||
description wording, architecture rationale, changelog entry
|
||||
content, new section creation.
|
||||
|
||||
CHANGELOG entries are always tagged HUMAN — version bump and
|
||||
release notes are human decisions.
|
||||
|
||||
If no drift detected in any doc: print
|
||||
`DOC SYNC: all docs current` and stop.
|
||||
|
||||
### STEP 5 — VALIDATION GATE (mandatory stop)
|
||||
|
||||
```
|
||||
DOC SYNC — VALIDATION GATE
|
||||
AUTO items : <count> (Claude will patch these)
|
||||
HUMAN items: <count> (listed above for your review)
|
||||
|
||||
Apply AUTO patches? (yes / select items / cancel)
|
||||
```
|
||||
|
||||
Wait for explicit approval. Do not proceed without it.
|
||||
|
||||
### STEP 6 — PATCH
|
||||
|
||||
Apply only approved AUTO items:
|
||||
- Surgical edits only. Preserve existing structure and tone.
|
||||
- For each edit, use the Edit tool with minimal old_string/new_string.
|
||||
- Do not rewrite surrounding prose. Do not reformat.
|
||||
- If a doc section doesn't exist yet for a change, propose creating
|
||||
it but do NOT auto-write. Tag as HUMAN and surface to user.
|
||||
|
||||
After patching, re-read each modified file to verify no broken
|
||||
markdown, no orphaned references.
|
||||
|
||||
### OUTPUT
|
||||
|
||||
```
|
||||
DOC SYNC COMPLETE
|
||||
DOCS CHECKED : <count>
|
||||
AUTO PATCHED : <count> items across <count> files
|
||||
HUMAN PENDING: <count> items (see report above)
|
||||
SKIPPED : <count> (user declined)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## AUTO MODE
|
||||
|
||||
Triggered by other skills at end of session.
|
||||
Input format: `auto-mode scope: <file1> <file2> ...`
|
||||
|
||||
### STEP A1 — PARSE SCOPE
|
||||
|
||||
Extract the file list from `$ARGUMENTS`.
|
||||
These are files modified during the current session.
|
||||
|
||||
### STEP A2 — IDENTIFY RELEVANT DOCS
|
||||
|
||||
For each modified file, determine which docs might reference it:
|
||||
- Code files → README (examples, feature list), USAGE, docs/
|
||||
- Config files → INSTALL, CONFIGURE, README (setup section)
|
||||
- Package manifest → README (prerequisites, install), INSTALL
|
||||
- Dockerfile/compose → README (Docker section), INSTALL
|
||||
- CLAUDE.md changes → skip (CLAUDE.md is self-documenting)
|
||||
|
||||
If no relevant docs exist for the changed files → exit silently.
|
||||
|
||||
### STEP A3 — QUICK DRIFT CHECK
|
||||
|
||||
For each relevant doc, read it and check only the sections that
|
||||
could be affected by the scoped changes. No full git scan —
|
||||
compare the doc content directly against the current state of
|
||||
the modified files.
|
||||
|
||||
Categorize findings:
|
||||
- **NONE** — no drift detected
|
||||
- **MINOR** — factual correction (command, param, path, version)
|
||||
- **SIGNIFICANT** — new feature undocumented, section outdated,
|
||||
breaking change not reflected
|
||||
|
||||
### STEP A4 — ACT
|
||||
|
||||
- **NONE** → exit completely silent. No output at all.
|
||||
- **MINOR** → patch silently. Print one-line confirmation:
|
||||
`doc-sync: patched <file> (<what changed>)`
|
||||
- **SIGNIFICANT** → surface to user before patching:
|
||||
```
|
||||
DOC SYNC — drift detected after this session:
|
||||
<list of significant items with proposed fixes>
|
||||
Apply? (yes / no / select)
|
||||
```
|
||||
Wait for approval.
|
||||
|
||||
---
|
||||
|
||||
## RULES
|
||||
- Never invent content. Only sync what changed in code.
|
||||
- Never fabricate examples, feature descriptions, or explanations.
|
||||
- If a doc section doesn't exist yet, propose creating it but
|
||||
don't auto-write (tag HUMAN).
|
||||
- CHANGELOG entries: always propose, never auto-write.
|
||||
- Inline comment updates: only for files in scope, only when
|
||||
signature actually changed.
|
||||
- Preserve existing doc structure, formatting, and tone.
|
||||
- Keep patches minimal — change what's wrong, nothing else.
|
||||
Reference in New Issue
Block a user