tomevault-io Project Rules Writer
Create rules that solve a specific problem in a specific project — never generic ones. Analyse the project first, design, confirm with AskUserQuestion, then generate.
Core discipline: understand the problem → analyse the project → design the rule → confirm → generate. No file lands without user confirmation.
Shared writing-discipline rules across this and the other writer skills (project-skill-writer / project-agent-writer / project-skill-installer): see ../project-skill-writer/references/writer-discipline.md.
When to use
- "create a rule", "for X create a rule", "set the code style"
- "make the AI always …", "enforce naming convention", "configure AI behaviour"
- User references
.agents/rules/...,.trae/rules/..., or#RuleNamesyntax - Constrain AI behaviour for a specific project or file pattern
When NOT to use
| User wants | Delegate to |
|---|---|
| A skill | project-skill-writer |
| An agent / subagent | project-agent-writer |
| Install an existing skill | project-skill-installer |
| Documentation about how rules work | Just answer; don't generate |
Prerequisites
- Node.js ≥ 18
- A project where an AI assistant reads project rules (Trae, Cursor, Windsurf, Claude Code, etc.). This writer emits to
<project>/.agents/rules/; symlink or sync to.trae/rules//.cursor/rules/if your IDE needs that exact path.
Workflow (5 steps)
L1 Understand the problem → L2 Analyse the project → L3 Design the rule → L4 Confirm → L5 Generate + validate
L1 — Understand the problem
Don't ask "what rule do you want?" Infer from the prompt:
| Pattern | Rule type | Apply mode | Example |
|---|---|---|---|
| "AI keeps using wrong naming" | Convention | File-specific (globs) |
camelCase for .ts, snake_case for .py |
| "AI should always do X" | Behaviour | Always-apply | Always use the project logger |
| "AI ignores our architecture" | Structure | Smart (description) |
Enforce layered-arch boundaries |
| "AI generates wrong imports" | Style | File-specific | Use @/ path aliases in .tsx |
| "I want to toggle manually" | Manual | #RuleName |
Ad-hoc code-review checklist |
Extract: problem, scope (which files/contexts), expected behaviour, exceptions.
L2 — Analyse the project
Run two agents in parallel via the Task tool:
- project-scanner — structure, existing rules, patterns
- convention-detector — naming / style / architecture conventions
Detect: language(s), framework, existing rule files (.agents/rules/*.md first, then .trae/rules/*.md if present), lint/format configs (ESLint, Prettier, EditorConfig, Ruff), naming patterns, layering.
L3 — Design the rule
Apply-mode picker:
| Mode | Use when | Frontmatter |
|---|---|---|
| Always-apply | Rule fits every AI interaction | alwaysApply: true |
| File-specific | Rule applies to certain file types | globs: *.tsx,*.ts + alwaysApply: false |
| Smart | AI decides per request via the description | description: "..." + alwaysApply: false |
| Manual | User invokes via #RuleName |
no frontmatter |
Design principles: one problem per rule • follow project conventions • narrowest scope that covers the problem • no conflict with existing rules.
Frontmatter format gotchas (the gate enforces these in L5):
| Wrong | Right |
|---|---|
globs: "*.ts" |
globs: *.ts,*.tsx |
globs: ["*.ts"] |
globs: *.ts |
| absolute paths | project-relative |
missing description |
always include description |
alwaysApply: true AND globs: |
one or the other |
L4 — Confirm (mandatory)
Use AskUserQuestion to present the design before any file is written. Include the rule name, apply mode, and output path. Offer "create / adjust / skip" — and if multiple modes are valid, offer the mode choice as a separate question. Never write a file without user confirmation. If the user says "adjust", loop back to L3.
L5 — Generate + validate
node scripts/cli.cjs init \
--skill-dir <this-skill-dir> \
--name <rule-name> \
--description "<when-this-rule-applies>" \
--output-dir <project>/.agents/rules/
Fallback: if init doesn't fit, write the .md file directly using assets/rule.md.template.
Then run quality-validator. Pre-delivery checklist:
-
globs: comma-separated, no quotes, no array - No absolute paths in rule content
-
descriptionpresent and explains when the rule applies -
alwaysApplyandglobsnot both active - No conflict with existing rules (from L2 analysis)
- Rule content is actionable (specific constraints, not vague advice)
- Content in English
Delivery report
Rule created:
Name: {rule-name}
Mode: {always|file-specific|smart|manual}
Path: {project-relative path}
Frontmatter:
description: {value}
globs: {value if applicable}
alwaysApply: {value}
Usage: {one-line note on how it fires}
Error handling
| Problem | Resolution |
|---|---|
| User's ask is too vague | Infer the most likely rule type from context, confirm in L4 |
| Multiple valid apply modes | Surface the choice in L4 |
.agents/rules/ doesn't exist |
Create it under the project root |
| User wants a skill / agent / install | Route to the right writer skill |
| User says "adjust design" in L4 | Loop back to L3 with feedback |
| Rule contains an absolute path | Reject; convert to project-relative |
| New rule conflicts with an existing one | Show diff, ask user to merge / replace / rename |
globs malformed |
Auto-fix: drop quotes, flatten arrays, use commas |
| No detectable conventions | Fall back to language defaults; note the assumption in the delivery report |
Boundaries
This skill only: analyses project context, designs a rule, confirms with the user, generates a frontmatter+markdown .md at <project>/.agents/rules/ (project-relative, IDE-neutral), validates the result.
This skill does not: create skills (→ project-skill-writer), create agents (→ project-agent-writer), install skills (→ project-skill-installer), edit any IDE's own settings, or install rules globally.
Agents and references
- Agents: project-scanner, convention-detector, quality-validator
- references/rule-types.md — pick the right rule type from a problem
- examples/application-modes.md — all four apply modes with frontmatter examples
- assets/rule.md.template — scaffold
- assets/trae-rules-docs.md — vendored frontmatter format reference (originally from Trae's rules doc; format is shared across Trae / Cursor / Windsurf)
Source: learnwy/skills — distributed by TomeVault.