writing-project-instructions
Use when creating or editing a CLAUDE.md or AGENTS.md, when it has grown long, or when a rule in it also exists in an installed skill.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- writing-project-instructions
- description
- Use when creating or editing a CLAUDE.md or AGENTS.md, when it has grown long, or when a rule in it also exists in an installed skill.
03 SKILL.md 正文
Writing project instructions
CLAUDE.md is read on every turn of every session; a skill's body costs nothing until it fires. Past a couple of hundred lines adherence drops, and the rule that mattered competes with forty that did not apply.
What goes where
| Content | Home |
|---|---|
| Facts only this repo knows — how to build, run, test it | CLAUDE.md |
| Constraints invisible in the file being edited — layering rules, generated files, frozen names | CLAUDE.md |
| Standing preferences about how to respond | CLAUDE.md |
| A discipline needed only for a certain kind of work | a skill |
| A rule that must hold whether or not the model cooperates | a hook |
| Anything an installed skill already states | a one-line reference, never a copy |
Test for moving something out: would it still make sense in a different repo? Then it is a discipline, paid for on every turn to be relevant on a few.
Never duplicate an installed skill
-
A rule in both places is forked, not reinforced. When the copies drift, the always-on one wins.
-
Replace the copy with a reference:
- **Testing:** `vvkit:writing-tests` for whether a test is owed, `vvkit-swift:swift-testing` for how to write one. - **Debugging:** `vvkit:debugging-systematically` — trace to origin before proposing a fix. -
Before removing a rule, confirm the skill states it. A rule with no home gets migrated first; deleting it because it "feels covered" is how a convention silently stops being followed. A portable rule with no home is a missing skill.
Keep what is genuinely always-on
- The repo's build, test and lint commands — they save a discovery pass every session.
- Constraints broken by the very edit that would trigger the skill.
- Output and tone preferences.
- Anything a hook depends on the reader knowing.
Shape
- Short sections with headings, so a reader skips what does not apply.
- Rules as rules, with the reason where it is not obvious — a reason generalises to the case the rule did not spell out.
- Plain statements. Emphasis everywhere marks nothing.
/vvkit:wire reconciles a CLAUDE.md against the installed skills mechanically. Read it before doing
the same edit by hand.
04 同仓库更多 Skills
no-heading
Use when proving that the validator rejects a body with no H1 and a force-loading @-link.
wrong-name-does-not-match-dir
Dispatches a subagent per task and reviews between each one.
writing-tests
Use when adding or changing behavior, fixing a bug, or judging whether an existing or generated test earns its place.
writing-skills
Use when authoring or editing a skill, agent, command or hook for this kit, or when deciding whether a piece of guidance belongs in a skill at all.
writing-logs
Use when adding or reviewing log statements, or when deciding what level a message belongs at.
writing-comments
Use when writing or reviewing comments and doc comments, or when a diff adds explanatory prose alongside code.