A skill folder is not a GitHub repository. It's an instruction set for Claude. At AEM, the Skill-as-a-Service platform for Claude Code, we review and commission skills daily. The production bar is clear: every file in the folder must either get read by Claude during execution or support files that do. README.md fails that test. CHANGELOG.md fails it worse.
TL;DR: README.md and CHANGELOG.md serve human readers, not Claude. A skill folder should contain only SKILL.md, a refs/ directory, an assets/ directory, and optionally evals.json. Documentation files add clutter, signal poor skill hygiene, and in the case of CHANGELOG.md, create a source of stale historical instructions that can break behavior if accidentally referenced.
What belongs in a Claude Code skill folder?
A production-ready Claude Code skill folder contains exactly four components: SKILL.md, a refs/ directory for reference files loaded on demand, an assets/ directory for templates and approved examples, and optionally evals.json for test cases. Every other file requires a specific justification tied to Claude's execution path. The canonical structure is:
my-skill/
SKILL.md ← Always read when the skill is invoked
refs/ ← Reference files, loaded on demand by SKILL.md
assets/ ← Templates and approved examples
evals.json ← Test cases for validation (not read during execution)
That's it. Every file not in this list requires a specific justification for its presence. The justification cannot be "it helps humans understand the skill." Human understanding is not Claude's job; it's yours. For comparison, GitHub's official MCP consumes tens of thousands of tokens on its own; a well-scoped skill folder costs a few dozen tokens at scan time (Willison, simonwillison.net, 2025). Every unnecessary file erodes that efficiency.
Why does README.md create problems?
Claude Code does not automatically read every file in a skill folder. SKILL.md gets read on invocation. Reference files get read when SKILL.md instructs Claude to read them. Files Claude was never instructed to read are irrelevant to skill execution.
So README.md is harmless, right?
Not quite. Three issues:
It creates a loading risk. Skill maintainers who inherit the folder sometimes add "Read README.md for context" to a SKILL.md step, thinking they're giving Claude background information. They're loading a human-facing document into Claude's context window. README.md is written in the second person, for a reader who needs orientation. Claude doesn't need orientation to the skill it's executing — it needs instructions for that execution. The context injection is noise.
It signals a confused mental model. We've audited skills from over 40 unique builders as part of the AEM commission process. Skills with README.md in the folder almost always have other structural problems: reference files that chain to each other, rules written as prose rather than steps, output contracts that describe goals instead of deliverables. The README is a symptom of thinking about the skill as a software project rather than as an instruction set. The rest of the skill usually reflects that confusion.
It adds review overhead. When you or a colleague audits the skill 6 months after it shipped, README.md is another file to open and evaluate. It tells you nothing about how the skill behaves. It contributes nothing to the execution. It's maintenance tax for no return.
"The single biggest predictor of whether an agent works reliably is whether the instructions are written as a closed spec, not an open suggestion." — Boris Cherny, TypeScript compiler team, Anthropic (2024)
README.md is the opposite of a closed spec. It's contextual documentation for humans, open-ended by design. One documented Claude Code optimization project reduced initial context by 54% simply by removing verbose upfront documentation and keeping only execution-relevant content (Lindquist, github.com/johnlindquist, 2025). README.md is one of the first candidates for that cut.
Why is CHANGELOG.md worse?
CHANGELOG.md is worse than README.md because it can directly cause skill regressions, not just maintenance overhead. Changelogs contain historical state written in present-tense language: old behavior descriptions, removed conditionals, version comparisons. If a maintainer adds "Read CHANGELOG.md for context" to SKILL.md, Claude receives a document full of instructions that no longer apply.
A real example: "Changed in v2: we removed the 3-step approval gate and replaced it with a single confirmation." That sentence describes what the skill used to do, what it does now, and implies there's a v1 behavior that was different. Claude now has a document full of historical conditionals — behavior that no longer applies, written in present-tense language.
We've seen this produce exactly the time-sensitive conditional anti-pattern: Claude reads the changelog, encounters "in v1, we did X," and occasionally applies the v1 behavior because the conditional structure doesn't clearly distinguish "this happened" from "this is what to do." Historical changelogs are written for humans who understand temporal context. Claude treats instructions as current unless specifically told otherwise. Research from Stanford NLP confirms the underlying problem: performance on instruction-following tasks dropped by over 30% when relevant information appeared mid-context rather than at the start, because models treat mid-context content as live instructions (Liu et al., "Lost in the Middle," 2023, ArXiv 2307.03172). A changelog injected mid-prompt sits in exactly this vulnerable position.
The actual home for changelog content is the commit history. git log is the changelog for a skill, just like it's the changelog for any other versioned file. The skill folder contains the current state; the repository history contains the evolution. A 2025 Chroma study of 18 models, including Claude, documented progressive accuracy decay as context length grew, a pattern the researchers named "context rot" (Chroma, 2025). Historical changelogs are a reliable way to trigger it.
What about other documentation files?
Any documentation file that Claude never reads during execution does not belong in the skill folder. This covers NOTES.md, TODO.md, DESIGN.md, CONTRIBUTING.md, and any file that describes the skill rather than instructs it. Apply one test to every file you are considering:
Does Claude read this file during skill execution? If no, the file doesn't belong in the folder. This includes:
NOTES.md— personal notes to yourselfTODO.md— items you plan to fixDESIGN.md— rationale for structural decisionsCONTRIBUTING.md— instructions for other human contributors- Any file that begins with "This skill was created to..."
If you need to capture design rationale or contribution guidelines, put them in the repository's root-level documentation, not inside the skill folder. LLM reasoning performance begins degrading around 3,000 tokens, well before any model's technical limit (Levy, Jacoby, and Goldberg, 2024). A 2025 EMNLP study confirmed the same effect from a different angle: accuracy dropped 13.9% to 85% as context length grew, even when models had perfect access to the relevant information, meaning the irrelevant content itself caused the degradation (Du, Tian, et al., EMNLP 2025 Findings). Every non-execution file that reaches Claude's context pulls from that budget without contributing to the output.
Is this a script or template that SKILL.md references? Scripts and templates belong in assets/. They serve execution — Claude uses them as deterministic components of the skill output. That's a legitimate reason for a file to exist in the folder.
Is this a reference file for domain knowledge? That belongs in refs/, explicitly cited by a SKILL.md step. The reference file must contain content Claude can act on — facts, rules, formats, examples — not commentary about the skill itself.
For what actually belongs in the refs/ folder and what size limits apply, see What Are Reference Files in a Claude Code Skill? and What Goes in a SKILL.md File?. For how accidental reference file inclusions can compound into structural failures, see What Happens When Reference Files Chain to Other Reference Files?.
Removing documentation files from a skill folder won't fix a SKILL.md that has unclear instructions. Folder hygiene is necessary but not sufficient: a clean folder with a vague, under-specified SKILL.md still fails at the bar check. The structure sets the conditions for reliable behavior; the instruction quality determines whether those conditions are met.
Frequently asked questions
The core rule is simple: a file belongs in the skill folder only if Claude reads it during execution or if another file that Claude reads references it. README.md and CHANGELOG.md satisfy neither condition. Every attempted exception, including every scenario builders raise in practice, fails the same test.
Does Claude actually read all files in a skill folder?
No. Claude reads SKILL.md on invocation and reads reference files when SKILL.md instructs it to. Files never mentioned in SKILL.md are not read during execution; they are invisible to Claude at runtime. At scan time, skills consume only "a few dozen" tokens, with full file content loaded only when a task matches (Willison, simonwillison.net, 2025). README.md is technically harmless in most cases, but the problem is maintenance overhead and the risk that someone loads it accidentally.
Where should I put documentation about my skill?
In the repository's root or a separate /docs directory, not in the skill folder. If your skill is a standalone repository, the repo-level README.md is the correct home. If it's a skill inside a larger project, the project's documentation covers it.
Can I put a brief comments section at the top of SKILL.md?
YAML frontmatter supports a description field, which is the right place for a one-line description of what the skill does and when to invoke it. Beyond that, the SKILL.md body is instruction space for Claude. Design rationale belongs in commit messages.
What if I need to explain setup steps for my skill?
If setup requires running a command or installing a dependency, that belongs in your project's README.md. If setup requires reading a reference file, the reference file belongs in refs/ with a citation in SKILL.md. There's no setup scenario that requires a README.md inside the skill folder.
What's the maximum a skill folder should contain?
A well-structured production skill folder contains: SKILL.md, 1–5 reference files in refs/, 0–3 templates or approved examples in assets/, and evals.json. That's the full scope. If the folder contains more than 10 files total, audit for files that don't serve Claude's execution. Addy Osmani's benchmarks at Google Chrome show that giving a model an explicit output format with examples lifts consistency from around 60% to over 95% (Osmani, Engineering Director, Google Chrome, 2024). The mechanism is the same: reducing noise, tightening signal. A bloated skill folder is noise.
Last updated: 2026-04-18