| name | rules-manager |
| description | Create, edit, and maintain AGENTS.md and .agents/rules/ — tech stack, commands, universal rules, rule index, and rule files. Use to add, modify, restructure, or optimize project rules, conventions, and constraints. |
| argument-hint | [init | add <rule-name> | edit | optimize | task description] |
<core_principle>
Rules consume tokens on every agent run. Keep them minimal, specific, and discoverable.
Two-tier system:
- AGENTS.md — Always loaded. Acts as the index + universal rules.
- .agents/rules/*.md — Modular rule files for focused topics (changelog, testing, deployment, etc.).
CRITICAL invariant: Every file in .agents/rules/ must be referenced in AGENTS.md so agents know it exists. AGENTS.md without a reference = orphaned rule = invisible to agents.
</core_principle>
<file_layout>
project-root/
├── AGENTS.md # Index + universal rules (always loaded)
└── .agents/
└── rules/
├── changelog.md # Rule for changelog management
├── testing.md # Rule for tests
└── deployment.md # Rule for deployment
AGENTS.md must contain a ## Rules section listing each .agents/rules/*.md file with a one-line description.
</file_layout>
<agents_md_template>
Minimal AGENTS.md with rules index:
# Project Name
Short description (1-2 lines).
## Tech Stack
- [Non-obvious tech only]
## Commands
- `[dev]` - Dev server
- `[test]` - Run tests
## Rules
The detailed rules live in `.agents/rules/`. Read the relevant file before acting:
- **Changelog** - [.agents/rules/changelog.md](.agents/rules/changelog.md) - When/how to update CHANGELOG.md
- **Testing** - [.agents/rules/testing.md](.agents/rules/testing.md) - Test conventions and coverage
- **Deployment** - [.agents/rules/deployment.md](.agents/rules/deployment.md) - Deploy checklist
## Universal Rules
- [2-3 critical rules that apply everywhere]
The ## Rules section is the index. Each bullet = one file in .agents/rules/. The ## Universal Rules section holds short, project-wide constraints that don't deserve their own file.
</agents_md_template>
<rule_file_template>
Each .agents/rules/<name>.md should be focused, short, and actionable.
# [Rule Title]
Short purpose statement (1 line).
## When this applies
- [Specific triggers - what task/context loads this rule]
## Rules
- [Specific, actionable rule]
- [Another rule with example if format matters]
## Example
[3-5 line concrete example, only if needed]
Size target: 20-60 lines per rule file. If longer, split into multiple files.
</rule_file_template>
<writing_rules>
Be specific, never vague:
NO: "Update changelog properly"
YES: "Append entry to CHANGELOG.md under ## Unreleased before every PR. Format: - [type] description (#PR)"
Prohibitions beat positive guidance:
NO: "Try to write tests"
YES: "NEVER merge without a passing test for the changed behavior"
Emphasis hierarchy: CRITICAL > NEVER > ALWAYS > IMPORTANT
- Lead each section with the most critical rule
- Use bold + keyword for non-negotiables:
**CRITICAL**: Never commit secrets
Do NOT include:
- Generic best practices ("write clean code", "DRY", "SOLID")
- Linter-enforced rules (ESLint, Prettier, Biome already do this)
- Things the agent discovers from the code (file structure, framework defaults)
- Marketing or vision statements
- Verbose paragraphs - one line is almost always enough
</writing_rules>
/rules-manager init - Bootstrap AGENTS.md + .agents/rules/
When the argument contains init:
- Detect project context - Read
package.json or equivalent for name, stack, scripts.
- Check existing files - If
AGENTS.md or .agents/rules/ already exists, read them and ASK before overwriting.
- Create skeleton - Write AGENTS.md with empty
## Rules index, ready to populate.
- Create
.agents/rules/ directory - Empty for now. New rules added via add workflow.
Target AGENTS.md size at init: under 40 lines.
/rules-manager add <name> - Add a new rule
When the argument starts with add:
- Confirm name - Slugify (e.g., "changelog management" ->
changelog). Ask user if unclear.
- Read existing AGENTS.md - Confirm it exists. If not, run
init first.
- Ask the user for rule content - What does the rule enforce? When does it apply? Any examples?
- Write
.agents/rules/<name>.md - Use the rule file template. Keep it 20-60 lines.
- Update AGENTS.md
## Rules section - Add a one-line bullet pointing to the new file:
- **<Title>** - [.agents/rules/<name>.md](.agents/rules/<name>.md) - <one-line purpose>
- Verify the link - Make sure the path in AGENTS.md exactly matches the created file.
CRITICAL: Step 5 is non-negotiable. A rule file without an index entry is invisible.
/rules-manager edit - Modify AGENTS.md directly
When the user wants to change AGENTS.md itself rather than add a rule file — update the tech stack, commands, universal rules, project description, or restructure sections:
- Read AGENTS.md - Load current content.
- Make the targeted edit in place - Change only the relevant section; leave unrelated sections untouched.
- Preserve the index - If touching
## Rules, keep every .agents/rules/*.md link intact.
- Stay minimal - Apply
<writing_rules>: specific, prohibitions over guidance, no bloat.
This is the default when the user references AGENTS.md content (not a rule file) — e.g. "add a command to AGENTS.md", "update the tech stack", "tighten the universal rules".
/rules-manager optimize - Audit and clean up
When the argument contains optimize:
- Inventory - List AGENTS.md and every file in
.agents/rules/.
- Check the index - For each file in
.agents/rules/, verify there's a matching bullet in AGENTS.md ## Rules. Flag missing entries.
- Check for orphans - For each AGENTS.md bullet, verify the file exists. Flag broken links.
- Apply bloat removal - For each rule file, remove:
- Linter-enforced rules
- Generic best practices
- Verbose explanations (compress to one line)
- Things derivable from code
- Compress - Paragraphs to bullets, multi-line rules to single lines.
- Show diff and ask before applying.
Target sizes:
- AGENTS.md: under 80 lines
- Each rule file: under 60 lines
Default - Add a rule based on description
When the argument is a free-form task (e.g., "add a rule about how we tag releases"):
- Treat as
add with auto-derived name.
- Ask the user 1-2 clarifying questions if the rule scope is unclear.
- Follow the
add workflow.
<rules_for_this_skill>
- This skill manages ALL of AGENTS.md (tech stack, commands, universal rules, index, description) and
.agents/rules/ — not just creating new rule files. Editing existing AGENTS.md content is fully in scope.
- ALWAYS update AGENTS.md
## Rules index when creating a file in .agents/rules/
- NEVER create a rule file without confirming with the user what it should contain
- NEVER overwrite existing AGENTS.md or rule files without asking
- Default to short rule files (20-60 lines). Split if larger.
- When user asks "create a rule", default to creating a file in
.agents/rules/ (not inline in AGENTS.md), unless the rule is 1-2 lines and fits the universal section.
- When the user references AGENTS.md content directly (a command, the stack, a universal rule), edit AGENTS.md in place via the
edit workflow — don't spin up a new rule file.
</rules_for_this_skill>
<reference_guides>
