create-rule

name	create-rule
description	Create or update Minsky rules with proper structure, frontmatter, and cross-references. Use when writing a new rule, modifying an existing rule, or reviewing rule quality.
user-invocable	true

Create Rule

Create or update rules with proper structure, metadata, and cross-references.

Arguments

Optional: rule name or description (e.g., /create-rule no-magic-numbers).

Process

0. Check the rule-admission ladder first (mt#2874)

Before drafting ANY new guidance content, check whether it belongs in a rule at all — and if it does, whether it needs alwaysApply: true. New guidance content defaults DOWN the ladder; alwaysApply: true is the LAST rung, not the default:

1. Path-scoped .claude/rules — file-shaped guidance (applies only when a matching glob is in context). Use globs in the frontmatter instead of alwaysApply.
2. Skill — task-shaped guidance (a procedure invoked for a specific workflow, not needed on every turn).
3. Memory (mcp__minsky__memory_create) — incident-shaped guidance (a durable finding from a specific incident, not a standing per-turn check).
4. Docs (docs/) — reference-shaped guidance (background/architecture an agent looks up on demand, not a behavior it must apply unprompted).
5. alwaysApply: true — LAST, reserved for genuinely per-turn discipline. Apply the mt#1876 criterion before choosing this rung: "would removal cause an agent to skip a check it runs every turn?" If the answer is no, the content belongs on a cheaper rung above.

Every rule addition that reaches step 2 below and sets alwaysApply: true is implicitly asserting it passed this check. A PR that grows the compiled CLAUDE.md by more than a couple thousand bytes via .minsky/rules/** is mechanically gated on this same ladder at merge time (require-growth-justification-before-merge.ts, mt#2874) — front-loading the check here avoids that round-trip.

1. Define the rule's purpose

• What specific behavior does this rule govern?
• When should this rule be applied? (triggers)
• Is this a constraint (declarative) or a procedure (should be a skill instead)?

Key distinction: Rules are declarative constraints that are always-on or triggered by file patterns. Procedures and workflows should be skills, not rules.

2. Write the frontmatter

---
description: "Use when [specific trigger]. Apply alongside [related-rule] for [context]."
globs: "**/*.ts" # Optional: file patterns that trigger this rule
alwaysApply: false # true only for universal constraints
tags: [category] # e.g., code-style, testing, architecture, safety, minsky
---

Description guidelines:

• Focus on WHEN the rule applies, not WHAT it instructs
• Begin with "Use when..." or "Guidelines for..."
• Include trigger keywords
• Use "REQUIRED" for non-negotiable rules
• Keep under 100 characters
• Test: "Would an AI correctly apply this rule based solely on this description?"

3. Structure the content

1. Title — clear, concise # Title

2. Introduction — 1-2 sentences summarizing purpose

3. Core requirements — bulleted list of key points

4. Examples — contrasting good/bad patterns:

   // AVOID
   badExample();
   
   // PREFER
   goodExample();
   

5. Rationale — only if not self-evident

6. See also — cross-references to related rules/skills

4. Follow quality principles

• Concision: Every word must count. AI assistants have limited attention.
• Modularity: One rule = one concern
• No duplication: Never repeat content from other rules
• Hierarchy: Most important information first
• Clarity: Simple language, concrete examples

5. Use the rules command

Create rules via minsky rules create, not by writing files directly:

minsky rules create my-rule --name "My Rule" --description "When to use"

Or via MCP: mcp__minsky__rules_create

Anti-patterns

• Verbose introductions — don't waste words explaining the rule exists
• Duplicate content — cross-reference, don't copy
• Vague descriptions — "best practices" without specifics
• Mixed concerns — each rule governs exactly one area
• Procedural content in rules — multi-step workflows belong in skills

Assessment checklist

• Precise description indicating when to apply
• No duplicated content from other rules
• Clear, specific language
• Concrete examples (correct and incorrect)
• Structured most-to-least important
• References to related rules/skills
• Could be correctly applied by an AI with limited attention