Three-Tier Skill Architecture
Skill rules belong in three layers — manifesto, cross-project behaviors, per-project specifics. Each tier has a different lifecycle, a different audience, and a different promotion rule. Mixing them produces unmaintainable Claude instructions.
The problem
If you write Claude rules in one place, two things happen. First, the file becomes too long and Claude stops reading it. Second, you can't tell which rules are about you as an operator, which are about how Claude should behave generally, and which are about this specific project's conventions. So you stop maintaining it, and over time the rules drift from how you actually work.
The decision
Three tiers, each with its own file, its own audience, and its own promotion rule:
Tier 1 — Manifesto. Lives at ~/.claude/CLAUDE.md. Hand-written. Strategic. Loaded into every session. This is your operating philosophy: how you want Claude to think, what you reject, what mandate Claude is operating under. Short. Punchy. Never auto-generated.
Tier 2 — Cross-project Claude behaviors. Lives at ~/.claude/learning/global-rules.md, imported by Tier 1 via an @import line. Concrete behavioral rules that apply regardless of which project you're in: how to ask clarifying questions, how to handle ambiguity, how to write code, how to communicate corrections. These graduate from Tier 3 when they prove generally useful.
Tier 3 — Per-project specifics. Lives at <project>/.claude/learning/global.md. Rules that only matter inside a particular codebase: this team's naming conventions, this product's domain language, this stack's gotchas. Per-project, dream-extracted from session logs, lifecycle bound to the project.
The promotion rule
A Tier 3 rule earns promotion to Tier 2 when either of these is true:
- Within-project elevation. The rule is about Claude behavior — communication style, code hygiene, ambiguity handling, ergonomics, tool selection — rather than business-specific logic. Promote regardless of repo count, because behavior generalizes immediately.
- Cross-project frequency. The rule appears in 2+ projects' Tier 3 sources. Activates when the second project independently arrives at the same conclusion.
The "OR" is important. The first path (single-project elevation for behavioral rules) lets you start formalizing patterns from day one with N=1, instead of waiting for a second project to validate them.
What this rejects
- One giant CLAUDE.md. Files over ~150 lines stop getting read carefully. Tiers force pruning.
- Project rules embedded in the global file. When you switch projects, those rules become dead weight — or worse, they fight the new project's conventions.
- Manifesto language at the rule level. "Be excellent" doesn't help Claude write a function. Strategic intent and operational rules belong in different files.
What I'd revisit
The promotion mechanism is currently manual — a sweep skill scans Tier 3 files weekly and proposes Tier 2 candidates. If you have many projects, automation matters more. If you have few, the manual review is fine. The right answer depends on N.
The "two-path OR" rule is doing real work, but it's also the part most likely to be wrong. The hardest call is whether something feels behavioral (promote) or business-specific (don't). I expect to refine the test as more rules graduate.