paulrberg/md-docs

Markdown Documentation Management

Overview

Manage project documentation for Claude Code workflows including README.md and agent context files (AGENTS.md / CLAUDE.md). This skill enforces a strict audience split: README.md is for humans, AGENTS.md is for agents and developers running commands. Use this skill when initializing new projects, updating existing documentation, or ensuring context files accurately reflect current code.

By default the skill operates recursively across the whole repository, not just the root. update-* workflows find and refresh every existing README.md / AGENTS.md in the tree; init-* workflows create files at the repo root and at each package root (a directory holding a manifest or workspace member) that lacks one. Each file is scoped to its own directory subtree and the nearest enclosing manifest. Pass --root-only to restrict any workflow to the repository root, or pass a path argument to limit the sweep to one subtree.

The skill emphasizes verification and validation over blind generation — analyze the actual codebase structure, file contents, and patterns before creating or updating documentation. All generated content should be terse, imperative, and expert-to-expert rather than verbose or tutorial-style.

Audience Split

This is the central rule for everything this skill produces.

| File | Audience | Contains | Excludes | | ------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | README.md | Humans browsing the repo (GitHub, npm, etc.) | Description, badges, links to docs/site/demo, references, papers, related work, acknowledgments, license, contributing pointer | Any CLI commands, just recipes, package scripts, build/test/lint workflows, project structure trees, API reference | | AGENTS.md (and CLAUDE.md symlink) | AI agents and developers working in the repo | Stack, commands (install, dev, build, test, lint), just recipes, package.json scripts, Makefile targets, code style, architecture, conventions, contribution workflow | Marketing copy, badges, external links unrelated to development |

When in doubt, ask: would a human reading this on GitHub care, or only a developer/agent running commands? If the latter, it goes in AGENTS.md.

Exemption — operator-run setup guides. The split is a default, not an absolute. A README may carry a short technical guide when its human reader is also the operator who must run the steps — typical cases: dotfiles repos (e.g. a chezmoi source tree whose README documents new-machine bootstrap), homelab or infra configs, personal tooling — or when the user explicitly asks for one. Keep the guide brief and task-focused (setup, bootstrap, restore); development-workflow commands (build, test, lint) still belong in AGENTS.md. During updates, preserve an existing exempted guide instead of stripping it.

Workflow Selection

Pick the workflow that matches the user's intent:

| Trigger | Workflow | Reference | | --------------------------------------------------------------------- | -------------------- | ----------------------------- | | "update README" / "refresh README" (file already exists) | Update README | references/update-readme.md | | "init README" / "create README" / "new README" (no file or --force) | Initialize README | references/init-readme.md | | "update CLAUDE.md" / "update AGENTS.md" / "update context files" | Update Context Files | references/update-agents.md | | "init AGENTS.md" / "create CLAUDE.md" / "init context" | Initialize Context | references/init-agents.md |

Selection rules:

• If the target file already exists and the user says "update" / "refresh" / "fix", route to an update-* workflow.
• If the target file is missing or the user says "create" / "init" / "new", route to an init-* workflow.
• For ambiguous requests, enumerate the target files first (see Recursive Discovery) and confirm with the user.
• If the user invokes the skill with no arguments, default to listing the files present across the tree and proposing a workflow rather than guessing.
• Multiple workflows in one request (e.g. "update README and AGENTS.md") are fine — run them sequentially in the order the user listed them, reporting each result independently.
• Each selected workflow applies to every target file the discovery step finds, unless --root-only or a narrowing path argument restricts the sweep.

CONTRIBUTING.md Policy

This skill does not maintain CONTRIBUTING.md. If the workflow detects a CONTRIBUTING.md alongside any target file (repo root or any package root):

1. Do not block other writes; surface the advisory for that directory.
2. Recommend the user merge its contents into the sibling AGENTS.md (since AGENTS.md now owns the development workflow, branch conventions, review process, and tooling references).
3. Suggest deleting CONTRIBUTING.md after the merge so the agent context file is the single source of truth.
4. Do not auto-merge or auto-delete; the user performs the merge.

Report the recommendation per directory in the standard summary format and continue with whichever README/AGENTS workflow the user requested, ignoring the CONTRIBUTING.md file itself.

Prerequisites

Before using any documentation workflow, verify basic project structure:

git rev-parse --git-dir

Ensure the output confirms you are in a git repository. If not initialized, documentation workflows may still proceed but git-specific features will be skipped.

Resolve the repository root once; all discovery is relative to it (or to a path argument, if given):

git rev-parse --show-toplevel

Then enumerate target files (see Recursive Discovery below) before attempting any workflow. If CONTRIBUTING.md shows up next to a target, apply the policy above for that directory.

Recursive Discovery

By default, workflows act on every relevant file in the tree. --root-only collapses this to the repo root; a path argument scopes it to one subtree.

Exclusions (always). Skip these everywhere during discovery and creation:

