Skills in CLAUDE.md
Benchmarked against: Anthropic — Using Skills with the API Architecture: CLAUDE.md references → Rules enforce → Skills execute
Skills integrate with SuperPortia's configuration through three touchpoints: CLAUDE.md, hooks, and rules.
The three-layer integration
| Layer | Role | Example |
|---|---|---|
| CLAUDE.md | References skills, defines when to suggest | "Use /66s-review for major decisions" |
| Rules | Define trigger conditions, behavioral constraints | "Cost awareness applies to all engine choices" |
| Skills | Detailed execution procedures | "Step 1: Apply White Hat analysis..." |
How CLAUDE.md references skills
CLAUDE.md is lean — it doesn't contain skill details, just pointers:
## Pre-Flight Check (30 seconds before any non-trivial task)
3D scoring 0-6: Blast Radius × Knowledge Freshness × Reversibility.
Full SOP: bulletin board + Cloud UB ub-a0914abf17a7
The Pre-Flight Check details are in UB, not in CLAUDE.md. If a full skill were needed, it would be loaded on demand.
Hook integration
Hooks can trigger skill-adjacent behavior:
| Hook | Trigger | Action |
|---|---|---|
| SessionStart | New session | Injects heartbeat, timestamp, mailbox status |
| PreToolUse | Before tool calls | Can gate skill invocation |
| PostToolUse | After tool calls | Can log skill results |
Example: SessionStart hook
# .claude/hooks/session-start.sh
echo "⏰ $(TZ='Asia/Taipei' date '+%Y-%m-%d %H:%M') (Taipei)"
# Hook output injected into context — not a skill, but skill-like
Rule → skill escalation
Some rules point to skills for complex procedures:
| Rule says | Skill provides |
|---|---|
| "Run Pre-Flight Check before non-trivial tasks" | PFC 3D scoring procedure |
| "Major decisions require systematic review" | /66s-review full Six Hats analysis |
| "Cost awareness applies to all engine choices" | /brain_lite emergency downshift |
Auto-discovery
Claude Code automatically discovers skills from the .claude/skills/ directory:
- Scans for directories in
.claude/skills/ - Each directory with a
prompt.mdbecomes a skill - Directory name = command name (e.g.,
66s-review→/66s-review) - Skills appear in the skills list automatically
No manual registration needed in CLAUDE.md.
Best practices
| Practice | Why |
|---|---|
| CLAUDE.md mentions when to use skills | Agents know skills exist |
| Rules define triggers, skills define procedures | Clean separation |
| Skills reference rules, not vice versa | Rules stay lean |
| Skills don't duplicate rule content | Avoid inconsistency |
Related pages
| Page | Relationship |
|---|---|
| Skills Overview | Full skills reference |
| CLAUDE.md + PD | PD architecture |
| Creating a Skill | How to build |