# How to Build Great Agent Skills — Synthesized Research

Compiled from: Thariq (Anthropic), Ole Lehmann, Aakash Gupta, Corey Haines, Anthropic's Official Guide, Lee Han Chung's deep dive, and our own skill-creator spec.

---

## 1. What Skills Actually Are

Skills are NOT executable code. They are **prompt templates** that inject domain-specific instructions into the conversation context. When invoked, a skill modifies:
- **Conversation context** — by injecting instruction prompts
- **Execution context** — by changing tool permissions, model, constraints

The AI model (Claude) decides when to invoke a skill based on textual descriptions in its system prompt. There is no algorithmic routing — it's pure LLM reasoning.

**Key insight from Thariq:** Skills are entire *directories*, not just markdown files. They contain executable scripts, local assets, configuration hooks, and data that the agent can discover and manipulate.

---

## 2. Architecture: Progressive Disclosure

The #1 design principle. Skills use a three-level loading system:

| Level | What | When Loaded | Size |
|-------|------|-------------|------|
| 1. Metadata | `name` + `description` in frontmatter | Always in context | ~100 words |
| 2. SKILL.md body | Core instructions, workflow | When skill triggers | <5k words |
| 3. Bundled resources | scripts/, references/, assets/ | As needed by agent | Unlimited |

**Why this matters:** The context window is a shared resource. Every token your skill uses is a token the agent can't use for reasoning, conversation history, or other skills.

---

## 3. Skill Anatomy

```
skill-name/
├── SKILL.md              (required — frontmatter + instructions)
├── scripts/              (executable code for deterministic tasks)
├── references/           (documentation loaded on-demand)
└── assets/               (files used in output, not loaded into context)
```

### SKILL.md Structure

```yaml
---
name: skill-name
description: What this does AND when to trigger it. This is the primary 
  triggering mechanism. Include all "when to use" here — NOT in the body.
---
```

Body = instructions for the agent. Only loaded AFTER the skill triggers.

### What NOT to Include
- README.md, INSTALLATION_GUIDE.md, CHANGELOG.md
- User-facing documentation
- Setup/testing procedures
- Information the model already knows

---

## 4. Thariq's Key Lessons (Anthropic Engineer)

### a) Give the model flexibility
Don't force rigid paths. Include a JSON config file. If details are missing, the agent should pause and ask.

### b) Optimize the description field
Write it for the AI's parsing logic — it's a highly specific trigger for when to deploy the skill.

### c) Provide memory to skills
Include an append-only log or SQLite database inside the skill folder. Store data in stable folders (`${CLAUDE_PLUGIN_DATA}`) to survive upgrades.

### d) Store scripts and generated code
Give Claude scripts so it can focus on orchestration, not reconstructing boilerplate.

### e) Avoid stating the obvious
Claude is already smart. Focus on information that pushes it beyond conventional thinking — like specific design system preferences to avoid generic UI patterns.

### f) Enforce code quality
Build skills that enforce unique formatting rules and testing practices.

### g) "Seeing like an Agent"
Design the action space as if equipping a "human in a box" — give the agent Unix primitives, file system access, and persistent memory. The agent loop: **gather context → take action → verify work**.

### h) Nine categories of skills
**Code track:** Library/API references, Code quality
**Workflow track:** Business process workflows, Product verification (headless browser assertions)

---

## 5. Ole Lehmann's Autoresearch Method

Adapted from Karpathy's autonomous experimentation methodology:

1. **Generate** outputs from a skill using test inputs
2. **Score** outputs against predefined binary (yes/no) criteria
3. **Analyze** failure patterns
4. **Mutate** the skill prompt to address failures
5. **Iterate** — keep mutations that improve scores, discard ones that don't

Result: The skill self-improves overnight through hundreds of automated experiments. Ole's GitHub: `olelehmann100kMRR/autoresearch-skill`

---

## 6. Aakash Gupta's Addition

