md-docs

Markdown Documentation

Manage project documentation by verifying against actual codebase state: analyze structure, files, and patterns before writing; never generate blind.

Working rules

• Read existing documentation and verify its claims against actual code and commands before editing.
• Preserve request authority, external-action boundaries, proof standards, and failure-attribution rules when condensing context.
• Do not create CONTRIBUTING.md or DOCS.md as a side effect; apply the specific workflow's creation limits.
• Keep cross-cutting conventions discoverable in the main context file and avoid duplicated volatile facts.
• Report actual edits and checks; do not claim snippets or external identifiers verified without checking them.

Portability

AGENTS.md is the universal context file (works with Claude Code, Codex, Kilocode). During Initialize Context or Update Context Files workflows only: if CLAUDE.md exists without AGENTS.md, confirm with the user first (Ask via AskUserQuestion (Claude Code; load with ToolSearch select:AskUserQuestion if not loaded) or request_user_input (Codex); fall back to numbered options in chat), then mv CLAUDE.md AGENTS.md. Never migrate as a side effect of another task.

The CLAUDE.md symlink is optional compatibility, not a required step. Claude Code v2.1.277 and later reads AGENTS.md natively when no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists in the working directory or above it; any of those three found there silently stops that loading, so flag it. For harnesses or sessions that read only CLAUDE.md, offer a CLAUDE.md containing @AGENTS.md; offer ln -s AGENTS.md CLAUDE.md only when no contributor uses Windows (a clone without core.symlinks gets a one-line text file); Edit/Write refuse to write through the link. Keep an existing symlink unless the user asks to remove it. Details and fixes: init-agents.md, section "Claude Code compatibility".

When this skill references "context files", it means AGENTS.md (and CLAUDE.md if present, as a symlink or an @AGENTS.md import).

Monorepos

Multi-package repo? Read monorepo.md before any update-*/init-* sweep (discovery commands, per-file scoping, context-loading rules). Enumerate targets; if the sweep would create or rewrite more than 3 files, stop: list planned targets and confirm before writing (same ask mechanism as in Portability above).

Arguments

Treat these as user-request modifiers: apply when the request contains the flag or equivalent phrasing. All workflows support:

• --dry-run: preview changes as a diff, write nothing
• --preserve: keep existing structure, fix inaccuracies only
• --minimal: quick pass, high-level structure only
• --thorough: deep analysis of all files

Backup Handling

Before overwriting, create a unique adjacent backup path with exclusive creation (for example, mktemp FILE.backup.XXXXXX). Copy the source bytes into that new path. Report the backup path. If creation or copying fails, stop before overwriting the source. Never replace or auto-delete an existing backup.

Report Format

After every operation, display a summary:

[OK] Updated AGENTS.md
  - Fixed build command
  - Added new directory to structure

[OK] Updated README.md
  - Added installation section
  - Updated badges

[--] CONTRIBUTING.md not found (skipped)

Verify

• Every factual claim in updated docs verified against current codebase
• No stale file paths or component names
• Formatting renders correctly in markdown preview

Task-specific references

Read the relevant reference before implementing or reviewing the matching behavior:

• For updating or initializing a context file, README, CONTRIBUTING, or API documentation: documentation-workflows.md.
• For selecting durable context, organizing documentation, or editing prose: context-content-and-writing.md.

Existing specialized references, when the corresponding topic applies:

• update-agents.md.
• update-readme.md.
• update-contributing.md.
• init-agents.md.