---
name: write-skill
description: Write agent skills with proper structure, progressive disclosure, and bundled resources. Use when editing an existing skill or creating a new skill.
---

# Writing Agent Skills

## Writing a new skill workflow

1.  Gather requirements - ask user about:
    -   What task/domain does the skill cover?
    -   What specific use cases should it handle?
    -   Does it need executable scripts or just instructions?
    -   Any reference materials to include?

2.  Draft the skill - create:
    -   SKILL.md with concise instructions
    -   Additional reference files if content exceeds 500 lines
    -   Utility scripts if deterministic operations needed

3.  Review with user - present draft and ask:
    -   Does this cover your use cases?
    -   Anything missing or unclear?
    -   Should any section be more/less detailed?

## Skill Structure

```text
skill-name/
├── SKILL.md        # Main instructions (required)
├── REFERENCE.md    # Detailed docs (if needed)
├── EXAMPLES.md     # Usage examples (if needed)
└── scripts/        # Utility scripts (if needed)
    └── helper.js
```

## Skill Suites

A **Skill Suite** is a collection of related sub-skills bundled into a single skill folder. Use a skill suite when you want to group complex operations or a large system workflow under a single name (e.g., the `iris` skill).

### Structure

```text
skill-suite-name/
├── SKILL.md        # Index / Table of sub-skills (required)
├── sub-skill-1.md  # Sub-skill instructions
├── sub-skill-2.md  # Sub-skill instructions
└── scripts/        # Shared utility scripts (if needed)
```

### SKILL.md Index Format

In a skill suite, the main `SKILL.md` acts as an index of sub-skills. It should contain a table listing each sub-skill with a relative link to its instruction file and a brief description:

| Skill Name | File Path | Description |
| :--- | :--- | :--- |
| **suite-sub-1** | [sub-skill-1.md](./sub-skill-1.md) | Description of what this sub-skill does. |
| **suite-sub-2** | [sub-skill-2.md](./sub-skill-2.md) | Description of what this sub-skill does. |

## SKILL.md Template

```md
---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
argument-hint: <required-arg> [optional-arg]  # (optional)
---

# Skill Name

## Quick start

[Minimal working example]

## Workflows

[Step-by-step processes with checklists for complex tasks]

## Advanced features

[Link to separate files: See [REFERENCE.md](REFERENCE.md)]
```

## Argument Hint Requirements (Optional)

The `argument-hint` parameter in the frontmatter is optional. It indicates what arguments the skill accepts when invoked. It helps the agent understand what parameters to pass.

-   Use angle brackets `<...>` for **required** arguments.
-   Use square brackets `[...]` for **optional** arguments.

**Example**:

```yaml
argument-hint: <document> [target-language]
```

## Description Requirements

The description is **the only thing your agent sees** when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill based on the user's request.

**Goal**: Give your agent just enough info to know:

1.  What capability this skill provides
2.  When/why to trigger it (specific keywords, contexts, file types)

**Format**:

-   Max 1024 chars
-   Write in third person
-   First sentence: what it does
-   Second sentence: "Use When [specific triggers]"

**Good example**:

```text
Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
```

**Bad example**:

```text
Helps with documents.
```

The bad example gives your agent no way to distinguish this from other document skills.

## When to Add Scripts

Add utility scripts when:

-   Operation is deterministic (validation, formatting)
-   Same code would be generated repeatedly
-   Errors need explicit handling

Scripts save tokens and improve reliability vs generated code.

## When to Split Files

Split into separate files when:

-   SKILL.md exceeds 500 lines
-   Content has distinct domains (finance vs sales schemas)
-   Advanced features are rarely needed

## Review Checklist

After drafting, verify:

-   [ ] Description includes triggers ("Use when...")
-   [ ] SKILL.md under 500 lines
-   [ ] No time-sensitive info
-   [ ] Consistent terminology
-   [ ] Concrete examples included
-   [ ] References one level deep
