writing-claude-md-files_skill

This skill helps you craft CLAUDE.md files that capture domain intent, contracts, and freshness dates across top-level and subdirectories.

Python

128

GitHub Stars

1

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill ed3dai/ed3d-plugins --skill writing-claude-md-files

SKILL.md8.0 KB

Overview

This skill helps create and maintain CLAUDE.md files for projects and subdirectories. It codifies where to put project-wide HOW/commands versus domain-level WHY/contracts, and enforces mandatory freshness dates so Claude sessions have reliable context.

How this skill works

The skill provides templates and guidelines for top-level and domain-level CLAUDE.md files, including required sections, line-length heuristics, and file hierarchy recommendations. It enforces a mandatory "Last verified" date (obtained via date +%Y-%m-%d) and checks that domain files focus on intent, contracts, invariants, and boundaries rather than implementation details.

When to use it

When adding or updating a project-wide CLAUDE.md to capture tech stack, commands, and conventions.
When a domain/subdirectory has non-obvious contracts, invariants, or architectural decisions to communicate.
When onboarding new engineers who need persistent context without re-explaining intent each session.
When a CLAUDE.md is stale and needs verification of promises and guarantees.
When you want to limit Claude edits to safe areas by declaring boundaries and edit rules.

Best practices

Top-level files: focus on HOW (commands, tech stack, project structure), keep under ~300 lines.
Domain files: focus on WHY and CONTRACTS (exposes, guarantees, expects), keep under ~100 lines.
Always include a real freshness date using bash: date +%Y-%m-%d and update it when contracts change.
Name key files rather than using @ syntax; avoid force-loading files into context.
Remove stale content; prefer short, accurate guidance over exhaustive detail.

Example use cases

Create a root CLAUDE.md that lists build/test commands, tech stack, and safe-to-edit paths.
Add a domain CLAUDE.md for auth that documents token guarantees, invariants, and boundaries.
Update a billing domain CLAUDE.md after an API contract changes and bump the Last verified date.
Decide not to create CLAUDE.md for small utility folders to avoid unnecessary maintenance.

FAQ

Every CLAUDE.md must include a "Last verified" date produced by date +%Y-%m-%d.

Should I list every command and configuration?

No. Top-level files should cover the essential commands; reference package.json or configs for exhaustive lists.