Tier 1: Intent Routing via Metadata
In Level 1, Claude reads only the name and description field in the YAML frontmatter of every installed Skill. This is loaded directly into the system context on session initialization.
Because Claude uses this field to determine whether to activate a Skill, the description is an intent router, not a passive label.
YAML
# GOOD: Explicit functionality and trigger keywords
name: post-mortem-analysis
description: Generates incident post-mortem reports from incident logs, Slack threads, and Jira tickets. Trigger when the user mentions post-mortem, incident review, RCA, root cause analysis, or outage summary.
The Description Stress-Test: Read only the name and description fields of your installed Skills without looking at their instructions. Could an external engineer (or an LLM) correctly route 10 different user requests to the right Skill? If not, rewrite the description.
Tier 2: Streamlining the Core Workflow File
When Level 1 matches user intent, Claude reads the SKILL.md body file into active context.
Anthropic guidelines recommend keeping the main SKILL.md file under 500 lines (roughly 1,500–2,000 words). Treat the SKILL.md file as a high-level orchestration index: keep core workflows inline, but offload detailed domain specifications, API tables, and optional branch logic into separate reference files.
incident-review-skill/
├── SKILL.md # Lean orchestration core (<500 lines)
├── schemas.md # Output payload definitions (Loaded on demand)
├── runaway-process.md # Specific edge-case guide (Loaded only if triggered)
└── scripts/
└── parse_logs.py # Executed as a tool (Zero context overhead)
Tier 3: Context-Free Scripts vs. On-Demand Documentation
Level 3 contains two distinct resource types that engineers frequently confuse:
- Reference Documents: Markdown files, OpenAPI specs, or style guides intended for Claude to read into context only when specifically referenced.
- Executable Scripts: Python, Bash, or Node.js scripts meant for Claude to execute as local tools.
Executable scripts run deterministically without burning context window tokens on source code parsing. A 2,000-line log parsing script written in Python returns a raw JSON output to Claude in milliseconds, keeping source code out of the context window while providing 100% deterministic reliability.
