# Freshness Checklist > matching the existing column format. Remove entries for agents that no longer exist. - Skill: `tools-only/freshness-checklist` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/freshness-checklist` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/freshness-checklist/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-29 - Page: https://skillmd.com/skills/tools-only/freshness-checklist --- # Freshness Checklist > For use by the `docs-writer` skill. Defines audit targets and auto-fix > rules for detecting stale documentation. ## How to Run a Freshness Audit 1. Read `VERSION.md` to get the canonical version number. 2. Walk through each audit target below. 3. For each issue found, note: file path, line, issue, suggested fix. 4. Present all issues in a summary table. 5. Apply fixes after user confirmation (or immediately if told "fix all"). ## Audit Targets ### 1. Version Number Sync **Source of truth**: `VERSION.md` → `Current Version: X.Y.Z` **Files to check**: | File | What to look for | | ------------------------------------------- | ---------------------------------- | | `docs/*.md` | `> Version X.Y.Z` in header line | | `.github/instructions/docs.instructions.md` | Version in header template example | **Auto-fix**: Replace old version string with current from `VERSION.md`. ### 2. Agent Count and Table **Source of truth**: List `.github/agents/*.agent.md` files (exclude `_subagents/` directory). **Expected count** (as of 2026-02-26): **13 agents** **Files to check**: | File | What to verify | | ------------------------------------------- | ---------------------------------------------------- | | `docs/README.md` | `## Agents (N + 3 Subagents)` heading and table rows | | `.github/instructions/docs.instructions.md` | `### Agents (N total)` and table | | `docs/README.md` project structure | `# N agent definitions` comment | **Auto-fix**: Update count in heading. Add missing agents to table matching the existing column format. Remove entries for agents that no longer exist. ### 3. Skill Count and Table **Source of truth**: List `.github/skills/*/` directories (exclude `README.md` file). **Expected count** (as of 2026-02-26): **14 skills** **Files to check**: | File | What to verify | | ------------------------------------------- | -------------------------------------- | | `docs/README.md` | `## Skills (N)` heading and table rows | | `.github/instructions/docs.instructions.md` | `### Skills (N total)` and table | | `docs/README.md` project structure | `# N skill definitions` comment | **Auto-fix**: Update count in heading. Add missing skills to the appropriate category table. Remove entries for deleted skills. ### 4. Prompt Guide Currency **Source of truth**: `docs/prompt-guide/README.md` agent/skill tables. **Files to check**: | File | What to verify | | ----------------------------- | --------------------------------------- | | `docs/prompt-guide/README.md` | Agent and skill tables match filesystem | | `docs/README.md` | Prompt Guide section links are valid | **Auto-fix**: Update tables to match current agent/skill inventory. ### 5. Prohibited References **Rule**: Removed agents must not be referenced in live docs. **Banned patterns**: - `diagram.agent.md` - `adr.agent.md` - `docs.agent.md` - `docs/guides/` - `docs/reference/` - `docs/getting-started.md` **Files to check**: All `docs/**/*.md`, `README.md`, `CONTRIBUTING.md`. **Auto-fix**: Replace with the correct skill reference (see `references/doc-standards.md` → Prohibited References table). ### 6. Deprecated Path Links **Rule**: No live doc should link to removed directories. **Check**: Grep all in-scope markdown files for links to non-existent paths. **Auto-fix**: Remove the link or replace with the current equivalent. ### 7. Instruction File Table Sync **Source of truth**: List `.github/instructions/*.instructions.md` files. **Expected count** (as of 2026-02-26): **25 instruction files** **Files to check**: Only relevant if `docs/README.md` or the root `README.md` lists instruction files. **Auto-fix**: Update count and table entries. ### 8. Template Inventory Sync **Source of truth**: List `.github/skills/azure-artifacts/templates/*.template.md` files. **Expected count** (as of 2026-02-09): **16 templates** **Files to check**: Only relevant if documentation references template counts. **Auto-fix**: Update count reference. ### 9. Project Health Files **Source of truth**: Filesystem agent/skill counts + CI validation results. **Files to check**: | File | What to verify | | -------------------------------------- | --------------------------------------------------- | | `QUALITY_SCORE.md` | Grades reflect current state; change log up to date | | `docs/exec-plans/tech-debt-tracker.md` | Active items still relevant; resolved items moved | **Auto-fix**: Update grades and log entries in `QUALITY_SCORE.md`. Mark resolved debt items as resolved with the current date. ## Summary Table Template When reporting audit results, use this format: ```markdown | # | File | Line | Issue | Fix | | --- | -------------------- | ---- | --------------------------------------- | -------------- | | 1 | docs/README.md | 42 | Agent count says 6, actual is 8 | Update heading | | 2 | docs.instructions.md | 34 | Missing `design` and `conductor` agents | Add table rows | ``` ## Known Issues No known issues. Last audit: 2026-02-26. All 21 discrepancies identified during the initial audit have been resolved (Tasks A–D). Fixes included: - Version headers migrated to `[Current Version](../VERSION.md)` links - Agent counts corrected to 8, skill counts to 8 - Conductor model corrected to Claude Opus 4.6, approval gates to 5 - MCP path fixed, broken link removed - Glossary cross-references fixed, keyboard shortcut corrected, new terms added - Scenarios directory removed; replaced by docs/prompt-guide/