skill-design

# Skill Design Loop (SDL)

A systematic methodology for designing **production-grade agent skills** that are maintainable, composable, and secure.

## When to Use

- Creating a new reusable agent capability
- Packaging repeated workflows into portable skills
- Teaching an agent specialized domain knowledge
- Building skills that need evaluation and security hardening

## When NOT to Use

- One-off guidance (use direct instructions instead)
- Project-specific rules (use CLAUDE.md or project instructions)
- Simple prompts without reuse potential

---

## Quick Start (Happy Path)

1. **Capture requirements** in an Uncertainty Ledger
2. **Decide** if this should be a skill (vs. one-off guidance)
3. **Define scope**: Goal, Non-goals, Preconditions
4. **Write contract first**: Definition of Done + evaluation prompts
5. **Design disclosure map**: frontmatter -> SKILL.md -> references/
6. **Craft matching signals**: name + description as retrieval interface
7. **Author instructions**: procedure with checkpoints
8. **Add security posture**: trust boundaries, confirmations
9. **Validate**: spec compliance + regression prompts
10. **Package**: metadata, versioning, change notes

---

## The 10-Step SDL

### Step 0: Uncertainty Ledger (VOI-Driven)

Before designing, explicitly document:

```yaml
knowns:
  - [list guaranteed inputs and constraints]
assumptions:
  - [list things assumed but not confirmed]
questions:
  - [list 1-3 highest-VOI clarifying questions]
risks:
  - [list what could go wrong if assumptions are wrong]
```

**Key principle**: Ask only questions where expected value of information exceeds cost. If you cannot ask, proceed with safest defaults and document assumptions.

### Step 1: Skill Fit Decision

Answer: Should this be a skill or something else?

| Choose SKILL when | Choose OTHER when |
|-------------------|-------------------|
| Capability recurs across tasks/sessions | One-off guidance needed |
| Benefits from progressive disclosure | Always-on rules n