vvkit-writing-project-instructions
Use when creating or editing an AGENTS.md or legacy CLAUDE.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
- vvkit-writing-project-instructions
- description
- Use when creating or editing an AGENTS.md or legacy CLAUDE.md, when it has grown long, or when a rule in it also exists in an installed skill.
03 SKILL.md 正文
Writing project instructions
AGENTS.md is loaded as project guidance; 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.
Codex runtime
Load referenced skills by reading their SKILL.md. Surveyor, reviewer and runner
skills are role instructions, not registered agent types or enforced tool allowlists.
Use a generic subagent only when delegation is available and permitted; otherwise
perform the role inline. Follow the active session's model, context and permission
rules. User authorization takes precedence over imported workflow approval gates.
Claude hooks and plugin commands are not active in this package. Existing
.claude/context/ paths refer to project documents, not Codex configuration.
What goes where
| Content | Home |
|---|---|
| Facts only this repo knows — how to build, run, test it | AGENTS.md |
| Constraints invisible in the file being edited — layering rules, generated files, frozen names | AGENTS.md |
| Standing preferences about how to respond | AGENTS.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 AGENTS.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-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.
writing-logs
Use when adding or reviewing log statements, or when deciding what level a message belongs at.