claude-md-authoring_skill

This skill helps you author and review CLAUDE.md configurations for Claude Code, applying WHAT/WHY/HOW and budget guidance.

Python

24

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 ratacat/claude-skills --skill claude-md-authoring

SKILL.md6.7 KB

Overview

This skill creates and reviews CLAUDE.md configuration files for Claude Code, applying HumanLayer guidelines like instruction budgets, the WHAT/WHY/HOW framework, and progressive disclosure. It focuses on compact, universally applicable guidance that maximizes context transfer while avoiding fragile patterns like using Claude as a linter.

How this skill works

The skill inspects a repository or user preferences to decide scope (user-level or project-level) and then generates or reviews CLAUDE.md content that fits the chosen scope. It counts actionable directives against instruction budgets, enforces WHAT/WHY/HOW structure for project files, and flags anti-patterns such as style rules that belong to deterministic tooling. It also recommends external references for complex topics and validates the result with a quality checklist.

When to use it

Creating a new CLAUDE.md for a personal or project context
Reviewing or trimming an existing CLAUDE.md to meet instruction budgets
Converting verbose or style-heavy guidance into high-level philosophy plus references
Preparing CLAUDE.md before onboarding Claude Code to a repository
Checking that user-level rules are truly universal across projects

Best practices

Choose scope first: user-level for universal preferences, project-level for repo-specific workflows
Keep instruction counts low: target ~30–40 for user-level, ~50–80 for project-level
Use WHAT/WHY/HOW for project-level files: WHAT (2–5 lines), WHY (optional), HOW (3–7 lines)
Avoid detailed style rules; delegate deterministic enforcement to linters and formatters
Use progressive disclosure: reference docs for deep conventions and examples

Example use cases

Drafting a project-level CLAUDE.md that lists purpose, stack, and essential commands
Trimming an over-specified user-level file by moving naming rules into docs and linters
Validating a CLAUDE.md against the quality checklist before committing
Converting inline examples into referenced docs to reduce instruction inflation
Flagging commands or tooling referenced in a user-level file that may not exist everywhere

FAQ

Each actionable directive counts as one instruction; multi-item lists count per item. Keep totals under the target budgets to avoid exceeding Claude Code's attention limits.

Can CLAUDE.md include formatting rules?

Avoid specific formatting or naming rules in CLAUDE.md. Instead, reference linters and formatters so enforcement is deterministic.