# Skill Builder

> Use when the user wants to create, scaffold, or review a new Agent Skill (a SKILL.md-based reusable capability for Claude, Cursor, Codex, or any agentskills.io-compliant agent). Not for general questions about what skills are, and not for writing regular prompts or one-off instructions.

- Skill: `kanthalas/skill-builder` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kanthalas/skill-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kanthalas/skill-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: KanthalaS (https://skillmd.com/u/kanthalas)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/kanthalas/skill-builder

---


# Skill Builder

You are helping the user turn a workflow, procedure, or domain of knowledge into a properly scaffolded Agent Skill. Follow this sequence every time — do not skip the description-quality check, it is the single highest-leverage step.

## Step 1: Get the raw material

Ask the user to describe, in plain language:
- What task or workflow should trigger this skill
- What a *good* outcome looks like when the skill is used correctly
- Any tasks that sound similar but should NOT trigger this skill (this is often the most useful question — it sharpens the boundary)

If the user has an existing document, playbook, or set of examples, ask for it directly rather than reconstructing it from memory.

## Step 2: Write the description as a trigger contract, not a summary

Draft the `description` field as one or two sentences that state:
1. The specific task that should trigger this skill
2. What similar-but-different task should NOT trigger it

Bad pattern: "Helps with [topic]." — too vague, will either never fire or fire on the wrong tasks.
Good pattern: "Use when [specific task with concrete trigger words]. Not for [nearby task it should be excluded from]."

Run the draft description past the user before moving on. This field determines whether the finished skill actually works — it is worth iterating on before writing a single line of the body.

## Step 3: Draft the body — core steps only

Write the numbered, unconditional steps that apply to *every* invocation of this skill. Keep this section under roughly 5,000 tokens (~3,750 words). If the core steps alone are approaching that limit, stop and tell the user this is probably two or three skills wearing one trigger contract — help them split it instead of cramming it into one file.

Do not re-explain general knowledge the model already has. Only include the specific, non-obvious parts of the process that are actually this user's process, not a generic version of the task.

## Step 4: Decide what belongs outside the body

For each piece of content in the draft, ask:
- Is this exact, repeatable, deterministic logic (math, formatting, a fixed lookup)? → Move it into `scripts/` and have the body call it, rather than describing it in prose.
- Is this detail only relevant to a minority of cases (a specific region, department, or edge case)? → Move it into `references/[descriptive-name].md`, and add a one-line pointer to it in the body ("see references/x.md for [specific case]"). Do not inline it.
- Is this a template, example output, or boilerplate file the skill should produce? → Move it into `assets/`.

## Step 5: Assemble the folder

Create this structure:

```
skill-name/
├── SKILL.md
├── scripts/       (only if Step 4 identified deterministic logic)
├── references/    (only if Step 4 identified edge-case detail)
└── assets/        (only if Step 4 identified templates/boilerplate)
```

Use a lowercase, hyphenated folder name matching the skill's `name` field.

## Step 6: Validate before handing it back

Run `scripts/validate_skill.py` (bundled with this skill) against the finished SKILL.md and report back:
- Whether both required frontmatter fields are present
- An estimated token count for the body, flagged if over the ~5,000 token guideline
- Whether the description contains an explicit "not for" boundary
- A flag on any of the top 10 vague-description filler words ("helps with", "assists", "supports", "various", "general", "things", etc.)

Present the results to the user plainly, then ask if they want to fix anything before finishing.

## Step 7: Tell the user how to install and share it

Remind the user of their options, matched to what they said in Step 1 about their setup:
- Local personal use: drop the folder into `~/.claude/skills/` (or the equivalent path for their agent)
- Project-specific: drop it into `.claude/skills/` inside the repo
- Sharing with a team: push it to a GitHub repo with a `marketplace.json`, installable via `/plugin marketplace add`
- Public sharing: point them to submitting through a curated directory such as skillstore.io if they want automated review before publishing

Do not install or publish anything without the user explicitly asking you to.