meta-rules

name	meta-rules
description	Agent and skill writing rules for Claude Code plugins. Enforces anti-bloat constraints, token limits, and quality standards for all auto-generated improvements.
user-invocable	false

Meta-Rules — Plugin Component Quality Gates

Rules that govern how agents, skills, and workflows should be written. All auto-generated improvements MUST pass these rules before application.

Token Limits

These limits apply to auto-generated improvements (output of improvement-generator and auto-optimizer). They constrain individual components, not the main orchestrating SKILL.md which serves as a command router.

Component	Max Tokens	Measurement	Scope
Agent description (.md)	1000	chars/4	Per agent file
Knowledge skill (SKILL.md)	500	chars/4	Per knowledge skill (meta-rules, analysis-patterns, cost-tracking)
Main skill (SKILL.md)	No hard limit	—	Orchestrating skill — uses lazy-load via resources/
Single example	200	chars/4	Per example block
Hook script	100 lines	line count	Per standalone script

Writing Rules

Agents

1. ALWAYS use imperative voice in instructions ("Analyze the traces" not "You should analyze the traces")
2. ALWAYS specify input and output formats explicitly
3. NEVER exceed 1000 tokens in the agent description
4. ALWAYS include model assignment (haiku/sonnet/opus) with justification
5. Include 1-2 examples maximum — more examples waste context
6. NEVER use vague instructions ("do your best", "try to", "if possible")
7. ALWAYS specify exit conditions — when is the agent done?

Skills

1. ALWAYS keep SKILL.md under 500 tokens — use resources/ for details
2. ALWAYS use the 2-layer structure: SKILL.md (core) + resources/ (on-demand)
3. NEVER load all resources at once — lazy-load per phase/command
4. ALWAYS declare allowed-tools explicitly — minimal permissions
5. ALWAYS include trigger conditions in the description

Hooks

1. ALWAYS complete within 50ms — hooks block execution
2. ALWAYS use || true fallback — hook failures must not break workflow
3. NEVER read large files in hooks — use append-only writes
4. ALWAYS use set -euo pipefail in scripts
5. NEVER install external dependencies — bash + jq only

Workflows

1. ALWAYS define phase transitions with explicit entry/exit conditions
2. NEVER allow unbounded loops — always set max_iterations
3. ALWAYS provide rollback mechanisms for destructive operations
4. NEVER modify files without the user's explicit request

Anti-Bloat Rules

Prevent infinite growth of auto-generated content:

1. Rule addition: When adding a new rule, check if an existing rule covers the same case → merge instead of add
2. Example cap: Maximum 2 examples per section. If adding a third, remove the least useful existing one
3. Description growth: If a component grows beyond its token limit after improvement, the improvement MUST be rewritten to fit within the limit
4. Periodic review: Every 10 improvement cycles, run a deduplication pass on all agent/skill content
5. Justification required: Every rule must have a "why" — rules without justification are candidates for removal

Validation Procedure

When checking a component against meta-rules:

1. Measure token count (chars / 4)
2. Check against component-type limit
3. Verify required sections exist (input, output, model assignment for agents)
4. Check for prohibited patterns (vague instructions, missing exit conditions)
5. Return: { passed: bool, violations: string[], token_count: number }