Use when adding project conventions or scoping guidelines. Use when user says 'add convention', 'scope guideline', 'add rule', 'create rule'.
Writing rules IS creating scoped, auto-injected conventions.
Rules auto-inject into context when files match their paths: glob. Keep them concise—every line costs tokens.
Core principle: Rules = path-scoped conventions with auto-injection. CLAUDE.md = broad project instructions. For this plugin project: use CLAUDE.md for all guidelines—rules mechanism not currently implemented.
Violating the letter of the rules is violating the spirit of the rules.
Pattern: Skill Steps Handoff: none Next: none
Before ANY action, create task list using TaskCreate:
TaskCreate for EACH task below:
- Subject: "[writing-rules] Task N: <action>"
- ActiveForm: "<doing action>"
Tasks: 0. Fetch latest official rule/skill spec
Announce: "Created 8 tasks (0–7). Starting execution..."
Execution rules:
TaskUpdate status="in_progress" BEFORE starting each taskTaskUpdate status="completed" ONLY after verification passesTaskList to confirm all completed| Phase | Focus | What You Do |
|---|---|---|
| Analysis | Understanding | Identify what convention needs enforcement |
| Scope Definition | Targeting | Determine which files need this convention |
| Design | Planning | Structure rule content and path patterns |
| Implementation | Creation | Write clear, specific configuration rules |
| Optimization | Refinement | Streamline scope and improve clarity |
Goal: Pull the current Anthropic spec for path-scoped rules / skill frontmatter before designing — never trust cached memory.
Action:
Skill tool: fetching-claude-docs
component: rule
question: "rule frontmatter (paths, description), auto-injection by glob,
rule vs CLAUDE.md vs skill placement, token cost considerations"
Verification: Received YAML with non-empty spec_excerpt. Use as authoritative reference; if any rule in this SKILL conflicts with the fetched spec, the fetched spec wins.
Goal: Understand what convention to encode and where it applies.
Questions to answer:
Decision tree:
digraph rule_decision {
rankdir=TB;
start [label="New directive needed", shape=doublecircle];
q1 [label="Applies to\nall files?", shape=diamond];
q3 [label="Contains steps\nor code?", shape=diamond];
q4 [label="CLAUDE.md\nalready > 180 lines?", shape=diamond];
claudemd [label="CLAUDE.md"];
global_rule [label="Global rule\n(no paths)"];
scoped_rule [label="Path-scoped rule"];
skill [label="Not a rule\nuse writing-skills"];
start -> q1;
q1 -> q3 [label="yes"];
q1 -> scoped_rule [label="no"];
q3 -> skill [label="yes"];
q3 -> q4 [label="no"];
q4 -> global_rule [label="yes"];
q4 -> claudemd [label="no"];
}
Verification: Can state the convention in one sentence and specify the glob pattern.
Goal: Work on matching files WITHOUT the rule. Note where convention is forgotten.
Process:
Verification: Documented at least 1 instance where convention was not followed.
Goal: Create rule file addressing the gaps you documented.
~/.claude/rules/ # User-level (global, all projects)
.claude/rules/ # Project-level
├── code-style.md # Global rule (no paths:)
├── api/
│ └── conventions.md # paths: ["src/api/**"]
└── testing/
└── guidelines.md # paths: ["**/*.test.ts"]
---