/readme

Interpret the user's instruction, determine the operation, target, focus, and files, then announce the plan and execute.

Files

This skill manages two companion files:

• •README.md — onboards users (default, always included)
• •CONTRIBUTING.md — onboards contributors (included when relevant)

When the instruction mentions contributing, development setup, or contributor onboarding, include CONTRIBUTING.md. When creating a README from scratch, also create CONTRIBUTING.md if the project has more than one potential contributor. When reviewing, check both files for drift.

For CONTRIBUTING.md protocol, read ~/.claude/skills/readme/core-contributing.md.

Operations

help

Explain how this skill works. Read and present help.md from this skill's directory.

create

Write a README from scratch. Use when no README exists, or the user explicitly wants a full rewrite. Destructive — overwrites any existing README.

update

Modify an existing README. Use when a README exists and needs changes — new features to document, stale sections to fix, targeted edits. Preserves what works, rewrites what doesn't.

review

Assess README quality without modifying it. Use when the user wants to know what's wrong, what's missing, or whether recent work is documented. Reports findings. Does not write unless the user asks.

Target

Which README(s) to operate on. Orthogonal to the operation.

• •Single — one README for the current project (default)
• •Batch — multiple READMEs, e.g. every package in a monorepo
• •Git-scoped — packages affected by a branch, PR, commit range, or time period

Interpret from the user's natural language. "That branch", "the packages I touched this week", "everything under packages/", "affected by this PR" are all valid. For git-scoped, resolve the reference (git log, git diff, branch comparison) to determine which packages are affected.

For batch or git-scoped: read batch.md from this skill's directory for the queue protocol.

Focus

Which parts of each README to touch. Orthogonal to both operation and target.

• •Whole — the entire README, all sections (default for create)
• •Affected — only sections implicated by specific changes (a PR, a branch, recent commits)
• •Named — user-specified sections ("just the concepts", "the quickstart and usage")

These combine freely with target:

• •all READMEs × only parts affected by this PR
• •one README × the whole thing from scratch
• •all READMEs × full rewrite from source
• •one README × just the concepts section

Announce Before Acting

After determining operation, target, focus, and files, announce the plan and wait for confirmation:

Operation: CREATE
Target: packages/cmx
Files: README.md + CONTRIBUTING.md
Focus: whole (new files from scratch)
Proceed?

Operation: UPDATE
Target: 5 packages affected by PR #42 (core, fs, test, release, cmx)
Files: README.md
Focus: sections affected by PR changes
Proceed?

Operation: UPDATE
Target: packages/cmx
Files: CONTRIBUTING.md
Focus: development workflow section (build tool changed)
Proceed?

Operation: REVIEW
Target: packages/cmx
Files: README.md + CONTRIBUTING.md
Focus: whole
Proceed?

If you cannot confidently determine any dimension, ask. Do not guess.

Inference

When the user's instruction doesn't name an operation explicitly, infer from context:

• •User asks about the skill itself ("help", "how does this work", "what can you do") → help (takes precedence)
• •No README exists → create
• •README exists + conversation has recent implementation work → update
• •README exists + git working tree is dirty → update
• •README exists + no recent context + clean git → review
• •User says "rewrite", "from scratch", "start over" → create
• •User says "refresh", "add", "fix", "change" → update
• •User says "review", "check", "audit", "how does it look" → review

File Sequencing

When both README.md and CONTRIBUTING.md are in scope, process README.md first. It defines the glossary that CONTRIBUTING.md links to. Each file runs its own pipeline — do not merge protocols.

Execution

After confirmation, read the operation's file from ~/.claude/skills/readme/:

Only the files needed for the determined operation + file combination are loaded.