Skill Creator

---
name: skill-creator
description: Guide for creating and validating agent skills. Use when authoring or updating a SKILL.md, writing frontmatter, structuring scripts/references/assets, or checking a skill before deployment. Triggers on create skill, write skill, skill frontmatter, validate skill, fix skill YAML. For installing a finished skill, use skill-deployer instead.
---

# Skill Creator

Guidance for building lean, effective agent skills and validating them before deployment.

> **Deployment** (scope, target paths, verification in `<available_skills>`) is handled by **skill-deployer**. Finish creation and validation here first.

## Quick Process

1. **Understand** — gather concrete usage examples (see [creation-process.md](references/creation-process.md) Step 1)
2. **Plan** — identify scripts, references, and assets to bundle
3. **Implement** — write SKILL.md and bundled resources
4. **Validate** — `python3 scripts/skill.py validate <skill-folder>` (see [validation.md](references/validation.md))
5. **Deploy** — `python3 scripts/skill.py deploy <skill-folder>` for a global user skill; **skill-deployer** handles GitHub URLs, workspace/assistant scope, update and remove
6. **Iterate** — refine after real usage, re-validate after edits

## Write flow: `skill.py`

User skills are **read-only to the agent**. Write them only with `skill.py deploy`; never `cp`, `tee`, `sed -i`, or file-tool writes into the user skills folder.

```bash
python3 <skill_base>/scripts/skill.py new <name> [--to <dir>]     # template in the workspace
python3 <skill_base>/scripts/skill.py clone <name> [--to <dir>]   # copy a user/system skill into the workspace
python3 <skill_base>/scripts/skill.py validate <dir>              # strict checks, stdlib only
python3 <skill_base>/scripts/skill.py deploy <dir>                # validate, then copy to <user skills>/<name>/
```

In a Docker session the user skills mount is read-only: `deploy` stages the skill in `.libragent/skill-outbox/<name>/` and the host installs it when the command finishes. Read `.libragent/skill-outbox/<name>.status` afterwards (`installed` or `rejected: <reason>`).

Edit the workspace copy between `new`/`clone` and `validate`. `deploy` refuses invalid skills, overwrites an existing skill of the same name, and restores it if the deployed copy fails validation.

## Validation (required before deploy)

```bash
python scripts/validate_skill.py <path/to/skill-folder>
python scripts/validate_skill.py <path/to/skill-folder> --strict   # before deployment
```

Checks frontmatter (same rules as the Rust scanner) and warns about common path mistakes. Full checklist: [validation.md](references/validation.md).

## Core Rules

- **Concise body**: SKILL.md under ~150 lines; move detail to `references/`
- **Triggers in frontmatter**: all "when to use" guidance goes in `description`, not the body
- **Cross-platform by default**: never assume Linux/Bash; provide dual recipes (Bash + PowerShell) or OS-neutral commands/scripts
- **Name matches folder**: `name:` in frontmatter must equal the directory name
- **Safe YAML**: use double quotes in `description` when text contains apostrophes (`"Telegram's"`, not `'Telegram\'s'`)
- **No duplicate reads**: information lives in SKILL.md *or* references, not both
- **Imperative voice** in body instructions
- **No auxiliary docs**: no README, CHANGELOG, or INSTALLATION_GUIDE in the skill folder

## Structure

See [anatomy.md](references/anatomy.md) for directory layout (`SKILL.md`, `scripts/`, `references/`, `assets/`).

## Design Guidance

- [design-principles.md](references/design-principles.md) — concision, degrees of freedom, progressive disclosure
- [creation-process.md](references/creation-process.md) — full walkthrough
- [validation.md](references/validation.md) — validate_skill.py usage and rules
- [workflows.md](references/workflows.md) — sequential and conditional workflow patterns
- [output-patterns.md](references/output-patterns.md) — template and example patterns

## Frontmatter Checklist

```yaml
---
name: skill-name
description: "What it does + specific triggers/contexts for when to use it."
---
```

Only `name` and `description` are required. The description is the primary trigger mechanism.