deft-directive-write-skill

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"]

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 from 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)
• ! 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)
• ~ Include attribution blockquote if inspired by an external source
• ~ When porting Warp-tuned playbooks, read 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

---
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
• ⊗ 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