Context Engineering in Practice
agent37.club
Skills are the missing piece — the way you permanently extend the agent harness without re-explaining yourself every session.
The real cost: not just your time typing — it's the tokens you waste and the context window space you burn before the model even starts working.
A skill is a set of instructions — packaged as a simple folder — that teaches Claude how to handle specific tasks or workflows.
Instead of re-explaining your preferences, processes, and domain expertise in every conversation, you teach Claude once and benefit every time.
your-skill-name/ ├── SKILL.md # Required - main instructions ├── scripts/ # Optional - executable code │ ├── process.py │ └── validate.sh ├── references/ # Optional - documentation │ ├── api-guide.md │ └── examples/ └── assets/ # Optional - templates, fonts └── template.md
A CLAUDE.md file, but modular, shareable, and with lazy-loading superpowers.
| MCP (Connectivity) | Skills (Knowledge) |
|---|---|
| Connects Claude to services (Notion, Linear, GitHub...) | Teaches Claude how to use those services effectively |
| Provides real-time data access and tool invocation | Captures workflows and best practices |
| What Claude can do | How Claude should do it |
Access to tools, ingredients, and equipment.
Step-by-step instructions on how to create something valuable.
Users accomplish complex tasks without figuring out every step themselves.
The key insight — and why it matters for your token budget
Provides just enough info for Claude to know when the skill should be used. Sits in the system prompt at all times. Tiny footprint.
Full instructions and guidance. Only loaded when Claude decides the skill is relevant to the current task. This is the main payload.
Additional files (references/, scripts/, assets/) that Claude can choose to navigate and discover only as needed. Maximum efficiency.
Why this matters: This progressive disclosure minimizes token usage while maintaining specialized expertise. It's the same principle as lazy-loading in web development.
// The agentic loop (simplified) while (!done) { // 1. Build the messages array messages = [ system_prompt, // CLAUDE.md + skills L1 ...tool_definitions, // built-in + MCP tools ...conversation_history // user + assistant + tools ]; // 2. Call the API response = claude(messages); // 3. If skill matches → inject L2 content if (response.wants_skill) { system_prompt += skill.body; // L2 loaded! } // 4. Execute tool calls for (tool of response.tool_calls) { result = execute(tool); conversation_history.push(result); } }
Skills are not separate from the harness — they are a layer of the harness. Understanding this helps you design better skills.
Anatomy, frontmatter, descriptions, and instructions
The YAML frontmatter appears in Claude's system prompt. It's the first level of progressive disclosure — always present, always evaluated.
--- name: your-skill-name description: What it does. Use when user asks to [specific phrases]. --- # Your Skill Name ## Instructions ... (this is Level 2, loaded later)
That's all you need to start. Everything else is optional.
| Field | Required? | Rules |
|---|---|---|
| name | Yes | kebab-case, no spaces, no capitals |
| description | Yes | WHAT + WHEN, under 1024 chars |
| license | No | MIT, Apache-2.0, etc. |
| compatibility | No | Environment requirements |
| metadata | No | author, version, mcp-server |
No XML angle brackets (< >) in frontmatter. No "claude" or "anthropic" in the name. Frontmatter goes into the system prompt — malicious content could inject instructions.
Good: notion-project-setup
Bad: Notion Project Setup (spaces)
Bad: notion_project_setup (underscores)
Bad: NotionProjectSetup (capitals)
Don't include a README.md inside your skill folder. All documentation goes in SKILL.md or references/.
(For GitHub distribution, keep README at the repo root — separate from the skill folder.)
The skill loader is a deterministic file scanner, not an LLM. It looks for exact file names. This is by design — it's fast and reliable, no guessing.
Structure: [What it does] + [When to use it] + [Key capabilities]
# Specific and actionable description: Analyzes Figma design files and generates developer handoff docs. Use when user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code".
# Includes trigger phrases description: Manages Linear project workflows including sprint planning, task creation. Use when user mentions "sprint", "Linear tasks", "project planning", or "create tickets".
# Too vague description: Helps with projects.
# Missing triggers description: Creates sophisticated multi-page documentation systems.
# Too technical, no user phrases description: Implements the Project entity model with hierarchical relationships.
--- name: your-skill description: [...] --- # Your Skill Name ## Instructions ### Step 1: [First Major Step] Clear explanation of what happens. ### Step 2: [Second Step] Run `python scripts/fetch_data.py --project-id PROJECT_ID` Expected output: [describe success] ## Common Issues ### MCP Connection Failed If you see "Connection refused": 1. Verify MCP server is running 2. Confirm API key is valid 3. Try reconnecting
# Good
Run `python scripts/validate.py
--input {filename}` to check format.
If validation fails, common issues:
- Missing required fields
- Invalid date formats (use YYYY-MM-DD)
# Bad Validate the data before proceeding. # Good CRITICAL: Before calling create_project: - Project name is non-empty - At least one team member assigned - Start date is not in the past
Use bullet points and numbered lists. Keep SKILL.md under 5,000 words. Move detailed docs to references/.
Three categories, five patterns
Consistent, high-quality output — presentations, apps, designs, code.
Example: frontend-design skill
Multi-step processes with consistent methodology.
Example: skill-creator skill
Workflow guidance on top of MCP tool access.
Example: sentry-code-review skill
--- name: slides description: Create Agent 37 presentation slides. Use when building new weekly slide decks or editing existing ones. Contains the full theme, CSS, JS navigation, and conventions. --- # Agent 37 Slide Builder You now have the complete system for building Agent 37 presentation slides. Every deck must use this theme and structure exactly. ## File Convention - One HTML file per session: `week{N}-{slug}.html` - Self-contained — all CSS/JS inline - Link from README.md sessions table ## Complete CSS [... full theme CSS ...] ## Complete JS [... navigation code ...]
Every time we build a deck, we'd paste ~300 lines of CSS, explain the footer, explain the naming convention, explain the color system... every single time.
We say "build slides for week 5 about skills" and Claude already knows the entire design system. Zero repeated context.
## Workflow: Onboard New Customer ### Step 1: Create Account Call MCP tool: `create_customer` Parameters: name, email, company ### Step 2: Setup Payment Call MCP tool: `setup_payment_method` Wait for: payment method verification ### Step 3: Create Subscription Call MCP tool: `create_subscription` Parameters: plan_id, customer_id (Step 1) ### Step 4: Send Welcome Email Call MCP tool: `send_email` Template: welcome_email_template
Each step becomes a tool call in the agentic loop. The skill's sequential structure keeps Claude from trying to do steps out of order — which is a common failure mode without skills.
### Phase 1: Design Export (Figma MCP) 1. Export design assets from Figma 2. Generate design specifications 3. Create asset manifest ### Phase 2: Asset Storage (Drive MCP) 1. Create project folder in Drive 2. Upload all assets 3. Generate shareable links ### Phase 3: Task Creation (Linear MCP) 1. Create development tasks 2. Attach asset links to tasks 3. Assign to engineering team ### Phase 4: Notification (Slack MCP) 1. Post handoff summary to #engineering 2. Include asset links and task refs
Each MCP call result stays in context. A 4-phase workflow with 3 calls each = 12 tool results in the window. Without skill guidance, Claude might make 20+ exploratory calls instead. Skills reduce total tool calls by providing the exact sequence.
## Iterative Report Creation ### Initial Draft 1. Fetch data via MCP 2. Generate first draft report 3. Save to temporary file ### Quality Check 1. Run validation script: `scripts/check_report.py` 2. Identify issues: - Missing sections - Inconsistent formatting - Data validation errors ### Refinement Loop 1. Address each identified issue 2. Regenerate affected sections 3. Re-validate 4. Repeat until quality threshold met ### Finalization 1. Apply final formatting 2. Generate summary 3. Save final version
Use scripts/ for validation instead of asking Claude to check things in natural language. Code is deterministic; language interpretation isn't. A 10-line Python script costs zero tokens vs. Claude reasoning about quality for 500+ tokens each loop.
Use when: same outcome, different tools depending on context.
## Smart File Storage ### Decision Tree 1. Check file type and size 2. Determine best storage: - Large (>10MB): cloud storage MCP - Collaborative: Notion/Docs MCP - Code files: GitHub MCP - Temporary: local storage ### Execute Storage - Call appropriate MCP tool - Apply service-specific metadata ### Provide Context to User Explain why that storage was chosen
Key: clear decision criteria, fallback options, transparency.
Use when: your skill adds specialized knowledge beyond tool access.
## Payment Processing w/ Compliance ### Before Processing (Compliance Check) 1. Fetch transaction details via MCP 2. Apply compliance rules: - Check sanctions lists - Verify jurisdiction allowances - Assess risk level 3. Document compliance decision ### Processing IF compliance passed: - Call payment processing MCP tool - Apply fraud checks ELSE: - Flag for review - Create compliance case
Key: domain expertise embedded in logic, compliance before action.
"I need to set up a project workspace"
Like walking into Home Depot: "I need to fix a kitchen cabinet" — the employee points you to the right tools.
"I have Notion MCP connected — what can I do?"
Like picking out a new drill and asking how to use it for your specific job.
Most skills lean one direction. Knowing which framing fits helps you write better descriptions and instructions.
Make it work, make it trigger, make it efficient
Run queries in Claude.ai directly. Fast iteration, no setup.
Best for: personal skills, early development
Automate test cases in Claude Code for repeatable validation.
Best for: team skills, iterating on triggers
Build evaluation suites via skills API. Systematic testing at scale.
Best for: production skills, enterprise
The most effective skill creators iterate on a single challenging task until Claude succeeds, then extract the winning approach into a skill. This leverages Claude's in-context learning and provides faster signal than broad testing.
Should trigger: - "Help me set up a new ProjectHub workspace" - "I need to create a project in ProjectHub" - "Initialize a ProjectHub project for Q4 planning"
Should NOT trigger: - "What's the weather in San Francisco?" - "Help me write Python code" - "Create a spreadsheet" (unless your skill handles sheets)
| Metric | Target |
|---|---|
| Triggers on relevant queries | 90%+ |
| Completes workflow in X tool calls | Measure |
| Failed API calls per workflow | 0 |
| Signal | Check |
|---|---|
| Users don't need to re-prompt | Observe |
| Workflows complete without correction | Run 3-5x |
| Consistent results across sessions | Compare |
50% fewer tokens, 87% fewer messages, zero failures. Skills don't just save time — they save money and produce better results.
Fix: Add more detail and nuance to the description. Include keywords and trigger phrases users actually say.
Fix: Add negative triggers, be more specific about scope.
description: Advanced data analysis for CSV files. Use for statistical modeling, regression, clustering. Do NOT use for simple data exploration (use data-viz skill instead).
Ask Claude: "When would you use the [skill name] skill?" Claude will quote the description back. Adjust based on what's missing.
From personal use to org-wide deployment
Skills are published as an open standard (Agent Skills). The same skill should work across Claude or other AI platforms that adopt the standard.
Focus on outcomes, not features.
# Good "Set up complete project workspaces in seconds — including pages, databases, and templates." # Bad "A folder containing YAML frontmatter and Markdown instructions."
// Key capabilities // 1. List and manage skills GET /v1/skills // 2. Add skills to messages POST /v1/messages { "model": "claude-opus-4-6", "system": "...", "messages": [...], "container.skills": [ "my-skill-id" ] } // 3. Version control via Console // 4. Works with Agent SDK
| Use Case | Best Surface |
|---|---|
| End users interacting directly | Claude.ai / Code |
| Manual testing & iteration | Claude.ai / Code |
| Individual ad-hoc workflows | Claude.ai / Code |
| Applications using skills programmatically | API |
| Production deployments at scale | API |
| Automated pipelines & agents | API |
Skills in the API require the Code Execution Tool beta, which provides the secure environment skills need to run.
When things go wrong — and how to fix them
File not named exactly SKILL.md (case-sensitive)
Fix: Rename. Verify with ls -la
YAML formatting issue
# Wrong - missing delimiters name: my-skill description: Does things # Correct --- name: my-skill description: Does things ---
Name has spaces or capitals
# Wrong name: My Cool Skill # Correct name: my-cool-skill
Description too generic or missing trigger phrases.
Quick checklist:
Common causes:
1. Verify server connected 2. Check auth 3. Test MCP independently 4. Verify tool names (case-sensitive)
Symptom: Skill seems slow or responses are degraded
Causes:
With naive loading: 33% of your window gone on skills alone.
With progressive disclosure: only 5% used, and only for the relevant skill.
This is why the three-level system exists. It's not just convenience — it's critical for context window health.
Skills are not "add-ons" to the agent — they are a context management strategy. They solve the fundamental problem of agent harnesses: how to give the model the right knowledge at the right time without wasting the finite context window.
| Strategy | What It Does | Token Impact | From |
|---|---|---|---|
| Skills (Progressive Disclosure) | Load knowledge only when needed | Saves 20-60% of context | Week 5 |
| CLAUDE.md | Persistent project-level instructions | Always present (~200-500 tokens) | Week 3 |
| System Reminders | Re-inject objectives every turn | Small per-turn cost, high ROI | Week 3 |
| Todo Lists | Attention manipulation — keep model on track | Small cost, prevents drift | Week 3 |
| Compaction | Compress old context into summaries | Reclaims 40-70% of used space | Week 2 |
| Fresh Sessions | Start over when context is poisoned | 100% reclaim (lose history) | Week 3 |
| Sub-agents (Task tool) | Isolate expensive operations in child contexts | Protects parent window | Week 2 |
Skills are the proactive strategy — you design the knowledge structure before conversations happen. Everything else is reactive — managing context during conversations.
Teach Claude once. Benefit every conversation.
Save tokens. Get consistent results. Share with your team.
Resources:
agent37.club