md-docs

SKILL.md

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.

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.