skills.rest
t-step
t-stepCOMMUNITY
Explore all skills by this author →
GitHub

maintain-claude-md

Creates, updates, and lints CLAUDE.md files for Claude Code sessions.

Updated Jul 9, 2026
Search Tags:#documentation#scaffold#monorepo#claude-code#lint#claude-md#lessons-learned
One-click install
npx skills add https://github.com/t-step/bindle-archive --skill maintain-claude-md-t-step
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: maintain-claude-md
Source: https://github.com/t-step/bindle-archive/tree/main/skills/maintain-claude-md
Command: npx skills add https://github.com/t-step/bindle-archive --skill maintain-claude-md-t-step

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? CLAUDE.md files drift over time: @-includes break, loader stubs load nothing, governance gets duplicated, and lessons get overwritten instead of appended. This Skill manages the full lifecycle of the operational file Claude Code reads at every session start, keeping it accurate and safe. ## Core Features & Use Cases - Init mode: Introspects the repo (README, package manifests, constitution, specs), asks up to five targeted questions, and scaffolds a canonical CLAUDE.md — including monorepo loader-stub layouts — without ever overwriting an existing file. - Update mode: Appends dated lessons, session history entries, and active-spec (SPECKIT) notes newest-first while preserving all existing content verbatim, with anti-bloat graduation of stale entries to docs/. - Lint mode: Runs a read-only static report (check | status | detail) covering include integrity, nested trees, command safety, duplicated governance, rule rationale, byte budget, and stale history — never executing scaffolded commands. - Use Case: After a debugging session, ask the agent to record the lesson; it appends a dated entry to Lessons learned without touching any existing line, then lints the file to confirm no broken @-includes. ## Quick Start Ask the agent to lint this repo's CLAUDE.md for broken includes, stale references, and unsafe commands using the maintain-claude-md skill.

Frequently Asked Questions about maintain-claude-md

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a CLAUDE.md file for my repository?▼

Use the skill's init mode: it introspects your README, package manifests, constitution, and specs, asks up to five questions about mission, commands, and hard rules, then scaffolds a canonical CLAUDE.md. If a CLAUDE.md already exists, it stops and offers a review or merge instead of overwriting.

How do I add a lesson learned to CLAUDE.md without breaking it?▼

Use update mode, which appends a dated entry (### YYYY-MM-DD — topic) to Lessons learned, newest first. It never rewrites existing sections and preserves all prior content verbatim, including typos and formatting, then shows the added lines as a diff.

Does linting CLAUDE.md run the commands listed in it?▼

No. Lint is strictly read-only and static: it checks binaries with command -v and verifies referenced paths exist, but never executes any snippet from the Commands section. This prevents accidental damage from scaffolded commands like release scripts.

Can this skill handle monorepos with multiple CLAUDE.md files?▼

Yes. Init detects apps/* or packages/* layouts and scaffolds a root loader stub that @-includes a shared core plus per-app CLAUDE.md files. Lint verifies every include target exists and fails a loader stub whose target is missing.

What problems does the CLAUDE.md lint check detect?▼

Lint reports missing required sections, broken @-includes, dead loader stubs, unknown command binaries, governance duplicated from a constitution, hard rules lacking rationale, byte-budget bloat, inaccurate SPECKIT blocks, undated lessons, stale session history, and a missing maintained-by marker.

When should I not use this skill on a CLAUDE.md?▼

Skip it when hand-editing prose inside an already-correct CLAUDE.md — just edit directly. It also does not author READMEs or constitutions; CLAUDE.md links to those documents rather than replacing them.

Related Skills

Explore More Software Engineering Skills→
g-bastianellig-bastianelli

write-constitution

Extract principles from project documentation and draft them into a constitution document.

Community
Advanced
watminwatmin

curare

Prune stale entries and replace the current-state note at wrap-ups.

Community
Intermediate
arielybarakarielybarak

claude-setup-scaffolder

Generate and validate Claude Code setups with CLAUDE.md, skills, and hooks.

Community
Advanced
agencia-conversionagencia-conversion
49

brain-keeper

Ingest sources, update brain pages, and log provenance decisions.

Official
Advanced