Applied autoresearch to product management skills:
- Define **binary evaluation criteria** (yes/no questions to assess output quality)
- Run **automated optimization loops** — Claude generates, tests, analyzes failures, refines
- **Compounding gains** — hundreds of experiments overnight, far exceeding human pace

Key frame: "AI agents optimize tactics autonomously while humans focus on strategy."

---

## 7. Vasilije/Cognee (tricalt) — Self-Improving Agent Skills

The observe→inspect→amend→evaluate loop:
1. **Observe** — watch how the skill performs on real tasks
2. **Inspect** — identify where it struggles or produces suboptimal output
3. **Amend** — modify the skill instructions
4. **Evaluate** — test again, keep improvements

---

## 8. Anthropic's Official Guide — Key Rules

### Concise is Key
> "The context window is a public good."

Default assumption: the model is already very smart. Only add context it doesn't already have. Challenge each piece: "Does this justify its token cost?"

**Prefer concise examples over verbose explanations.**

### Set Appropriate Degrees of Freedom
- **High freedom** (text instructions) — when multiple approaches are valid
- **Medium freedom** (pseudocode/scripts with params) — preferred pattern exists, some variation OK
- **Low freedom** (specific scripts, few params) — operations are fragile, consistency critical

Metaphor: narrow bridge with cliffs → specific guardrails. Open field → many routes OK.

### Reference Organization Patterns
1. **High-level guide with references** — SKILL.md links to FORMS.md, REFERENCE.md, etc.
2. **Domain-specific organization** — subdirectories per domain (finance.md, sales.md)
3. **Conditional details** — basic in SKILL.md, advanced in references

### Frontmatter Rules
- Only `name` and `description` in YAML
- Description = primary triggering mechanism
- Include ALL "when to use" info in description, NOT in body
- Body is only loaded after triggering, so trigger info there is useless

### Iteration Workflow
1. Use the skill on real tasks
2. Notice struggles or inefficiencies  
3. Identify how SKILL.md or resources should be updated
4. Implement changes and test again

---

## 9. Design Patterns for Quality

### Progressive Disclosure Patterns
- Keep SKILL.md body under **500 lines**
- Split content when approaching this limit
- Reference files must be clearly referenced from SKILL.md with instructions on when to read them
- Avoid deeply nested references — keep one level deep from SKILL.md
- For reference files >100 lines, include a table of contents

### Naming Conventions
- Lowercase, digits, hyphens only
- Under 64 characters
- Prefer short, verb-led phrases
- Namespace by tool when helpful (e.g., `gh-address-comments`)

### What NOT to Do
- Don't create README.md, CHANGELOG.md, etc.
- Don't include user-facing documentation
- Don't duplicate info between SKILL.md and references
- Don't state things the model already knows
- Don't use symlinks (packaging will reject them)

---

## 10. Cross-Referencing Skills (Corey's Pattern)

Corey's marketing skills reference each other and build on shared context:
- **Foundation skill** (`product-marketing-context`) — every other skill reads it first
- Skills are organized into **categories** (SEO, CRO, Content, Paid, Growth, Sales, Strategy)
- Each skill has a "Related Skills" section for the dependency map
- The README uses an ASCII art dependency diagram showing the architecture

This creates a **skill ecosystem**, not just individual skills.

---

## Summary: The 10 Commandments of Great Skills

1. **Progressive disclosure** — metadata → SKILL.md → references/scripts
2. **Context is precious** — every token counts; be concise
3. **Description is everything** — it's the only trigger mechanism
4. **Don't teach what the model knows** — add only non-obvious domain knowledge
5. **Include scripts for deterministic tasks** — don't make the model rewrite code
6. **Provide memory** — append-only logs or databases for skill state
7. **Match freedom to fragility** — guardrails where operations are brittle
8. **Test with real tasks, iterate** — autoresearch for automated improvement
9. **Reference files, not monoliths** — split large skills into domain-specific refs
10. **Skills are ecosystems** — they should cross-reference and build on each other