{"id":"86330d4e-faad-4499-82d1-31ceaaa80a6c","shortId":"YRTZPM","kind":"skill","title":"create-rule","tagline":"Use when creating, writing, or updating a Claude Code rule file (.claude/rules/*.md or ~/.claude/rules/*.md), or when asking about rule format, path scoping, or rule best practices.","description":"# Create Rule\n\n## Rules vs CLAUDE.md vs Skills\n\nChoose the right mechanism before writing anything:\n\n| Mechanism | When to use | Loads |\n|---|---|---|\n| **Rule** | Behavioral instructions scoped to a topic or file type | Every session (or on path match) |\n| **CLAUDE.md** | Broad project context: build commands, architecture, workflows | Every session |\n| **Skill** | Repeatable on-demand workflows | Only when invoked |\n\nIf the instruction only makes sense for certain file types (e.g. Go, test files), use a path-scoped rule. If it's a repeatable task workflow, use a skill instead.\n\n## Storage Locations\n\n| Scope | Path |\n|---|---|\n| Personal, all projects on this machine | `~/.claude/rules/<topic>.md` |\n| Project, shared with team via git | `.claude/rules/<topic>.md` |\n\nRules in subdirectories are discovered recursively (e.g. `.claude/rules/frontend/react.md` works).\n\n## Rule File Format\n\n```markdown\n---\npaths:            # optional; omit for always-load\n  - \"**/*.go\"\n  - \"**/*_test.go\"\n---\n\n# rule-name\n\nInstructions...\n```\n\nNo `paths` frontmatter → rule loads every session.\n`paths` present → rule loads only when Claude opens a matching file.\n\n## Path Scoping Decision\n\nUse **always-load** (no frontmatter) for:\n- Universal behaviors: commit style, escalation policy, output verbosity\n- Toolchain choices: task runner, package manager, CI tooling\n\nUse **path-scoped** for:\n- Language conventions: `**/*.go`, `**/*.ts`, `**/*.py`\n- Test files: `**/*_test.go`, `**/*.test.ts`, `**/*.spec.ts`\n- Domain directories: `src/api/**/*`, `e2e/**/*.go`, `migrations/**/*.sql`\n\nSee [references/rule-patterns.md](references/rule-patterns.md) for glob pattern examples.\n\n## Writing Effective Rules\n\n- **Specific and verifiable**: \"Use 2-space indentation\" not \"format code nicely\"\n- **One topic per file** with a descriptive filename (`testing.md`, `api-design.md`)\n- **Under 200 lines**. Longer files reduce adherence; split if growing large\n- **Markdown structure**: use headers and bullets, not dense paragraphs\n- **No contradictions** across rule files; audit when adding new ones\n- **IMPORTANT** / **YOU MUST** emphasis for rules that are frequently violated\n\n## Workflow\n\n1. **New or update?** Check existing rules in the target directory for overlap\n2. **Scope**: personal (`~/.claude/rules/`) or project (`.claude/rules/`)?\n3. **Path scope**: universal (no frontmatter) or file-type specific?\n4. **Check for conflicts**: scan existing rules for contradictions or duplication\n5. **Write the file**: concrete, verifiable instructions; one topic\n6. **Verify**: confirm file is under 200 lines and uses specific language\n\n## Authoring Checklist\n\n- [ ] Description starts with \"Use when...\" if this is actually a skill (wrong tool if so)\n- [ ] Topic is focused: one concern per file\n- [ ] Path scope matches actual applicability (don't always-load a Go-only rule)\n- [ ] Instructions are concrete and verifiable, not vague\n- [ ] No contradictions with existing rules in the same directory\n- [ ] File is under 200 lines\n\n## Anti-Patterns\n\n- **Vague rules**: \"write clean code\", \"be consistent\". Not actionable\n- **Duplicating defaults**: don't document what Claude already does correctly\n- **Over-specifying**: bloated rule files cause Claude to ignore them\n- **Wrong scope**: file-type-specific rules (Go, SQL) in always-load waste context\n- **Contradictions**: two rules giving conflicting guidance on the same behavior\n- **Workflow steps in rules**: if it's a multi-step process, use a skill instead\n\n## Additional Resources\n\n- Full glob pattern examples and good/bad rule samples: [references/rule-patterns.md](references/rule-patterns.md)\n- Official docs: https://code.claude.com/docs/en/memory#organize-rules-with-clauderules","tags":["create","rule","skill","issue","paultyng","agent-skills","ai-tools","claude-code","cursor","dotfiles"],"capabilities":["skill","source-paultyng","skill-create-rule","topic-agent-skills","topic-ai-tools","topic-claude-code","topic-cursor","topic-dotfiles"],"categories":["skill-issue"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/paultyng/skill-issue/create-rule","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add paultyng/skill-issue","source_repo":"https://github.com/paultyng/skill-issue","install_from":"skills.sh"}},"qualityScore":"0.454","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 8 github stars · SKILL.md body (3,733 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:09:00.613Z","embedding":null,"createdAt":"2026-05-18T13:21:25.456Z","updatedAt":"2026-05-18T19:09:00.613Z","lastSeenAt":"2026-05-18T19:09:00.613Z","tsv":"'/.claude/rules':18,127,317 '/docs/en/memory#organize-rules-with-clauderules':514 '1':301 '2':243,314 '200':261,358,422 '3':321 '4':332 '5':343 '6':352 'across':282 'action':435 'actual':374,391 'ad':287 'addit':498 'adher':266 'alreadi':443 'alway':155,186,396,468 'always-load':154,185,395,467 'anti':425 'anti-pattern':424 'anyth':45 'api-design.md':259 'applic':392 'architectur':73 'ask':22 'audit':285 'author':364 'behavior':52,192,481 'best':30 'bloat':449 'broad':68 'build':71 'bullet':276 'caus':452 'certain':93 'check':305,333 'checklist':365 'choic':200 'choos':39 'ci':205 'claud':11,176,442,453 'claude.md':36,67 'claude/rules':15,135,320 'claude/rules/frontend/react.md':144 'clean':430 'code':12,248,431 'code.claude.com':513 'code.claude.com/docs/en/memory#organize-rules-with-clauderules':512 'command':72 'commit':193 'concern':385 'concret':347,405 'confirm':354 'conflict':335,476 'consist':433 'context':70,471 'contradict':281,340,411,472 'convent':213 'correct':445 'creat':2,6,32 'create-rul':1 'decis':183 'default':437 'demand':81 'dens':278 'descript':256,366 'directori':223,311,418 'discov':141 'doc':511 'document':440 'domain':222 'duplic':342,436 'e.g':96,143 'e2e':225 'effect':237 'emphasi':293 'escal':195 'everi':61,75,168 'exampl':235,503 'exist':306,337,413 'file':14,59,94,99,147,180,218,253,264,284,329,346,355,387,419,451,460 'file-typ':328 'file-type-specif':459 'filenam':257 'focus':383 'format':25,148,247 'frequent':298 'frontmatt':165,189,326 'full':500 'git':134 'give':475 'glob':233,501 'go':97,157,214,226,400,464 'go-on':399 'good/bad':505 'grow':269 'guidanc':477 'header':274 'ignor':455 'import':290 'indent':245 'instead':116,497 'instruct':53,88,162,349,403 'invok':85 'languag':212,363 'larg':270 'line':262,359,423 'load':50,156,167,173,187,397,469 'locat':118 'longer':263 'machin':126 'make':90 'manag':204 'markdown':149,271 'match':66,179,390 'md':16,19,128,136 'mechan':42,46 'migrat':227 'multi':491 'multi-step':490 'must':292 'name':161 'new':288,302 'nice':249 'offici':510 'omit':152 'on-demand':79 'one':250,289,350,384 'open':177 'option':151 'output':197 'over-specifi':446 'overlap':313 'packag':203 'paragraph':279 'path':26,65,103,120,150,164,170,181,209,322,388 'path-scop':102,208 'pattern':234,426,502 'per':252,386 'person':121,316 'polici':196 'practic':31 'present':171 'process':493 'project':69,123,129,319 'py':216 'recurs':142 'reduc':265 'references/rule-patterns.md':230,231,508,509 'repeat':78,110 'resourc':499 'right':41 'rule':3,13,24,29,33,34,51,105,137,146,160,166,172,238,283,295,307,338,402,414,428,450,463,474,485,506 'rule-nam':159 'runner':202 'sampl':507 'scan':336 'scope':27,54,104,119,182,210,315,323,389,458 'see':229 'sens':91 'session':62,76,169 'share':130 'skill':38,77,115,376,496 'skill-create-rule' 'source-paultyng' 'space':244 'spec.ts':221 'specif':239,331,362,462 'specifi':448 'split':267 'sql':228,465 'src/api':224 'start':367 'step':483,492 'storag':117 'structur':272 'style':194 'subdirectori':139 'target':310 'task':111,201 'team':132 'test':98,217 'test.go':158,219 'test.ts':220 'testing.md':258 'tool':206,378 'toolchain':199 'topic':57,251,351,381 'topic-agent-skills' 'topic-ai-tools' 'topic-claude-code' 'topic-cursor' 'topic-dotfiles' 'ts':215 'two':473 'type':60,95,330,461 'univers':191,324 'updat':9,304 'use':4,49,100,113,184,207,242,273,361,369,494 'vagu':409,427 'verbos':198 'verifi':241,348,353,407 'via':133 'violat':299 'vs':35,37 'wast':470 'work':145 'workflow':74,82,112,300,482 'write':7,44,236,344,429 'wrong':377,457","prices":[{"id":"c31caf23-7827-4d50-829f-8f52af5bb5e9","listingId":"86330d4e-faad-4499-82d1-31ceaaa80a6c","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"paultyng","category":"skill-issue","install_from":"skills.sh"},"createdAt":"2026-05-18T13:21:25.456Z"}],"sources":[{"listingId":"86330d4e-faad-4499-82d1-31ceaaa80a6c","source":"github","sourceId":"paultyng/skill-issue/create-rule","sourceUrl":"https://github.com/paultyng/skill-issue/tree/main/skills/create-rule","isPrimary":false,"firstSeenAt":"2026-05-18T13:21:25.456Z","lastSeenAt":"2026-05-18T19:09:00.613Z"}],"details":{"listingId":"86330d4e-faad-4499-82d1-31ceaaa80a6c","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"paultyng","slug":"create-rule","github":{"repo":"paultyng/skill-issue","stars":8,"topics":["agent-skills","ai-tools","claude-code","cursor","dotfiles"],"license":"mit","html_url":"https://github.com/paultyng/skill-issue","pushed_at":"2026-05-18T18:26:54Z","description":"Personal Claude Code / Cursor agent skills, rules, and config","skill_md_sha":"5ef83ff98f75c57d0149dba3f6c91d4708b6e23c","skill_md_path":"skills/create-rule/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/paultyng/skill-issue/tree/main/skills/create-rule"},"layout":"multi","source":"github","category":"skill-issue","frontmatter":{"name":"create-rule","description":"Use when creating, writing, or updating a Claude Code rule file (.claude/rules/*.md or ~/.claude/rules/*.md), or when asking about rule format, path scoping, or rule best practices."},"skills_sh_url":"https://skills.sh/paultyng/skill-issue/create-rule"},"updatedAt":"2026-05-18T19:09:00.613Z"}}