create-playbook

name	create-playbook
description	Create a new skill or playbook. Guides through requirements gathering and generates the appropriate template based on complexity.
disable-model-invocation	false
user-invocable	true
argument-hint	[skill-name]
allowed-tools	Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
metadata	{"version":"2.16","created":"2025-02-10T00:00:00.000Z","updated":"2026-08-18T00:00:00.000Z","author":"Ability.ai","changelog":["2.16: Platform-truth refresh (Trinity v0.9.0, tag 93d7ce7c) — Long-Running-Task Rule: turn-end kills background BASH jobs/monitors, but since trinity#2127 a headless run waits for background subagents/forks (bounded by the execution timeout + 300s idle-finalize, rebuilt base image); Foreground-Fork Rule keeps `background: false` as the contract for the right reason (deterministic on every image, mandatory pre-0.9). Reporting Rule guard now also swallows the `requires an agent-scoped API key` refusal — a user/admin-key session sees the tool but cannot report (mcp-server reports.ts)","2.15: Add the Playbook-Call Rule to Design Constraints + a validation-checklist line — a playbook is the unit of inter-agent work (fleet convention protocols/playbook-call.md, operator direction 2026-08-16): anything another agent, schedule, orchestrator, or pipeline stage may call must run from a single `/name [args]` line, declare its inputs in argument-hint (`--run <id>` when part of a larger run), and when called by another agent run only itself and change state only through its own writes and gates. The SKILL.md is the contract — no I/O schema","2.14: Platform-truth refresh (Trinity dev 88a4e2f7) — corrected the flat falsehood that Trinity never reads template.yaml schedules: at creation; since ent#89 it DOES, but entries land disabled unless they declare a literal YAML true, cap at 20, dedup by name, and are never re-applied on recreate, and firing additionally needs the agent's autonomy gate (OFF on every new agent). Reporting Rule updated to the shipped report lifecycle: payload is an object capped at 5 MiB (not 256 KB), display_hint gains `json` and is no longer cosmetic (the customer-facing Workspace renders through it), and list_reports/get_report are taught as read-before-write so a scheduled series resumes instead of duplicating","2.13: Trinity-first docs refresh (verified vs Claude Code 2.1.220) — ship the five tier templates as bundled supporting files (Step 6 pointed at a nonexistent templates/ dir; now ${CLAUDE_SKILL_DIR}/templates/); reframe the frontmatter reference as engine fields vs Trinity platform fields (add disallowed-tools, background:, ${CLAUDE_PROJECT_DIR}, allowed-tools grant semantics + accepted formats, name≡directory note; requires:/automation:/schedule: documented as platform contract, not caveat); replace the Routines advisory with the Trinity scheduling path (schedule: → template.yaml → create_agent_schedule; message invokes by slash name; timeout ≤ agent cap); add the Scheduled-Invocation Rule (scheduled playbooks keep disable-model-invocation: false, schedule messages use the slash name) and the Foreground-Fork Rule (headless-bound context: fork must set background: false — forks run in background by default since 2.1.218 and are reaped at turn-end) with matching validation-checklist lines; official supporting-file names in Step 4b; description/name coaching in Step 2","2.12: Add the Library-Grade Rule to Design Constraints + Step 5b library-target question — a skill destined for a shared skills library declares a requires: frontmatter contract (env keys, packages, binaries), references credentials only as named env vars (never .env reads, no interactive auth, materialize-from-env when a tool demands a credential file), fails with named missing-key errors, and passes a deterministic env-coherence + secret-scan check before contribution","2.11: New Step 9 registers the created skill in the agent's CLAUDE.md — Core Capabilities row + request-phrased Request Dispatch row when the table exists, and resolves the playbook-gap operator-queue item (playbook-gap-<slug>) the skill was created to close","2.10: Correct the stall-watchdog facts in the Long-Running-Task Rule — since trinity#1369 the no-output watchdog is 1800s (not 300s) and watches mcp__* tools only (Bash is unwatched, piping doesn't 're-arm' anything); add set_reminder as the Trinity-side way to verify a decoupled job's artifact without waiting for the next cron","2.9: Add the Reporting Rule to Design Constraints + a validation-checklist line — a skill that yields a surfaceable result (summary, batch, metrics) ends with a guarded mcp__trinity__report step (namespaced report_type, a display_hint, JSON payload) so scheduled/headless runs leave a visible record on the Trinity Reports tab; guarded to skip silently off-Trinity (reporting is an upgrade, never a gate)","2.8: Add the Long-Running-Task Rule to Design Constraints + a validation-checklist line — a headless/scheduled run is one agent turn and CANNOT host a >~10-min job (the harness auto-backgrounds it past the ~10-min sync Bash ceiling, active waiting is blocked, and ending the turn reaps every background task/monitor). Such work must be decoupled to an OS-level cron/systemd/sidecar + done-marker; the run only triggers and verifies the artifact moved. In-turn oversight is an interactive-only affordance, not a headless one","2.7: Generated skills now include the what's-new banner + a seed changelog; documented the required changelog + banner convention for every tier","2.6: Add the Composition Rule — playbooks invoke child skills by name (compose, don't copy); reuse-check step, Composes section, transitive autonomous check","2.5: Add when_to_use/arguments/shell/effort/substitution-vars to frontmatter; fix hot-reload advice; add supporting-files step; add Routines note","2.4: Add Single-Task Rule — scheduled skills must be scoped to one task type per invocation","2.3: Note project-specific vs official frontmatter; list newer official fields (model, context, paths, hooks) for Tier 3","2.2: Add No-Gates Rule — autonomous playbooks cannot have approval gates (breaks execution)","2.1: Add 45-minute rule to Design Constraints — autonomous playbooks must complete within this limit"]}

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. Tier templates are bundled with this skill in templates/ — reference them at runtime via ${CLAUDE_SKILL_DIR}/templates/.

---

Workflow

Step 1: Check for Existing Skills

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?