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.
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.
More from paulrberg/agent-skills
code-simplify
This skill should be used when the user asks to "simplify code", "clean up code", "refactor for clarity", "reduce complexity", "improve readability", "make this easier to maintain", or asks to simplify recently modified code.
1.7Kcode-review
This skill should be used when the user asks to "review code", "review PR", "code review", "audit code", "check for bugs", "security review", "review my changes", "find issues in this code", "review the diff", or asks for pull request review or code audit.
1.5Kcli-gh
This skill should be used when the user mentions "gh CLI", "gh command", asks to "view repository info", "trigger workflows", "search GitHub", "manage codespaces", "check PR status", "list issues", "browse repo", or asks about GitHub CLI usage and automation from the command line.
1.4Keffect-ts
This skill should be used when the user asks about Effect-TS patterns, services, layers, error handling, service composition, or writing/refactoring code that imports from 'effect'. Also covers Effect + Next.js integration with @prb/effect-next.
1.4Kcode-polish
This skill should be used when the user asks to "polish code", "simplify and review", "clean up and review code", "full code polish", "simplify then review", "refactor and review", "simplify and fix", "clean up and fix", or wants a combined simplification and review workflow on recently changed code.
1.3Ktailwind-css
This skill should be used when the user asks to style with Tailwind v4, add or fix Tailwind classes, use tailwind-variants or tw-animate-css, or configure Tailwind. Trigger phrases include "style with Tailwind", "fix Tailwind styles", "configure Tailwind v4", "migrate to Tailwind v4".
1.3K