Md Docs
Split repo documentation correctly between human-facing README.md and agent/developer AGENTS.md (and CLAUDE.md symlink) so installs and automation stay consistent.
Overview
md-docs is an agent skill most often used in Build/docs (also Ship and Launch/distribution) that enforces README versus AGENTS.md audience boundaries for documentation workflows.
Install
npx skills add https://github.com/paulrberg/agent-skills --skill md-docsWhat is this skill?
- Strict audience table: README for human browsers vs AGENTS.md for agents and working developers
- README excludes CLI commands, just recipes, build/test workflows, structure trees, and API reference
- AGENTS.md carries stack, install/dev/build/test/lint commands and in-repo working context
- Shared conventions across all documentation workflows in the skill pack
- CLAUDE.md symlink pattern aligned with AGENTS.md for Claude Code discovery
- 2-file audience split (README.md vs AGENTS.md)
Adoption & trust: 1.6k installs on skills.sh; 62 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your README mixes install commands and agent prompts, so GitHub visitors bounce and coding agents miss the recipes they need in-repo.
Who is it for?
Indie OSS authors and skill publishers who want one marketing surface and one agent operations surface without duplicating or leaking internals.
Skip if: Private one-off scripts with no public README, or docs-only wikis with no agent workflow.
When should I use this skill?
Creating or updating repo documentation workflows that touch README.md, AGENTS.md, or CLAUDE.md.
What do I get? / Deliverables
You get a human-polished README and a dense AGENTS.md (plus CLAUDE.md symlink) so discovery and agent sessions each read the right file.
- Audience-correct README.md
- AGENTS.md (and CLAUDE.md symlink) with commands and stack
- Workflow-aligned doc updates without cross-audience leakage
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Build/docs is where most repos first need the README vs AGENTS split; the same rules apply when polishing docs before Ship and Launch distribution. Docs subphase covers authoring standards that keep GitHub/npm readers separate from in-repo agent instructions and command recipes.
Where it fits
Bootstrap AGENTS.md with stack and test commands while README stays marketing-only.
Point Claude Code at CLAUDE.md → AGENTS.md without duplicating just recipes on GitHub.
Pre-release pass to ensure API reference moved out of README into proper docs links.
Refresh badges and demo links in README while agents still read unchanged dev workflows.
How it compares
Documentation workflow skill—not a static site generator or MkDocs replacement.
Common Questions / FAQ
Who is md-docs for?
Solo builders and maintainers publishing repos where both GitHub readers and AI coding agents need clear, non-overlapping documentation files.
When should I use md-docs?
During Build/docs when scaffolding README and AGENTS.md; during Ship before release; during Launch/distribution when refreshing badges and links without moving CLI detail into README.
Is md-docs safe to install?
It guides markdown authoring only—review the Security Audits panel on this Prism page for the agent-skills repo.
SKILL.md
READMESKILL.md - Md Docs
# Common Patterns Shared conventions and patterns used across all documentation workflows. ## Audience Split The skill enforces a strict split between `README.md` and `AGENTS.md`. Every workflow must respect it. | 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. The README is allowed to mention its sibling AGENTS.md and link to it; that's the only legitimate way for a reader to reach development commands from the README. ## Recursive Operation Workflows act on every relevant file in the repository by default — not just the root. The skill's `SKILL.md` documents the canonical discovery commands; this section captures the conventions every workflow must honor. **Scope controls.** - Default: recurse over the whole repo from `git rev-parse --show-toplevel`. - `--root-only`: collapse to the repo root (pre-recursion behavior). - `path` argument: confine the sweep to one subtree. **Exclusions (always).** During discovery and creation, skip: - VCS / dependency / build output dirs: `.git`, `node_modules`, `vendor`, `.venv`, `target`, `dist`, `build`, `out`, `.next`, `coverage`. - Anything ignored by git (use `git ls-files --others --exclude-standard` and `git check-ignore`). - Hidden dot-directories, unless the directory holds a manifest. **`update-*` targets** — every existing `README.md` / `AGENTS.md` in scope: ```bash git ls-files --cached --others --exclude-standard -- '**/README.md' 'README.md' '**/AGENTS.md' 'AGENTS.md' ``` **`init-*` targets** — package roots (repo root + directories holding a manifest such as `package.json`, `Cargo.toml`, `pyproject.toml`, `setup.py`, `go.mod`, `foundry.toml`, `Gemfile`, `composer.json`) that lack the file. Never create files in arbitrary leaf directories. **Per-file scoping.** Each target is independent: - Read metadata from the nearest enclosing manifest (own directory, else walk up). - A nested `README.md` links to its sibling `AGENTS.md`, never the root one. - Each `AGENTS.md` gets a sibling `CLAUDE.md` symlink in the same directory. - `CONTRIBUTING.md` is detected per directory and merged into the sibling `AGENTS.md`. `CLAUDE.md` is a symlink to its sibling `AGENTS.md` and is never enumerated or written on its own. ## CONTRIBUTING.md Policy This skill does not maintain `CONTRIBUTING.md`. The sibling AGENTS.md owns the contribution workflow. When any workflow detects `CONTRIBUTI