• VCS and dependency/build output dirs: .git, node_modules, vendor, .venv, target, dist, build, out, .next, coverage.
• Anything ignored by git (rely on --exclude-standard / git check-ignore).
• Hidden dot-directories (.github, .vscode, .claude, …) — unless the directory contains a manifest.

update-* discovery — find existing files to refresh:

# README.md / AGENTS.md tracked or untracked, respecting .gitignore
git ls-files --cached --others --exclude-standard -- '**/README.md' 'README.md' '**/AGENTS.md' 'AGENTS.md'

Drop any path under an excluded dir. CLAUDE.md is a symlink to its sibling AGENTS.md and is never processed on its own.

init-* discovery — find package roots that should get a new file:

# Directories holding a language/tooling manifest = package roots
git ls-files --cached --others --exclude-standard \
  -- '**/package.json' 'package.json' '**/Cargo.toml' 'Cargo.toml' \
     '**/pyproject.toml' 'pyproject.toml' '**/setup.py' 'setup.py' \
     '**/go.mod' 'go.mod' '**/foundry.toml' 'foundry.toml' \
     '**/Gemfile' 'Gemfile' '**/composer.json' 'composer.json'

The set of package roots is the repo root plus the unique directories of those manifests (minus exclusions). init-* creates the target file only in package roots that lack it; it does not create files in arbitrary leaf directories.

Per-file scoping. Treat each target independently:

• Metadata source is the nearest enclosing manifest (the one in its own directory, else walk up to the repo root).
• A nested README.md links to its sibling AGENTS.md, not the root one.
• Each AGENTS.md gets a sibling CLAUDE.md symlink in the same directory (ln -sf AGENTS.md CLAUDE.md, run from that directory).
• CONTRIBUTING.md is checked per directory and merged into the sibling AGENTS.md.

Process files deepest-first or root-first consistently, and report results grouped by path.

Common Arguments

These flags are interpreted consistently across workflows. Each reference describes their per-workflow effects in detail; see references/common-patterns.md for shared parsing conventions.

• path (positional): Limit the recursive sweep to this directory subtree instead of the whole repo. Combine with any workflow.
• --root-only: Disable recursion; act on the repository root only (the pre-recursion behavior). Always supported.
• --dry-run: Preview the changes that would be applied without writing files. Always supported.
• --preserve: Keep existing user-authored content; only fix verifiable inaccuracies. Used by update-* workflows.
• --minimal: Generate or verify the smallest useful output (top-level structure only).
• --thorough (alias --full): Perform deep analysis or generate comprehensive content. Slowest mode.
• --force: Override safety checks (e.g. overwrite existing target without prompting). Used by init-* workflows. Applies to every file in the sweep.

If the user passes other flags, fall back to default mode and surface a one-line note about the unrecognized flag in the final report.

Writing Style

All generated documentation should follow these conventions, regardless of workflow:

• Terse: Omit needless words. Lead with the answer or the link.
• Imperative (AGENTS.md): Use command form ("Build the project") not descriptive ("The project is built").
• Plain prose (README.md): Short, direct descriptions; avoid imperative lecturing — the audience is browsing, not executing.
• Expert-to-expert: Skip basic explanations; assume reader competence.
• Scannable: Use headings, lists, and code blocks. A reader should find what they need in under 30 seconds.
• Accurate: Verify every command, link, and path against the actual codebase before writing.

Avoid tutorial-style prose, redundant context, and filler such as "In order to...". When in doubt, write less. See references/common-patterns.md for examples of good vs. bad output.

Safety Defaults

Behaviors that apply across every workflow:

• Never auto-commit. Workflows touch documentation files only; the user reviews and runs git add / git commit manually. Rely on git for recovery — do not create *.backup files.
• For init-* workflows: refuse to overwrite an existing target unless --force is set or the user confirms via AskUserQuestion. When the sweep touches many files, confirm once for the batch rather than prompting per file.
• Recurse by default but stay inside the repo (git rev-parse --show-toplevel); honor the exclusions in Recursive Discovery. Use --root-only or a path argument to narrow scope. Never write outside the discovered target set.
• When a sweep would create or rewrite more than a handful of files, list the planned targets and get confirmation before writing (treat it like an implicit --dry-run preview first).
• If CONTRIBUTING.md exists next to any target, do not edit it; surface the merge-into-AGENTS recommendation for that directory and continue.

Update Context Files

When to use: user asks to update CLAUDE.md or AGENTS.md so they match the actual codebase. Trigger phrases include "update CLAUDE.md", "update AGENTS.md", "update context files", "fix context", "refresh context".

CLAUDE.md is a symlink to its sibling AGENTS.md and is not processed separately.

Runs on every existing AGENTS.md in the tree (see Recursive Discovery); each is scoped to its own directory and nearest manifest. AGENTS.md owns: stack, all CLI commands (install, dev, build, test, lint, deploy), just recipes, package.json scripts, Makefile targets, code style, architecture, conventions, and contribution workflow.

