Keep Docs Fresh with the docs-standards Agent Skill

Where this fits

You've just merged a change to your IPC contract. The tests pass, but your API.md is now stale, and your landing page diagram is out of date. Without a disciplined process, documentation decays silently until someone discovers a mismatch weeks later. The docs-standards skill encodes your project's documentation rules as an agent-loadable set of instructions, ensuring that any agent working on your codebase knows exactly which docs to touch, when, and how to verify they're fresh.

Why agents benefit

• Precise code-to-doc mapping: The skill defines a clear map—IPC contract changes go to TSDoc + generated API docs, domain changes go to docs/knowledge/, etc.—so an agent never guesses where a change belongs.
• Enforced thin-pointer/no-drift rule: Instead of duplicating architecture details, the skill tells agents to keep docs as thin pointers to canonical sources, preventing drift at the source.
• Automated graphify-update step: When architecture or module boundaries shift, the skill instructs agents to refresh landing diagrams and run drift checks, aligning visuals with reality.
• CI integration awareness: The skill references pnpm gen:api and pnpm check:landing-drift, so agents know that CI will catch violations—and they can run those checks locally before committing.
• Ownership clarity: With project-steward as the owner, agents know which role is responsible for doc maintenance, avoiding conflicting edits.

Practical scenarios

1. Updating IPC contracts

An agent is asked to change a message shape in packages/shared/src/ipc/contracts/. It loads docs-standards, sees that it must add TSDoc to the contract member, run pnpm gen:api, and never hand-edit docs/API.md. The agent completes the change and runs pnpm gen:api:check to confirm freshness before pushing.

2. Adding a new domain module

You introduce a new resume-parser module. The skill points the agent to docs/knowledge/resume-domain.md and docs/ARCHITECTURE.md. It also triggers the landing diagram refresh—the agent updates architecture-map.ts and body.html, then runs pnpm check:landing-drift to pass CI.

3. Refactoring the design system

A major UI overhaul touches DESIGN_SYSTEM.md. Without the skill, an agent might skip documentation entirely. With it, the agent knows to update that file and cross-reference any related knowledge docs, keeping the design narrative coherent.

Add it to your agent workflow

Install the skill into your agent's workspace:

npx skills add saeedkolivand/ai-job-hunter-app --skill docs-standards

Then, when an agent runs /update-docs or reaches the docs-sync step of an implementation workflow, it automatically loads these standards. For example, you can instruct your agent: "Update the export template docs per the new field additions"—the skill ensures it touches the right files and runs the right checks.

Compare before adopting

Before integrating docs-standards, compare it against your current documentation practices:

• Quality signals: Does the skill enforce a thin-pointer model and CI checks? Look for explicit rules like gen:api:check and check:landing-drift.
• Maintenance freshness: Check the repo's commit history—are the rules updated as the codebase evolves? A skill that lags behind your architecture is worse than none.
• Alternatives: Consider generic documentation prompts or manual checklists. The skill's advantage is its project-specific mapping, which generic prompts lack.
• Workflow fit: Does your agent already have a project-steward role? If not, you may need to adapt the ownership model.

Why it is worth tracking

With 48 stars and active maintenance, docs-standards demonstrates a practical, pattern-based approach to documentation hygiene. Its focus on generated docs, drift checks, and explicit ownership makes it a strong candidate for any project that struggles with doc rot. Evaluate it when you're building or refining your agent's documentation workflow—it could save hours of manual cleanup. For more agent skills, visit OpenAgentSkill and see how this skill fits into a broader ecosystem of coding-agent capabilities.