The most interesting agents don’t just use skills. They create new ones when they find a gap, and those skills persist across sessions.
Author: James Phoenix | Date: March 2026
The Problem
You declare agent capabilities statically. CLAUDE.md lists available CLIs. Skill files define workflows. MCP servers expose tools. But the set is fixed at configuration time.
When the agent hits something it can’t do, the conversation stalls:
User: "Post this to X/Twitter"
Agent: "I don't have a social posting capability. Would you like me to..."
That’s the wrong answer. The agent has file system access, network access, and the ability to research APIs. It has everything it needs to solve the problem AND encode the solution for next time.
The Pattern: Self-Extension
Self-extension is when an agent detects a capability gap, builds a reusable skill to fill it, uses that skill immediately, and persists it for future sessions.
Gap detected → Reusability check → Skill created → Used immediately → Available forever
This is distinct from one-off problem solving. The agent doesn’t just complete the task. It writes the instructions so it (or another session) can complete the same class of task without re-deriving the approach.
The Reusability Gate
Not every task should become a skill. The filter matters:
| Condition | Why It Matters |
|---|---|
| Capability gap exists | No existing skill covers this |
| Reusable pattern | Will come up again, not a one-off |
| Structured process | Clear API, tool usage, or workflow |
| User benefit | Saves real time on future requests |
All four must be true. Without this gate, you get skill bloat. A one-time data migration doesn’t need a skill file. Posting to social media clearly recurs.
Implementation
The implementation requires three things working together.
1. File System Access to Skills Directory
Claude Code uses ~/.claude/skills/ with YAML frontmatter for auto-loading. The agent needs write access to this directory.
~/.claude/skills/
email-automation/SKILL.md
deployment/SKILL.md
typefully/SKILL.md ← agent-created
2. YAML Frontmatter for Auto-Discovery
Each skill file starts with metadata that Claude Code pattern-matches against user requests:
---
name: typefully
description: >
Create, schedule, and manage social media posts via Typefully.
Use this skill when asked to draft, schedule, post, or check
tweets, posts, threads, or social media content.
allowed-tools: Bash(./scripts/typefully.js:*)
---
The description field is the routing mechanism. When a user mentions “post a tweet,” Claude Code matches against skill descriptions and auto-loads the relevant file. No manual context loading required.
3. Explicit Instructions in the Identity File
The agent won’t self-extend unless you tell it to. This goes in CLAUDE.md:
## Self-Extension
Create a new skill when ALL of these are true:
1. No existing skill covers this request
2. The pattern will likely recur
3. It involves a clear process, API, or tool usage
4. It saves time on future requests
When creating:
1. Recognize the gap
2. Create ~/.claude/skills/[name]/SKILL.md with YAML frontmatter
3. Include full documentation (endpoints, error handling, examples)
4. Use it immediately for the current task
5. Tell the user what you built
This is roughly 15 lines of instruction that produces a qualitatively different behavior.
Real-World Case Study
Pawel Jozefiak documented this pattern with his agent “Wiz” (January 2026). The sequence:
- Pawel asked Wiz to post to X/Twitter
- No social posting skill existed
- Wiz researched options (direct API vs Typefully for anti-bot bypass)
- Wiz created
~/.claude/skills/typefully/SKILL.mdwith 450+ lines of API documentation - Wiz posted the tweet using the new skill
- Wiz told Pawel: “Created social-posting skill for future use”
That skill file now fires automatically whenever social posting is mentioned in any session. The agent went from “can’t do that” to “permanent capability” in a single interaction.
Over weeks, Wiz accumulated 13 skills. At least one was entirely self-created. The rest were human-authored but follow the same YAML frontmatter pattern, so the boundary between “configured” and “bootstrapped” skills is invisible at runtime.
Connection to Compound Engineering
This pattern maps directly to the doctrine’s core principle:
“The output is not features. The output is capability.”
Each bootstrapped skill is a permanent expansion of the agent’s capability surface. The cost of creating it is paid once. Every future session benefits. This is cognitive capital formation applied to the agent itself.
The compound dynamics:
Session 1: Agent can do X tasks
Session 5: Agent bootstrapped 2 skills → can do X+2 tasks
Session 20: Agent bootstrapped 8 skills → can do X+8 tasks
Session N: Capability grows based on actual usage patterns
Unlike pre-planned feature sets, bootstrapped skills reflect real demand. The agent builds what’s actually needed, not what someone predicted would be needed.
Pairing with Error Registries
Skill bootstrapping handles “I can’t do this.” Error registries handle “I did this wrong.”
Together they form a closed learning loop:
Can't do it → Bootstrap skill → Now I can
Did it wrong → Log to registry → Scheduled fix → Now I do it right
Pawel’s implementation uses error-registry.json with structured entries:
{
"id": "err-20260130-001",
"severity": "high",
"category": "data_loss",
"title": "Data replacement instead of merge",
"solution": "ALWAYS merge new data with existing. Never replace.",
"status": "resolved"
}
A scheduled task reads the registry, picks the highest-severity unfixed errors, and attempts resolution. The agent fixes its own mistakes on a schedule.
See: Error Registry for Agents for the pattern in detail.
Parallel Sub-Agents as Bootstrapped Workers
The pattern extends beyond skills. Sub-agents in ~/.claude/agents/ can also be bootstrapped when the agent recognizes a need for parallel specialized execution.
~/.claude/agents/
firecrawl-scraper.md ← parallel web scraping
web-researcher.md ← research with summarization
email-sender.md ← Gmail SMTP worker
Each agent file specifies: name, description, allowed tools, and model (often Haiku for workers, Sonnet for coordination). The master agent orchestrates. Specialists execute.
The key detail: worker agents use cheaper, faster models. They don’t need full reasoning capacity. They need to follow instructions quickly.
What Makes This Different from Plugin Systems
Traditional plugin systems are human-authored, centrally distributed, and version-controlled. Agent-bootstrapped skills are:
| Property | Traditional Plugins | Bootstrapped Skills |
|---|---|---|
| Created by | Human developers | The agent itself |
| Triggered by | Release schedule | Real-time capability gap |
| Scope | General purpose | Tailored to this user’s needs |
| Documentation | External docs | Self-contained in skill file |
| Discovery | Registry/marketplace | YAML frontmatter pattern matching |
The bootstrapped approach is more like an organism developing antibodies. Exposure to a new challenge produces a persistent capability tuned to the specific environment.
Risks and Mitigations
Skill Bloat
Risk: Agent creates skills for everything, polluting the skills directory.
Mitigation: The four-condition gate (gap, reusable, structured, beneficial). Review skills periodically and prune.
Quality Drift
Risk: Agent-authored documentation may be incomplete or wrong.
Mitigation: Treat bootstrapped skills as drafts. Review them. The agent should flag new skills for human review.
Security Surface
Risk: Self-created skills may request overly broad tool permissions.
Mitigation: allowed-tools in YAML frontmatter scopes what each skill can do. Review permissions on new skills.
Context Inflation
Risk: Too many skills means too much auto-loaded context.
Mitigation: Claude Code only loads skills whose descriptions match the current request. Inactive skills don’t consume context.
Implementation Checklist
- Agent has write access to
~/.claude/skills/ - Self-extension instructions added to CLAUDE.md (~15 lines)
- Reusability gate defined (all four conditions)
- YAML frontmatter format documented for the agent
- Review process for new skills (human-in-the-loop)
- Optional: error registry for self-fixing (
error-registry.json) - Optional: sub-agent directory for parallel workers (
~/.claude/agents/)
Key Insight
Static capability declarations are a snapshot. Bootstrapped skills are a growth trajectory. The difference is whether your agent’s competence is fixed or compounding.
The instructions cost ~15 lines in your identity file. The behavior change is categorical: agents that hit walls vs agents that build doors.
Related
- Agent Capabilities: Tools & Eyes – The starting point: declared tools and visibility
- Long-Running Agent Patterns – Skills as a core primitive for extended agent runs
- Learning Loops – Encoding problems into prevention (bootstrapping encodes capabilities)
- Error Registry for Agents – Structured error memory that complements skill bootstrapping
- The Meta-Engineer Identity – Building systems that build systems
- Ad-hoc to Scripts – Converting repeated workflows to persistent execution
- Agent-Native Architecture – Designing systems where agents are first-class citizens
References
- Pawel Jozefiak: When Your AI Agent Starts Fixing Itself – Real-world implementation with Wiz agent (January 2026)
- OpenAI: Shell, Skills, Compaction – Skills as a long-running agent primitive
