# 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

```
/skill-write
```

## Files

| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `scripts/new-skill.sh` | Copies annotated templates to the destination |
| `references/scripts.md` | Package runner table and inline dependency patterns (loaded on demand) |
| `references/deployment-modes.md` | Plugin vs standalone differences and cache isolation rules (loaded on demand) |
| `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 |
| `assets/templates/tests/README.md` | Placeholder for test files |
| `tests/new-skill.bats` | Bats test suite for new-skill.sh |
| `tests/README.md` | Setup instructions for bats-support and bats-assert test dependencies |

## 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)