Inputs: each existing AGENTS.md (required), the nearest enclosing manifests, lock files, scripts, justfile, Makefile. Outputs: rewritten AGENTS.md files, each with a refreshed sibling CLAUDE.md symlink.

Recognised flags: path, --root-only, --dry-run, --preserve, --thorough, --minimal.

See references/update-agents.md.

Update README

When to use: user asks to update or refresh an existing README.md. Trigger phrases include "update README", "refresh README", "fix README", "regenerate README".

Runs on every existing README.md in the tree (see Recursive Discovery). For any package root that has no README.md, route that directory to Initialize README instead (or, with --force, allow update-readme to create it there).

README owns: description, badges, links (homepage, docs site, demo, package registry), references, related work, acknowledgments, license, contributing pointer. It does not contain CLI commands, just recipes, scripts, or project structure trees — those live in the sibling AGENTS.md, and the README links to it for them.

Inputs: each existing README.md; the nearest enclosing manifests for name/version/description/license/homepage URL; git remote for repository URL. Outputs: rewritten README.md files.

Recognised flags: path, --root-only, --dry-run, --preserve, --minimal, --thorough (alias --full).

See references/update-readme.md.

Initialize README

When to use: user asks to create new README.md files from scratch in a repository (or package roots) that lack them. Trigger phrases include "init README", "create README", "new README", "generate a README".

Creates a README.md in each package root that lacks one (repo root plus manifest-bearing directories; see Recursive Discovery). Refuses to overwrite an existing README.md without --force or explicit confirmation via AskUserQuestion. Supports two operating modes:

• Automatic inference: derive content entirely from project analysis.
• Guided: focus content around a user-provided description (e.g., "TypeScript library for parsing dates with zero deps"). A guided description applies to the root file; nested package files are inferred from their own manifests.

Same audience rules as Update README: humans only, no CLI.

Inputs: per-package-root codebase analysis (language, framework, LICENSE, homepage URL, citations or papers in repo), optional user-provided description. Outputs: new README.md in each targeted package root.

Recognised flags: path, --root-only, --dry-run, --minimal, --full, --force.

See references/init-readme.md.

Initialize Context

When to use: user asks to create new AGENTS.md (and CLAUDE.md symlink) files from scratch in a repository (or package roots) that lack context documentation. Trigger phrases include "init AGENTS.md", "create CLAUDE.md", "init context", "new context file", "generate AGENTS.md".

Creates an AGENTS.md in each package root that lacks one (see Recursive Discovery). Like Initialize README, supports automatic inference and guided mode (e.g., "Foundry smart contract project with security-first mindset"). For each generated file, always creates the sibling CLAUDE.md symlink via ln -sf AGENTS.md CLAUDE.md run from that directory.

Each generated AGENTS.md must include a Commands section that consolidates every CLI invocation a developer or agent will need for that package: install, dev, build, test, lint, format, deploy, plus all just recipes, npm/pnpm/yarn/bun scripts, and Makefile targets discovered in its directory.

Inputs: per-package-root codebase analysis (stack, scripts, justfile, Makefile, architecture hints, nearest package.json, README.md, language-specific manifests), optional user-provided description. Outputs: new AGENTS.md files, each with a sibling CLAUDE.md symlink.

Recognised flags: path, --root-only, --dry-run, --minimal, --full, --force.

See references/init-agents.md.

Reporting

Every workflow ends with a short summary. Use these conventions across all workflows:

• ✓ for successful operations: ✓ Updated AGENTS.md followed by indented bullet points listing concrete changes.
• ⊘ for skipped optional files.
• ⚠ for advisory notices (e.g. CONTRIBUTING.md merge recommendation).
• ✗ for failures: ✗ Failed to write README.md with a one-line cause.

Indent change details under each line so the user can scan a single file's deltas without re-reading the header. For recursive runs, group results by file path (use the path relative to the repo root as a sub-header) and end with a one-line tally (e.g. Updated 4 files, skipped 1, 1 advisory). For --dry-run, prefix the report with a "Planned Changes" header, list every target path, and include the diff or proposed-content preview rather than a confirmation. Refer to references/common-patterns.md for full report templates.

Additional Resources

For detailed workflows, examples, and implementation guidance, refer to these reference documents:

• references/common-patterns.md — Audience split, argument parsing, writing style, report formatting, file detection, metadata extraction, CONTRIBUTING.md merge recommendation
• references/update-agents.md — Complete context file update workflow including verification strategies, command discovery, and discrepancy detection
• references/update-readme.md — Complete README update workflow for human-aimed content
• references/init-readme.md — Complete README initialization workflow for human-aimed content
• references/init-agents.md — Complete context initialization workflow including language-specific templates and commands consolidation

These references provide implementation details, code examples, and troubleshooting guidance for each workflow type.