# Author an Agent Skill

> For coding agents: fetch this file, interview the human, then write one portable skill under `.agents/skills/` (or the personal skills dir if they choose). Follow [Agent Skills](https://agentskills.io/specification). Do not invent the workflow; do not default to vendor-only paths like `.claude/skills/`.

You are authoring a reusable Agent Skill. The goal is a skill that any compliant agent (Cursor, Codex, OpenCode, Claude with a bridge, …) can discover from metadata and load on demand—without stuffing the procedure into `AGENTS.md` or locking the human to one vendor’s skill creator.

This is **not** Claude’s `/skill-creator` plugin (eval / benchmark / Claude-only packaging). Same idea—guided creation—different contract: open directory layout, portable frontmatter, repo-friendly defaults. The portable stand-in for “eval” is agreeing **positive and negative example prompts** before you write files.

## When to use

- Human asks to "create a skill," "add an Agent Skill," "write SKILL.md," or "turn this checklist into a skill"
- A procedure would bloat `AGENTS.md` or is only needed for some tasks
- An existing skill is wrong (vague description, vendor-only fields, too long, bad triggers) and needs a rewrite

## When not to use

- The repo still has no product decisions—use [Bootstrap agent context](https://qwertylab.dev/tools/agent-context.md) first
- The ask is a one-off task; no recurring workflow
- The human wants "skills for everything" with no boundary—push back and pick one workflow
- They only want a vendor slash-command with no portable skill (say so, then still prefer `.agents/skills/` if they need multi-tool use)

**Rule of thumb:** needed on nearly every turn → short section in `AGENTS.md`. Needed only for this workflow → skill.

## Standard (source of truth)

| Concern | Standard | Location |
| --- | --- | --- |
| Skill format | [Agent Skills specification](https://agentskills.io/specification) | `.agents/skills/<name>/SKILL.md` |
| Project instructions | [AGENTS.md](https://agents.md/) | Repo root (point at skills; do not duplicate the procedure) |

Canonical project path: **`.agents/skills/<name>/`**. If a tool only reads `.claude/skills/` or similar, symlink or copy from the open layout after the portable skill exists—do not author only in the vendor tree.

Optional check (if available in the environment):

```bash
skills-ref validate .agents/skills/<name>
```

## Create vs rewrite

Before interviewing the procedure, establish mode:

| Mode | When | Rules |
| --- | --- | --- |
| **Create** | No skill yet (or human wants a new name) | New directory; do not overwrite an existing folder without asking |
| **Rewrite** | Improve or replace an existing skill | Read the current `SKILL.md` first. Ask: surgical edit (keep constraints the human still wants) or full replace? Never silently drop safety rules, non-goals, or scripts the human still relies on |

List existing `.agents/skills/*/SKILL.md` (and note vendor skill dirs if present) at the start. Check:

- **Name collision** — same `name` / folder already exists → ask before overwrite or pick another name
- **Trigger overlap** — another skill’s `description` would also match the same asks → narrow keywords, merge into one skill, or drop the new one. Confirm with the human

## Interview first

Ask in small batches (3–5). Prefer concrete choices. Do not invent triggers or steps from the repo tree without confirmation.

### Scope and language

1. Create or rewrite? If rewrite: edit or replace?
2. What recurring job should this skill do, in one or two sentences?
3. Project skill (`.agents/skills/` in the repo) or personal/global (user-level skills dir)? Default to project only if every contributor’s agent should follow it.
4. **Language of the skill body** (and usually the `description`): same as this chat / the project’s working language? Confirm explicitly when EN and ES are both in play.

### Trigger design (do this before any file write)

5. When should an agent load it? (situations + keywords)
6. When should it **not** load?
7. Agree **2–3 positive example prompts** (should load) and **2–3 negative example prompts** (must not load). Keep these in the interview notes; fold the distinction into `description` (“Use when… Not for…”).

### Procedure

8. Required steps, in order? What is optional?
9. Inputs / outputs (paths, commands, review gates)?
10. Split **local development** vs **production/server** commands if the workflow spans both (e.g. PowerShell/npm on a laptop vs bash/systemd on Linux).
11. Hard constraints (never force-push, never touch secrets, ask before commit, …)?

### Packaging

12. Detail in `references/` (long docs, examples) or `scripts/` (commands the agent should run)?
13. If `scripts/`: which OS/shell are they for? Prefer portable commands in the body when both local and server matter; put server-only bash under `scripts/` and say so in `SKILL.md`.
14. License? (`license`—optional)
15. Real environment needs? (`compatibility`—omit if none)

Propose draft `name` + `description` + the +/− prompt list; wait for a yes before writing.

## Write order (mandatory)

1. Confirm `name` (and no unwanted collision)
2. Lock **`description`** against the +/− prompts (gate for loading)
3. Write the **body** (and optional `references/` / `scripts/`)
4. Point from `AGENTS.md` if appropriate

Do not draft a long body first and bolt on a vague description afterward.

## Write the skill

### Directory

```text
.agents/skills/<skill-name>/
├── SKILL.md          # required
├── scripts/          # optional — executable helpers
├── references/       # optional — load on demand
└── assets/           # optional — templates, static files
```

`<skill-name>` must match frontmatter `name`: lowercase letters, digits, single hyphens; no leading/trailing hyphen; no `--`; max 64 characters.

Personal/global skills use the same layout under that tool’s user skills directory (often `~/.agents/skills/`). Do not commit personal skills into the repo.

### Frontmatter (portable)

Required:

```yaml
---
name: skill-name
description: What it does and when to use it. Include trigger keywords the agent can match.
---
```

Optional (open spec): `license`, `compatibility`, `metadata` (string keys → string values).

**`description` budget:** max **1024 characters** (spec). Keep it short and surgical—metadata for every skill competes for context on agents that list skills at startup. Put procedure detail in the body, not in `description`.

**Default: omit `allowed-tools`.** Experimental and agent-specific. Omit Cursor-/Claude-only fields (`paths`, `user-invocable`, `argument-hint`, Codex UI yaml, …) unless the human wants a vendor fork *in addition to* the portable skill.

### Description quality

`description` is how agents decide to load the skill. Cover **what**, **when**, and a crisp **not for**.

Good:

```yaml
description: >
  Run the Linux production deploy via Docker Compose and systemd. Use when the
  human asks to deploy, restart qwertylab services, or ship frontend/backend to
  the server. Not for local npm/astro preview.
```

Bad:

```yaml
description: Helps with deploys.
```

### Minimal `SKILL.md` skeleton

Start from this and fill with confirmed answers (language as agreed):

```markdown
---
name: example-skill
description: >
  Does X for Y. Use when the human asks A, B, or C. Not for D or E.
---

# Example skill

One-line purpose.

## Steps

1. …
2. …

## Constraints

- …
- Non-goals: …

## References

- Details: [references/…](references/…) — load when …
- Script (Linux/server): `scripts/…` — run when …
```

### Body

1. **One-line purpose**
2. **Steps** — numbered, falsifiable
3. **Constraints / non-goals**
4. **Pointers** — relative links to `references/` or `scripts/` (**one level deep** from `SKILL.md`; no nested reference chains)

**Size:** keep `SKILL.md` under ~500 lines. Move long material to `references/` and say when to open it. Progressive disclosure: metadata always → body on activate → references/scripts only as needed.

### `scripts/` and environments

- One-liners needed on both laptop and server → put in the body with an explicit **Local** vs **Production/server** split when they differ
- Non-trivial automation for one OS → `scripts/` plus a note (“bash on Linux host”, “not for Windows shell”)
- Do not assume bash on the human’s Windows/macOS machine because production is Linux

### After writing

- If `AGENTS.md` exists, add a one-line pointer—do not paste the procedure there
- Vendor bridge (`.claude/skills/`, etc.) only if the human asks; symlink or derive from `.agents/skills/`

## Anti-patterns

- Skills with no trigger language (or no “not for”) in `description`
- `description` over 1024 characters, or a procedure essay crammed into frontmatter
- Writing the body before locking description + +/− prompts
- Overlapping triggers with an existing skill without resolving the conflict
- Overwriting a skill folder without asking
- Encoding taste ("be elegant") instead of observable steps
- Dumping personal workflows into `.agents/skills/`
- Authoring only under `.claude/skills/` or `.cursor/` and calling it the standard
- Giant `SKILL.md` that should be `references/`; nested reference chains
- Inventing steps the human never confirmed
- Secrets or real `.env` values inside the skill
- "Generate 12 skills" from a vague prompt

## Verification

1. Show mode (create/rewrite), name, description, language, scope, +/− example prompts, and outline → get a yes
2. Write files; `name` matches folder; no accidental overwrite
3. Re-read `description`: under 1024 chars; answers “when do I load this?” and “when must I not?”
4. Check each positive prompt would match and each negative would not (adjust wording if not)
5. Optional: `skills-ref validate` on the skill directory

## Minimal command sequence

```text
1. List existing skills; decide create vs rewrite; check name/trigger collisions
2. Interview (language, +/− prompts, steps, local vs server, packaging)
3. Confirm name + description + prompt list with human
4. Write description first, then body (+ references/scripts if needed)
5. Point from AGENTS.md if appropriate
6. Verify +/− prompts against description; optional skills-ref validate
```

## References

- Agent Skills specification: https://agentskills.io/specification
- AGENTS.md: https://agents.md/
- Companion tool (repo bootstrap): https://qwertylab.dev/tools/agent-context.md