docs-sync
Synchronizes documentation (README.md, CHANGELOG.md, API docs) with implementation. Preserves user content outside speckit markers. Updates are non-destructive and clearly delineated. Always run after /speckit.implement completes.
How do I install this agent skill?
npx skills add https://github.com/drillan/speckit-gates --skill docs-syncIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The docs-sync skill is a documentation utility that synchronizes README and CHANGELOG files with implementation data using safe HTML comment markers. No malicious patterns or security risks were identified.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
2/2 files flagged
What does this agent skill do?
docs-sync
Synchronizes documentation with implementation after /speckit.implement completes.
Purpose
This skill automatically updates documentation to reflect the implemented features. It:
- Updates README.md: Adds/updates usage section with implementation details
- Updates CHANGELOG.md: Adds entries for new features and changes
- Updates API docs: Synchronizes API documentation with contracts
- Preserves user content: Content outside speckit markers is never modified
Marker System
docs-sync uses HTML comment markers to delineate auto-generated sections:
<!-- speckit:start:section-name -->
Auto-generated content here
<!-- speckit:end:section-name -->
Content outside these markers is preserved exactly as-is.
Output
The skill outputs a DocsSyncResult showing:
- Files created, updated, or unchanged
- Sections modified within each file
- Diff summary (lines added/removed/changed)
- Any errors encountered
Usage
This skill runs automatically after /speckit.implement. You can also run it manually:
npx skills run docs-sync
Exit Codes
| Code | Status | Meaning |
|---|---|---|
| 0 | Success | All updates successful |
| 1 | Partial | Some updates failed |
| 3 | Error | Required files missing |
Sections Updated
README.md
| Section | Marker | Content Source |
|---|---|---|
| Usage | <!-- speckit:start:usage --> | spec.md user stories |
| Installation | <!-- speckit:start:installation --> | plan.md dependencies |
| Features | <!-- speckit:start:features --> | spec.md functional requirements |
CHANGELOG.md
| Section | Marker | Content Source |
|---|---|---|
| Unreleased | <!-- speckit:start:unreleased --> | tasks.md completed tasks |
Preservation Rules
- Content before the first marker is always preserved
- Content after the last marker is always preserved
- Content between different marker pairs is always preserved
- Only content within matching marker pairs is updated
- If no markers exist, content is appended with new markers
Error Handling
- Missing markers: Creates new markers and adds content
- Malformed markers: Reports error, skips that section
- File permissions: Reports error, continues with other files
- Missing source files: Reports which sources are unavailable
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/drillan/speckit-gates/docs-sync">View docs-sync on skillZs</a>