create-playbook

Files (6)

• SKILL.md
• autonomous-template.md · templates/
• gated-template.md · templates/
• manual-template.md · templates/
• simple-skill.md · templates/
• stateful-skill.md · templates/

SKILL.md (first lines)

# Create Playbook

> ℹ️ **First, set expectations:** before anything else, print one short line with this skill's version and its most recent change — the top entry of `metadata.changelog` above — e.g. `create-playbook vX.Y — recent: <summary>`. Then proceed.

Create a new skill. Determines the right complexity tier and generates from the appropriate template.

> For concepts and patterns, see the [README](../../README.md).
> Tier templates are bundled with this skill in [templates/](templates/) — reference them at runtime via `${CLAUDE_SKILL_DIR}/templates/`.

---

## Workflow

### Step 1: Check for Existing Skills

```bash
ls -d .claude/skills/*/ 2>/dev/null | head -10
ls -d ~/.claude/skills/*/ 2>/dev/null | head -10
```

If similar skill exists, ask: update it, create variant, or proceed with new?

### Step 2: Gather Core Requirements

Ask or extract from context:

1. **Name**: lowercase-with-hyphens, descriptive. For project/personal skills the **directory name is the command** (`name:` is display-only); for plugin skills `name:` sets the command segment — keep name and directory identical so they never drift.
2. **Purpose** → the `description:` field: third person, *what it does + when to use it*, key use case first — the skill listing truncates `description` + `when_to_use` at 1,536 characters.
3. **Tools needed**: Which tools will it use?

### Step 3: Determine Complexity Tier

Ask these questions to classify:

**Q1: Does this skill read or write any files, APIs, or external state?**
- NO → **Tier 1: Simple Skill** (skip to Step 4)
- YES → Continue to Q2

**Q2: Will this run unattended, on a schedule, or need reliability guarantees?**
- NO → **Tier 2: Stateful Skill** (skip to Step 4)
- YES → Continue to Q3

**Q3: What automation level?**
- Safe to run completely unattended, **no approval needed at any point** → `autonomous`
- Needs human approval at checkpoints → `gated`
- Human monitors entire execution → `manual`

⚠️ **Critical**: If user says "autonomous" but also mentions approval/review steps, clarify:
> "Autonomous playbooks cannot have approval gates — they run unattended and would hang waiting for approval that never comes. Should this be `gated` instead?"

→ **Tier 3: Full Playbook**

### Step 4: Gather Tier-Specific Requirements

**For Tier 1 (Simple Skill):**
- Process steps (what does it do?)
- Outputs (what does it produce?)

**For Tier 2 (Stateful Skill):**
- State dependencies (what files/APIs does it read/write?)
- Process steps
- Outputs

**For Tier 3 (Full Playbook):**
- State dependencies
- Automation level (autonomous/gated/manual)
- Schedule (if autonomous or gated): cron expression
- Process steps
- Approval gates (if gated): where? ⚠️ **Not allowed for autonomous — see No-Gates Rule**
- Prerequisites

### Step 4b: Supporting Files

Ask: Does this skill need supporting files (templates, example outputs, helper scripts)?

- If YES: plan supporting files alongside SKILL.md using the official names — `reference.md` (detailed docs), `examples.md` (usage examples), `scripts/` (executables), `templates/` (files to fill in) — each referenced from SKILL.md so Claude knows when to load them (they load only when referenced, never automatically). Point at bundled scripts via `${CLAUDE_SKILL_DIR}`. Keep SKILL.md under 500 lines — move large reference material to separate files.
- If NO: proceed.

### Step 4c: Self-Improvement Option

Ask the user:

> **Should this skill be self-improving?**
>
> A self-improving skill watches its own runs and refines *how* it works. It never changes *what it is for* or *when it must stop*. It doesn't edit itself freely: runs write **proposals**, and a later run (or `/adjust-playbook --review-proposals`) applies them under rate limits, after a conflict check and a replay of fixed scenarios.

If NO: proceed. If YES, gather the contract. **Every answer lands in the generated skill**; none of these questions is optional:

1. **Counterweight (the mission as a tension).** "What does this skill optimize for, and what must it *also* achieve, by when, measurably?" Push for a number, for example "rigorous AND reaches a verdict within 6 runs". A skill that improves itself against one value drifts to that value's extreme. Without a counterweight, "more careful" always reads as "better". → `## Mission 🔒`
2. **Constraints.** "When must it stop or conclude? What may it write, and what must it never touch?" → `## Constraints 🔒`
3. **Scenarios.** Draft 3–5 *given → expect* cases from answers 1–2 and confirm them with the user. Include at least one case that tests the counterweight (e.g. "no signal by run 6 → calls it noise") and one that tests a stop rule. → `## Scenarios 🔒`
4. **Pace (offer the defaults).** At least **3 runs** of evidence between edits to the same step, at most **2 applied edits per week**, and a check-back **3 runs** after an edit is applied.

Then append the Controlled Self-Improvement contract (Appendix) to the generated skill and seed the `self-improvement.md` ledger next to it.

### Step 4d: Deep Reasoning

If this skill involves complex multi-step logic or architectural decisions, add `ultrathink` anywhere in the skill body to request deeper reasoning when it runs.

### Step 4e: Reuse Check (Composition)

Does any planned step duplicate work an existing skill already does? If so, **invoke that skill instead of reimplementing it** — ``Invoke `/child-skill` `` (namespace cross-plugin calls: ``/plugin:child-skill ``). Then:

- Add `Skill` to `allowed-tools`.
- List each child under a `## Composes` section so the dependency is greppable.
- Call the **unversioned** name to ride the latest version (so child fixes propagate automatically); pin `/child-vN` only to freeze against a child's breaking changes.

See **The Composition Rule** in Design Constraints. Never call another skill's `scripts/`/`reference.md`/templates directly — go through the skill entry point.

### Step 5: Determine Location

| Scope | Location | Use When |
|-------|----------|----------|
| Personal | `~/.claude/skills/[name]/` | Only you use it |
| Project | `.claude/skills/[name]/` | Team shares it |
| Plugin | `plugins/[plugin]/skills/[name]/` | Distribute widely |

Default to project scope unless specified.

From Abilityai/trinity-skills, Apache-2.0.

More from Abilityai/trinity-skills