# skill-write

Author a new skill conforming to the [agentskills.io](https://agentskills.io) specification.

## What it does

1. Scaffolds a full skill directory from annotated templates
2. Guides filling in `SKILL.md` and supporting files
3. Validates the result against the spec

## Before you start

This skill produces its best output when you arrive with rich context:

- Run `/grill-me` to resolve design decisions (scope, triggers, patterns)
- Collect domain research, examples, and reference docs
- Know the skill name (kebab-case) and destination path

## Usage

Invoke via your agent tool with `/skill-write`, or follow the steps in `SKILL.md` manually.

**Agent invocation:**
```
/skill-write
```

**Manual (human) workflow:**
```bash
# 1. Create the scaffold
bash scripts/new-skill.sh <skill-name> <destination-dir>

# 2. Fill in the templates at <destination-dir>/<skill-name>/

# 3. Validate
bash scripts/validate.sh <destination-dir>/<skill-name>
```

## Files

| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `scripts/new-skill.sh` | Copies annotated templates to the destination |
| `scripts/validate.sh` | Validates a skill directory against the spec |
| `assets/templates/SKILL.md` | Annotated SKILL.md template |
| `assets/templates/README.md` | Annotated README template for the new skill |
| `assets/templates/scripts/README.md` | Placeholder for bundled scripts |
| `assets/templates/references/README.md` | Placeholder for reference docs |
| `assets/templates/assets/README.md` | Placeholder for static assets |

## Placement

Skills can be installed in two locations:

| Type | Path |
|------|------|
| Direct (available immediately) | `~/.agents/skills/<name>/` |
| Plugin (installed via marketplace) | `plugins/<plugin>/skills/<name>/` |

## Spec reference

[agentskills.io specification](https://agentskills.io/specification.md)