| name | agents-tier-system |
| description | Full tier assignments, pairing conventions, and authoring checklist for .agents/ rules and skills. Use when creating or reviewing a rule or skill, deciding Tier 1 vs 2 vs 3, or auditing attachment cost. |
.agents/ tier system — full reference
Always-on priming: .agents/rules/agents-tier-system.md. Entry points: .agents/README.md, agents-first-convention, writing-agents-config.
Discover on disk (do not maintain partial catalogs here)
| Tier | How to list |
|---|
| Tier 1 | Frontmatter audit in agents-tier-system rule — budget set there |
| Tier 2 | ls .agents/rules/*.md + globs: in frontmatter |
| Tier 3 | alwaysApply: false, no globs: — intent via description |
| Skills | ls .agents/skills — runtime discovery via descriptions |
Pairing examples in this repo: architecture-priming ↔ improve-codebase-architecture; docs-governance-priming ↔ docs-governance + docs-lifecycle-sweep; docs-voice-priming ↔ docs-voice; agents-tier-system rule + skill; authoring-discipline rule + PROSE; verify-after-each-step rule + skill.
Caution: avoid stacking broad globs without thin priming bodies.
Authoring guidelines
Adding a new rule
- Decide the tier before writing.
- Tier 1 needs justification — every turn? If file/intent scoped, demote to Tier 2 or Tier 3.
- Tier 2 globs — broadest meaningful scope; pair with skill when applicable.
- Source + symlink per
agents-first-convention.
Adding a new skill
- Needs a rule? Hard
NEVER/ALWAYS + file-scoped work → Tier 2 priming rule.
- Skill-only — explicit trigger phrases in description.
- User-only orchestrator —
disable-model-invocation: true + delegate to model skill.
- Size —
writing-agents-config § SKILL.md size tiers.
Tier 1 audit command
for f in .agents/rules/*.md .agents/lessons.md; do
awk '/^---$/{c++; next} c==1 && /^alwaysApply: true$/{found=1; exit} END{exit !found}' "$f" && echo "$f"
done
Done when: tier choice justified; pairing checklist satisfied; Tier-1 audit command run when adding always-on rules.
Reference