md-docs

# Markdown Documentation Manage project documentation by verifying against actual codebase state. Emphasize verification over blind generation — analyze structure, files, and patterns before writing. ## Portability AGENTS.md is the universal context file (works with Claude Code, Codex, Kilocode). If the project uses CLAUDE.md, treat it as a symlink to AGENTS.md or migrate content into AGENTS.md and create the symlink: ```bash # If CLAUDE.md exists and AGENTS.md doesn't mv CLAUDE.md AGENTS.md && ln -sf AGENTS.md CLAUDE.md ``` When this skill references "context files", it means AGENTS.md (and CLAUDE.md if present as symlink). ## Workflows ### Update Context Files Verify and fix AGENTS.md against the actual codebase. See `references/update-agents.md` for the full verification workflow. 1. Read existing AGENTS.md, extract verifiable claims (paths, commands, structure, tooling) 2. Verify each claim against codebase (`ls`, `cat package.json`, `cat pyproject.toml`, etc.) 3. Fix discrepancies: outdated paths, wrong commands, missing sections, stale structure 4. Discover undocumented patterns (scripts, build tools, test frameworks not yet documented) 5. Report changes ### Update README Generate or refresh README.md from project metadata and structure. See `references/update-readme.md` for section templates and language-specific patterns. 1. Detect language/stack from config files (package.json, pyproject.toml, composer.json) 2. Extract metadata: name, version, description, license, scripts 3. If README exists and `--preserve`: keep custom sections (About, Features), regenerate standard sections (Install, Usage) 4. Generate sections appropriate to project type (library vs application) 5. Report changes ### Update CONTRIBUTING Update existing CONTRIBUTING.md only — never auto-create. See `references/update-contributing.md`. ### Initialize Context Create AGENTS.md from scratch for projects without documentation. See `references/init-agents.md`. 1. Analyze project: language, framework, structure, build/test tools 2. Generate terse, expert-to-expert context sections 3. Write AGENTS.md, create CLAUDE.md symlink ## Arguments All workflows support: - `--dry-run`: preview changes without writing - `--preserve`: keep existing structure, fix inaccuracies only - `--minimal`: quick pass, high-level structure only - `--thorough`: deep analysis of all files ## Backup Handling Before overwriting, back up existing files: ```bash cp AGENTS.md AGENTS.md.backup cp README.md README.md.backup ``` Never delete backups automatically. ## Writing Style - Terse: omit needless words, lead with the answer - Imperative: "Build the project" not "The project is built" - Expert-to-expert: skip basic explanations, assume competence - Scannable: headings, lists, code blocks - Accurate: verify every command and path against codebase - Sentence case headings, no emoji headers ## Report Format After every operation, display a summary: ``` ✓ Updated AGENTS.md - Fixed build command - Added new directory to structure ✓ Updated README.md - Added installation section - Updated badges ⊘ CONTRIBUTING.md not found (skipped) ```