md-docs

What this skill does

# 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.

## 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:

```bash
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):

```bash
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:

```bash
# 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:

```bash
# 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