nakane1chomenakane1chome/claude-skills/CLAUDE.md

claude-skills

CLAUDE.md0 starsChanged 7 months agoUnlicenseView on GitHub

Scaffolding for repeatable, deterministic agent-driven development. Two kinds of components: Each component lives in skills/<name>/ and contains: - SKILL.md — Skill definition with YAML frontmatter (name, description) and the prompt body - responsibilities.md — (optional) Agent vs developer ownership matrix for each stage - plugin.json — (plugins only) Plugin manifest for Claude Code auto-loading - hooks/hooks.json — (plugins only) Declarative hook registration using ${CLAUDE_PLUGIN_ROOT} paths This repo dogfoods sandbox: ./run-sandbox.sh --build at the repo root launches Claude Code in a…

In this repository12 other files it gives its agents.
- agent-optimizeSkill
- dev-recordSkill
- flesh-outSkill
- generator-codingSkill
- light-v-structureSkill
- no-pre-existing-failuresSkill
- review-skillSkill
- review-stepsSkill
- sandboxSkill
- sdlc-cross-reviewSkill
- strong-editSkill
- my-skillSkill

The file

We split this CLAUDE.md into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Every test reports two scores: Hard: PASS/FAIL (require + expect) and Ability: X% (weighted achieve checks).
line 77
Distinctive:
Document curation skills use a stop-after-each-stage pattern — the agent pauses for developer review between stages
line 85

≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

Scaffolding for repeatable, deterministic agent-driven development. Two kinds of components:

Skills — structured prompts (SKILL.md + optional responsibilities.md) that guide multi-step workflows with developer checkpoints
Plugins — hook-based components (plugin.json + hooks/hooks.json) loaded via --plugin-dir for passive session instrumentation

Component Structure

Each component lives in skills/<name>/ and contains:

SKILL.md — Skill definition with YAML frontmatter (name, description) and the prompt body
responsibilities.md — (optional) Agent vs developer ownership matrix for each stage
plugin.json — (plugins only) Plugin manifest for Claude Code auto-loading
hooks/hooks.json — (plugins only) Declarative hook registration using ${CLAUDE_PLUGIN_ROOT} paths

Document Curation Skills

Skill	Purpose	Use When
review-steps	Structured review for polish — language, clarity, structure	Draft with typos, incomplete sentences, or needing a final check
flesh-out	Generate structure from raw notes or bullet points	Raw notes, bullet points, stream of consciousness
strong-edit	Critical editorial analysis — challenges argument and structure	Complete draft needing substantive critique
agent-optimize	Optimize docs for AI agent consumption	Verbose prose that agents will need to parse
sdlc-cross-review	Completeness + parent document consistency via V-model	Document that needs checking against its SDLC hierarchy

Project Structure

Skill	Purpose	Use When
light-v-structure	V-model project structure conventions — scaffold the canonical `docs/` tree, audit traceability, and guide planning/decision-making	Organizing a project's documentation hierarchy (paradigm, ADR, arch, design, test), or keeping planning work aligned to V-model cross-validation pairs

Code Generation

Skill	Purpose	Use When
generator-coding	Template-based code generation pattern	Building generators that use data models + templates + helpers to produce repetitive interface code

Dev Environment

Skill	Purpose	Use When
sandbox	Scaffold a Docker YOLO-mode harness (`run-sandbox.sh` + `docker/`) into a target repo	Developer wants Claude Code to run in an isolated container with `--dangerously-skip-permissions`, sharing `~/.claude` for session continuity

This repo dogfoods sandbox: ./run-sandbox.sh --build at the repo root launches Claude Code in a container with /workspace bind-mounted to the checkout. Pytest cache is routed to .pytest_cache.sandbox/ so host and container test runs don't clobber each other.

Traceability

Component	Type	Purpose
dev-record	Plugin	Passive session recording — plans, input, decisions, deviations, anomaly detection, agent self-reporting
review-skill	Skill	Review a SKILL.md for quality and convention alignment

Testing

E2E tests validate skills and plugins against real Claude sessions across model tiers.

test_fw/ — reusable pytest framework (Claude SDK integration, audit inspection, ablation detection, test steps)
tests/ — per-skill E2E tests that depend on test_fw
make test runs skill tests across model tiers; make test-fw runs framework unit tests; make test-all runs both
CI: .github/workflows/e2e-tests.yml publishes HTML reports to GitHub Pages
See docs/testing.md for the full test framework guide

Test Steps

Tests use the steps fixture (TestSteps class) with three check classes:

Class	Prefix	On failure	Use when
require	`steps.require_`	Aborts test	Infrastructure prerequisites (session health, no errors)
expect	`steps.expect_`	Records FAIL, continues	Prompted deliverables the model was asked to produce
achieve	`steps.achieve_`	Records NOT ACHIEVED, continues	Quality/approach indicators, weighted by difficulty

Every test reports two scores: Hard: PASS/FAIL (require + expect) and Ability: X% (weighted achieve checks). Difficulty tiers: expected (1.0), challenging (0.5), aspirational (0.25).

Test Failures

Every test failure is a real bug. Fix it. There is no such thing as a "pre-existing failure," a "known flaky test," or an "unrelated issue." If a test fails, it is broken and you must fix it before moving on. Do not dismiss, skip, or rationalize away any failure. Do not label failures as "pre-existing" to avoid responsibility. If you broke it, fix it. If it was already broken, fix it anyway — you are looking at it now and that makes it your problem.

Conventions

Document curation skills use a stop-after-each-stage pattern — the agent pauses for developer review between stages
Plugins use a declarative hook model — hooks/hooks.json registers hooks, no settings.json merge needed
Infrastructure skills (e.g. dev-record) use an action-dispatch pattern — the user specifies an action to run
Skills with a responsibilities.md define which stages the agent leads vs assists on
Skills are composable: flesh-out a skeleton, then review-steps the result, then strong-edit the final draft
See AUTHORING.md for the full style guide on writing new skills (directory layout, frontmatter, description conventions)

License

Unlicense (public domain)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free