What Content Should Remain Bare in CLAUDE.md Files: The Complete Guide

CLAUDE.md files should contain only static, hand-written metadata and concise instructions—never auto-generated content, dynamic timestamps, or build artifacts that can be regenerated at runtime.

The humanlayer/skills repository treats CLAUDE.md (often named SKILL.md) as the canonical specification for Claude-based skills. These files function as the single source of truth that skill runners parse, so keeping them bare—minimal and deterministic—is a core architectural principle.

What "Bare" Means for CLAUDE.md Files

A bare CLAUDE.md contains only essential, declarative information. Anything that can be templated, injected, or generated belongs elsewhere. This separation ensures consistent skill behavior, clean version control diffs, and clear separation between human-authored intent and machine-produced artifacts.

In plugins/improve-claude-md/skills/improve-claude-md/SKILL.md, the repository demonstrates this philosophy with a tight YAML frontmatter block followed by short, purposeful sections. No example tables, no log dumps, no dynamic status fields.

Four Elements That Must Stay Bare

1. Front-matter YAML Block

The metadata header is the foundation of every skill definition. Keep these fields:

• name — unique skill identifier
• description — concise purpose statement
• author — attribution for maintainers
• version — semantic version string
• tags — searchable categorization
• inputs / outputs — declared interface contract

Omit: timestamps, runtime status, CI-generated build IDs, or any value that changes per execution.

Example from the repository pattern:

---
name: my-awesome-skill
description: Brief description of what the skill does.
author: Your Name <you@example.com>
version: 1.0.0
tags: [example, claude]
inputs:
  - name: targetFile
    type: string
    description: Path to the file to process.
outputs:
  - name: result
    type: string
    description: Resulting text after processing.
---

2. Human-Readable Instructions

Skill instructions should be hand-written, concise steps describing purpose and high-level workflow. Think algorithm outline, not tutorial.

Keep: Core logic flow, decision points, critical constraints.

Omit: Auto-generated examples, large code blocks produced by build steps, copy-pasted usage logs.

The plugins/design-control-loop/skills/design-control-loop/SKILL.md shows this restraint: instructions occupy mere lines while elaborated templates live under references/.

3. Static Reference Links

Include permanent URLs to external documentation, related assets, or canonical templates.

Keep: Links to README files, design patterns, or stable documentation (e.g., /plugins/design-control-loop/skills/design-control-loop/references/skill-template.md).

Omit: Temporary CI artifacts, expiring URLs, or dynamically constructed paths.

4. Explicit Placeholder Markers

Use TODO: and FIXME: comments to signal where future manual edits are required. These are intentional gaps, not oversights.

Omit: Sections that scripts will overwrite (e.g., a generated Examples table that npm run build populates elsewhere).

What Should Never Appear in Bare CLAUDE.md Files

Anti-pattern	Why it violates "bare"	Where it belongs
Auto-generated example tables	Changes on every build trigger false diffs	references/examples.md or build output
Runtime logs or execution traces	Dynamic, unbounded size, non-deterministic	External logging system or artifact storage
Timestamp fields in frontmatter	Updates on every commit create noise	CI metadata or separate build manifest
Full prompt templates with substitution variables	Templating logic belongs in skill runner	Template engine or references/ folder

Why the Bare Approach Matters

Determinism. The skill runner parses identical file contents on every invocation. No hidden state, no accidental variation.

Version control hygiene. Minimal files produce minimal diffs. Pull request reviews focus on meaningful human decisions, not generated noise.

Separation of concerns. Generation scripts—referenced in package.json or Makefile targets—can enrich documentation without polluting the source. The build-iterated-agentic-loop skill demonstrates this: complex looping logic stays readable because implementation details are stripped from the core definition.

Minimal CLAUDE.md Template

Based on patterns in humanlayer/skills, here is a production-ready bare template:

---
name: my-awesome-skill
description: Brief description of what the skill does.
author: Your Name <you@example.com>
version: 1.0.0
tags: [example, claude]
inputs:
  - name: targetFile
    type: string
    description: Path to the file to process.
outputs:
  - name: result
    type: string
    description: Resulting text after processing.
---

# Overview

A concise, hand-written description of the skill's purpose.  
Keep this section short; elaborate examples belong in the `references/` folder.

# Instructions

1. Validate the input.
2. Run the Claude model with the appropriate prompt.
3. Return the processed output.

# References

- [Design Control Loop template](/plugins/design-control-loop/skills/design-control-loop/references/skill-template.md)

Reference Files in humanlayer/skills

File	Demonstrates
plugins/improve-claude-md/skills/improve-claude-md/SKILL.md	Fully-specified skill descriptor with minimal frontmatter plus concise instructions
plugins/design-control-loop/skills/design-control-loop/SKILL.md	Bare metadata pattern with richer templates externalized to references/
plugins/build-iterated-agentic-loop/skills/build-iterated-agentic-loop/SKILL.md	Complex skill maintaining readability through strict minimization
README.md	Repository guidelines emphasizing minimal CLAUDE.md requirements

Summary

• Frontmatter stays bare: static metadata only, no dynamic fields
• Instructions stay concise: human-written workflow, no generated examples
• Links stay permanent: stable references, no temporary URLs
• Placeholders stay explicit: TODO:/FIXME: for manual future work
• Everything regenerable moves out: build artifacts belong in references/ or runtime injection

Frequently Asked Questions

What happens if I include auto-generated content in CLAUDE.md?

The file becomes a source of merge conflicts and review noise. Generated content changes on every build, producing diffs that obscure meaningful human edits. Per the repository's guidelines, such content belongs in separate files under references/ or in runtime-injected configuration.

Can I use templates or variables in CLAUDE.md files?

No. Templating logic violates the bare file principle. If substitution is required, implement it in the skill runner or build pipeline, keeping the committed CLAUDE.md fully resolved and static.

How do I version changes to a CLAUDE.md skill?

Update the version field in frontmatter following semantic versioning. Because the file stays minimal, version bumps appear in isolated, reviewable commits rather than buried in generated noise.

Where should detailed examples and documentation live?

Create a references/ directory adjacent to your CLAUDE.md. The design-control-loop skill uses this pattern: references/skill-template.md contains elaborated templates while SKILL.md remains bare.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}