make-skill

Package any workflow into a Claude Code skill. The output is a SKILL.md ready to publish with /publish-skill.

Phase 1: Capture the Workflow

Ask for anything missing:

1. What does it do? — One sentence. What problem does it solve?
2. When should it trigger? — Exact phrases or contexts. Be specific.
3. What does it need from the user? — Inputs before it can run.
4. What does it output? — File changes, code, chat output, commands?
5. What are the steps? — Walk through the process start to finish.
6. What are the hard rules? — Things it must always or never do.

If the current conversation already describes a workflow, extract answers from it before asking. Don't ask for what you already have.

Phase 2: Write the Frontmatter

---
name: skill-name           # lowercase, hyphenated, no spaces
description: [What it does]. Use when [contexts]. Triggers on requests like "[exact phrase]", "[exact phrase]", "[exact phrase]", or any request for [broader category].
category: [devops|ai|analytics|auth|payments|seo|marketing|planning|meta|workflow]
tags: [tag1, tag2, tag3]   # 3-5 lowercase keywords
author: tushaarmehtaa
---

The description is the trigger. Claude uses it to decide when to activate the skill. Make it explicit:

• Include WHAT the skill does AND WHEN to use it
• List specific trigger phrases in quotes — exact words a user would type
• End with a broader catch-all pattern
• Over-specify rather than under-specify — Claude tends to undertrigger

Phase 3: Write the Body

The structure that matches the quality bar of the existing skills:

[One-liner opener — what this does, what it outputs. No heading above this.]

## Phase 1: [First Phase Title]

[Instructions. Dense. Opinionated. No hedging.]

## Phase 2: [Next Phase Title]

...

## Verify

[ ] [Thing that must be true] [ ] [Thing that must be true] [ ] [Edge case handled]

Rules that don't move:

• Open with a single sentence — no # Heading before it. This is the first thing Claude reads.
• Use ## Phase N: Title for every major section
• Use ### 1.1 sub-phases only when Phase 1 needs branching (stack detection, mode selection)
• Code blocks must contain real, runnable code — not pseudocode
• Bold warnings inline for things that fail silently or break the whole flow
• End with ## Verify using bare [ ] items inside a code block (not markdown - [ ] list items)
• Under 500 lines total — push long examples to references/guide.md

Phase 4: The Verify Section

The verify section is not optional. It's how the user confirms the skill ran correctly.

Format exactly like this — bare brackets in a fenced code block:

## Verify

```
[ ] [Thing that must be true after the skill runs]
[ ] [Output format is correct]
[ ] [Edge case handled]
[ ] [Common mistake avoided]
```

Each item must be checkable — either it's done or it isn't. No vague items like "quality looks good."

Phase 5: References (if needed)

Create references/guide.md when:

• Full examples would push SKILL.md over 500 lines
• Multiple variants need their own section
• Edge cases are complex enough to need real examples

The reference file must have real input → output examples. Not outlines of examples.

Phase 6: Test Prompts

Write 3–5 prompts that should trigger the skill, and 2 that should NOT:

"make a skill for PR reviews"          ✅ should trigger
"create a skill to audit my code"      ✅ should trigger
"turn this process into a skill"       ✅ should trigger
"review my PR"                         ❌ should not trigger (different skill)
"what skills are available?"           ❌ should not trigger

Use these to validate the description before publishing. If any trigger should fire but doesn't, add the phrase to the description.

Phase 7: Publish

Use /publish-skill to copy the skill into the repo, update the README, build the site, and push.

Verify

[ ] YAML frontmatter has all 5 fields (name, description, category, tags, author)
[ ] Description includes specific trigger phrases in quotes
[ ] Body opens with a one-liner — no heading before it
[ ] All sections use ## Phase N: Title format
[ ] Code blocks contain real code, not pseudocode
[ ] Critical constraints are bolded inline
[ ] Verify section uses bare [ ] items in a fenced code block
[ ] SKILL.md is under 500 lines
[ ] Long examples moved to references/guide.md if needed
[ ] 3-5 test prompts written to validate triggers

See references/guide.md for full annotated SKILL.md examples, common structural mistakes, and the complete list of valid categories.