skill-builder

Skill Builder

How to write an agent skill that belongs in this library. Follow this standard exactly — every skill in dogfooded-skills was reviewed against it before merge.

What Is a Skill?

A skill is a markdown file at .claude/skills/<skill-name>/SKILL.md. It is loaded into the agent's context when invoked via skill invocation or referenced in the project instructions file. It is not a prompt — it is a runbook: concrete commands, decision tables, and explicit gotchas that turn the agent into a domain expert.

A skill is NOT:

• A README explaining what a tool does
• A collection of examples for the user to read
• A configuration file
• A vague list of things to consider

A skill IS:

• Step-by-step instructions the agent executes, not reads
• Real commands with real flags, not pseudocode
• The authoritative source of truth for one capability

File Structure

skills/
  <skill-name>/
    SKILL.md          ← required: the skill itself
    <support-files>   ← optional: scripts, templates, reference data

Skill names are kebab-case, lowercase. Use the shortest name that's unambiguous: deps-runner, not dependency-update-runner.

`-runner` suffix = operator-side dispatcher. A skill named *-runner runs outside a devbox and drives one: it spawns or targets a worker, prompts, polls, verifies and reports, and never executes its engine inline. Its engine carries no suffix and must work inside any checkout with no gateway access. The suffix is the pylot skills list --kind runner filter contract, so do not use it for anything else.

Frontmatter

Every SKILL.md must start with YAML frontmatter:

---
name: skill-name
description: One-line summary — used by the agent to decide relevance. Be specific.
allowed-tools: Read, Write, Bash, Glob, Grep  # optional — restrict tool use
---

Field rules

`name` — matches the directory name. No spaces, no uppercase.

`description` — one line, plain English. The agent reads this to decide whether to invoke the skill. Bad: "Manage environments." Good: "Claim, start, SSH into, and release Gitpod cloud environments for CI/agent workloads."

`requires_worker_skills` — runners only: the engine skills the worker must have, as a flat inline list (requires_worker_skills: [ce-debug]; block-style YAML lists are not read). Pylot resolves each to its catalog origin and installs it at user scope when the mission worker boots, failing the boot when it cannot. Every listed engine must be in the org's skills catalog with an owner/repo origin.

`allowed-tools` — whitelist of tools this skill may use. Omit to allow all tools. Set when the skill should be restricted (e.g., a read-only audit skill).

Section Structure

A skill must have these sections, in order:

1. One-line purpose (H1)

The title is the skill name. The first paragraph (no heading) is the one-sentence purpose. Example:

# deps-runner

Run dependency update PRs through a verification pipeline — checkout, build, test, classify risk, auto-merge or flag.

2. When to Use (optional but recommended)

Bullet list of triggers. When should the agent invoke this skill vs. doing something else?

## When to Use

- Dependabot or Renovate PRs that need automated verification
- Batch processing multiple dep updates for the same repo
- When you need a risk classification before merging

3. Prerequisites

Everything that must be true before the skill runs. Include verification commands.

## Prerequisites

gitpod version && gitpod whoami # Gitpod CLI authenticated gh auth status # GitHub CLI authenticated

### 4. Core Workflow

The heart of the skill. Numbered steps, real commands, decision points clearly marked.

Rules:
- Use numbered steps for sequential operations
- Use `> **Warning:**` for steps where errors are common
- Wrap multi-line bash in fenced code blocks with `bash` lang
- Show expected output when it matters for verification
- Decision points use tables or `if/else` prose, not vague "depending on..."

Example:

Workflow

1. List environments

   gitpod environment list --timeout 60s

Filter by repository URL. Count running/stopping envs for this repo.

1. Check pool limits — abort if count >= 3 (issue) or >= 2 (deps)

1. Claim a stopped env (prefer reuse over create)

   gitpod environment start {env-id} --set-as-context --dont-wait

Check for active pilot before claiming: ``bash gitpod environment ssh {env-id} -- "pgrep -x claude || echo NO_PILOT" If a claude` process exists, this pod is occupied. Pick another.

### 5. Decision Tables

Use tables whenever there are multiple paths or risk tiers.

Risk Classification

### 6. Error Handling

Explicit failure modes and what to do. Not exhaustive — only the non-obvious ones.

Error Handling

`pgrep -x claude` returns a PID — pod is mid-mission. Do not claim. Pick a different env.

Build fails on `bundle install` — check Ruby version. Lexgo requires Ruby 3.2.x. Run ruby -v inside the env.

`gitpod environment ssh` times out — env may still be starting. Poll with gitpod environment get {env-id} and retry after 15s.

### 7. Critical Rules (optional)

Bullet list of absolute must-follow rules. Use when violations cause data loss, leaked resources, or security issues.

Critical Rules

• Always release envs after use — stopped envs cost nothing; leaked running envs burn credits
• Never skip decontamination — a stopped pod resumes with stale git state
• One agent process per env — two agents share a git working directory and corrupt each other

## Description Rule

The `description:` field is the routing signal — it determines when an operator reaches for this skill. It MUST start with an actionable trigger.

| Good | Bad |
|------|-----|
| "Use when running the deps pipeline for a repo." | "6-stage SEQUENTIAL ICM procedure for deps-runner." |
| "Use to deploy to Fly.io or configure flyctl." | "Deploy applications to Fly.io platform." |
| "Use when triaging Dependabot/Snyk alerts." | "Security alert triage framework." |

**Self-check:** Does your description answer "when should I pick this skill?" If it describes _how_ the skill works instead of _when_ to use it, rewrite it.

Accepted trigger forms: "Use when ...", "Use to ...", "Use as ..." (for import-only skills). Mechanics notes (stage count, parallelism) belong in the skill body, not the description.

## Quality Checklist

Before submitting a skill, verify every item:

- [ ] Frontmatter is complete and valid YAML
- [ ] `description` is specific enough to distinguish from similar skills
- [ ] Every command in the skill was copy-pasted from a real terminal session
- [ ] Error handling covers the three most common failure modes
- [ ] No pseudocode — every step has a real, runnable command
- [ ] Decision points have tables or explicit conditions, not "it depends"
- [ ] No instructions to the *user* — all prose is addressed to the agent
- [ ] The skill has been run at least 5 times against a real workload

## Common Antipatterns

### Too vague

Bad

1. Run the appropriate command to start the environment.

Good

1. Start the environment:

   gitpod environment start {env-id} --set-as-context --dont-wait

### Instructing the user instead of the agent

Bad

The user should verify that the environment is running before proceeding.

Good

Verify the environment is running:

gitpod environment get {env-id} --timeout 15s | grep -i "running"

### Missing the "when not to use" case

A skill that can be over-applied is dangerous. If there are situations where the skill should NOT be invoked, say so explicitly.

When NOT to Use

• Major version upgrades with breaking changes — these need manual review
• PRs that touch schema.rb or database migrations

### Hiding gotchas in prose

Gotchas must be visually prominent. Use `> **Warning:**`, bold text, or a dedicated section. A gotcha buried in paragraph three will be missed.

## Template

Copy this as a starting point:

name: your-skill description: One specific sentence about what this skill does and for what context. allowed-tools: Read, Write, Bash, Glob, Grep

Your Skill

One sentence: what this skill does and why it exists.

When to Use

• Trigger A
• Trigger B

Prerequisites

# verification commands

Workflow

1. Step one

   command here

1. Step two — decision point

Error Handling

Common failure — what to do.

Critical Rules

• Rule 1
• Rule 2