---
title: create-skill
description: Author a new agent skill (SKILL.md) from a plain-English ask.
---

`create-skill` turns a plain-English description into a real, agent-facing
`SKILL.md` (plus any supporting files). It is the skill-authoring counterpart to
[`create-workflow`](/workflows/create-workflow): instead of hand-writing skill
docs, you describe what the skill should equip an agent to do and the workflow
clarifies it, designs the structure, scaffolds the files, and documents the result.

```bash
bunx smithers-orchestrator workflow run create-skill \
  --prompt "A skill that teaches an agent to triage flaky tests"
```

By default it pauses for you to approve the design before any files are written.
Clear the gate with `bunx smithers-orchestrator approve RUN_ID --node approve-design`, or run
autonomously with `--input '{"review":false}'`.

## Stages

1. **clarify**: turn the freeform ask into a structured skill spec (purpose, when-to-use, capabilities, inputs).
2. **design**: produce the concrete `SKILL.md` blueprint (frontmatter, body sections, supporting files).
3. **approve-design**: durable human approval gate (skippable via `review: false`).
4. **scaffold**: write `SKILL.md` (and any supporting files) under `.smithers/skills/`.
5. **document**: summarize what was created and where.

## Inputs

| Input | Type | Default |
| --- | --- | --- |
| `prompt` | string | `"Describe the agent skill you want to create, in plain English."` |
| `name` | string or null | `null` (the clarify/design steps choose a kebab-case id) |
| `review` | boolean | `true` (pause for design approval before writing files) |

Use this when you want to capture a repeatable agent capability as a reusable
skill without hand-authoring the `SKILL.md` structure yourself.
