fellowship-dev 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.
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."
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
```bash
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
bashlang - Show expected output when it matters for verification
- Decision points use tables or
if/elseprose, not vague "depending on..."
Example:
## Workflow
1. **List environments**
```bash
gitpod environment list --timeout 60s
Filter by repository URL. Count running/stopping envs for this repo.
Check pool limits — abort if count >= 3 (issue) or >= 2 (deps)
Claim a stopped env (prefer reuse over create)
gitpod environment start {env-id} --set-as-context --dont-waitCheck for active pilot before claiming:
gitpod environment ssh {env-id} -- "pgrep -x claude || echo NO_PILOT"If a
claudeprocess exists, this pod is occupied. Pick another.
### 5. Decision Tables
Use tables whenever there are multiple paths or risk tiers.
```markdown
## Risk Classification
| Condition | Risk | Action |
|-----------|------|--------|
| Patch update, build passes, tests pass | Low | Auto-merge with [skip ci] |
| Minor update, build passes | Medium | Flag for review |
| Major update or build fail | High | Block — manual review required |
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
-
descriptionis 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
3. Run the appropriate command to start the environment.
# Good
3. Start the environment:
```bash
gitpod environment start {env-id} --set-as-context --dont-wait
### Instructing the user instead of the agent
```markdown
# Bad
The user should verify that the environment is running before proceeding.
# Good
Verify the environment is running:
```bash
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.
```markdown
## 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
```bash
# verification commands
Workflow
Step one
command hereStep two — decision point
Condition Action Case A Do X Case B Do Y
Error Handling
Common failure — what to do.
Critical Rules
- Rule 1
- Rule 2