---
name: deft-directive-write-skill
description: >-
  Create new deft skills with proper structure, RFC2119 notation, triggers,
  and progressive disclosure. Use when user wants to create, write, or build a
  new deft skill.
triggers:
  - write a skill
  - create a skill
  - new skill
  - build a skill
---
<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
<!-- Purpose: rendered skill -->
<!-- Source of truth: packs/skills/skills-pack-0.1.json -->
<!-- Regenerate with: task packs:render -->
<!-- Edit the source, not this file. Slice instead of loading every SKILL.md: task packs:slice skills by-trigger --trigger <kw> (or list) -->

# Deft Write Skill

Create new deft skills that follow directive's conventions: RFC2119 notation, YAML frontmatter with triggers, clear When-to-Use sections, and proper naming.

Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.

> Inspired by [write-a-skill](https://github.com/mattpocock/skills/tree/main/write-a-skill) from [mattpocock/skills](https://github.com/mattpocock/skills). Adapted to deft's SKILL.md conventions, RFC2119 notation, and naming patterns.

## When to Use

- User wants to create a new skill for a workflow directive doesn't cover yet
- Formalizing an ad-hoc process that keeps repeating into a reusable skill
- Extending directive with project-specific or domain-specific skills

---

## Deft Skill Naming Conventions

| Skill type | Naming pattern | Example |
|---|---|---|
| Framework / meta | `deft-{verb}` | `deft-build`, `deft-setup` |
| GitHub-integrated | `deft-directive-gh-{verb}` | `deft-directive-gh-slice` (triage verb reclaims to `deft-directive-refinement`) |
| Domain / project-specific | `{project}-{verb}` | `my-app-deploy` |

---

## Process

### Step 1: Gather requirements

Ask the user (one question at a time):

1. What task or domain does this skill cover?
2. What specific use cases should it handle?
3. Does it require external tools (e.g., `gh`, `docker`, database CLIs)?
4. Should it produce files, run commands, or guide a conversation?
5. Any reference material or existing workflows to model from?

### Step 2: Draft the skill

- ! Follow the deft SKILL.md template below
- ! Keep SKILL.md under 150 lines — split long templates into `references/*.md` (see [`references/composer-skill-porting.md`](../../references/composer-skill-porting.md))
- ! Write the `description` field as if it's the only thing the agent will see when deciding whether to invoke this skill
- ! Include negative triggers in `description` (`Do NOT trigger on …`) so near-miss phrases do not load the wrong skill
- ~ Use the trigger words the user would naturally say
- ! Use RFC2119 notation throughout (!=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY)
- ! Apply **goal-gate determinism** (#852): rigid goal, acceptance criteria, quality gates, exit/handoff, and scope `⊗` boundaries; demote pure execution steps to `~` unless they are gates — see [`patterns/goal-gate-determinism.md`](../../patterns/goal-gate-determinism.md)
- ~ Include attribution blockquote if inspired by an external source
- ~ When porting Warp-tuned playbooks, read [`references/composer-skill-porting.md`](../../references/composer-skill-porting.md) for fast-path vs isolation, short-chat expectations, and Composer naming

### Step 3: Review with user

Present the draft and ask:
- Does this cover your use cases?
- Anything missing or unclear?
- Should any section be more or less detailed?

Iterate until approved.

### Step 4: Create the skill

- ! Create the directory `skills/{skill-name}/`
- ! Write `skills/{skill-name}/SKILL.md`
- ~ Create `skills/{skill-name}/REFERENCE.md` or `references/{topic}.md` if content exceeds 150 lines
- ~ Create `skills/{skill-name}/scripts/` for deterministic helper scripts
- ! When the skill creates GitHub issues or PRs, instruct authors to use `--body-file` with OS-temp paths — never inline multi-line `--body` strings (see `scm/github.md`)

---

## Deft SKILL.md Template

```markdown
---
name: {skill-name}
description: >
  {What it does in 1–2 sentences}. Use when {specific triggers —
  what the user would say or what context activates this skill}.
  Do NOT trigger on {near-miss phrase 1} or {near-miss phrase 2}.
triggers:
  - {trigger phrase 1}
  - {trigger phrase 2}
[metadata:
  clawdbot:
    requires:
      bins: ["gh"]   # only if external CLI is needed]
---

# {Skill Title}

{One-line description of what this skill does.}

Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.

[> Inspired by ... — optional attribution]

## When to Use

- {Use case 1}
- {Use case 2}

[## Prerequisites

- ! Verify {tool} is available — stop and report if not]

---

## Process

### Step 1: {Name}

- ! {mandatory action}
- ~ {recommended action}
- ⊗ {forbidden action}

### Step 2: {Name}

...

---

## Anti-Patterns

- ⊗ {what NOT to do}
- ⊗ {what NOT to do}
```

---

## Description Writing Rules

The description is **the only thing the agent sees** when deciding whether to load this skill. Write it to answer:
1. What capability does this provide?
2. When should it trigger? (use "Use when..." pattern)
3. What near-miss phrases must NOT trigger it? (use "Do NOT trigger on..." pattern)

- ! Max 1024 characters
- ! Include "Use when [specific triggers]" in the description
- ! Include "Do NOT trigger on [near-miss phrases]" when triggers could overlap another skill
- ⊗ Vague descriptions ("helps with things") — the agent can't distinguish between skills
- ! First sentence: what it does. Second sentence: when to use it. Third (when needed): what not to trigger on.

---

## Anti-Patterns

- ⊗ Omitting RFC2119 notation — deft skills use it consistently
- ⊗ Putting all content in SKILL.md when it exceeds 150 lines — split into `references/*.md` or `REFERENCE.md`
- ⊗ Prescribing a rigid tool-call path as MUST when only the goal/gates need determinism — use goal-gate-determinism (#852)

- ⊗ Putting every agent-host branch (Warp, Cursor, OpenClaw, Grok Build, generic) in one always-loaded SKILL body when a host-neutral core + per-host adapter split is feasible (#2928)

---

## Host-adapter skills (multi-host) (#2928)

Large skills that branch on **agent host** (the runtime: Warp, Cursor, OpenClaw, Grok Build, generic-terminal) SHOULD use progressive host adapters:

1. ! Keep a **thin host-neutral core** in `SKILL.md` (triggers, phase overview, detect, route table, cross-host MUST gates).
2. ! Put shared depth in `references/core-*.md`.
3. ! Put each host path in `references/host-<id>.md` (spawn primitive, cwd rules, monitor liveness, host MUST NOT list).
4. ! Default load path: detect host → read core + **one** adapter. 
5. ⊗ Load all host adapters “just in case.”

Exemplar: `skills/deft-directive-swarm/` (route table in SKILL + `references/host-openclaw.md` etc.).

- ⊗ Vague trigger phrases — use phrases the user would actually type
- ⊗ Overlapping triggers without negative triggers — add `Do NOT trigger on …` to the description
- ⊗ Naming a GitHub-integrated skill without `gh` in the name
- ⊗ Writing the description without a "Use when..." clause
- ⊗ Inline multi-line `gh --body` strings in skill steps — use `--body-file` per `scm/github.md`