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

> Discover what content belongs in CLAUDE.md files. Learn to include only static metadata and instructions, excluding dynamic or auto-generated content for clarity and maintainability.

- Repository: [HumanLayer/skills](https://github.com/humanlayer/skills)
- Tags: best-practices
- Published: 2026-09-07

---

**[`CLAUDE.md`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/CLAUDE.md) (often named [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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:

```yaml
---
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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main//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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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:

```markdown
---
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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/plugins/build-iterated-agentic-loop/skills/build-iterated-agentic-loop/SKILL.md) | Complex skill maintaining readability through strict minimization |
| [`README.md`](https://github.com/humanlayer/skills/blob/main/README.md) | Repository guidelines emphasizing minimal [`CLAUDE.md`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/CLAUDE.md). The `design-control-loop` skill uses this pattern: [`references/skill-template.md`](https://github.com/humanlayer/skills/blob/main/references/skill-template.md) contains elaborated templates while [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) remains bare.