---
name: creating-skills
description: Guide for creating effective skills inside sf. Use when writing a new skill or significantly updating an existing one. Covers concise design, progressive disclosure, sf-specific conventions, and what NOT to include.
---

# Creating Skills

This skill teaches how to write effective skills under `src/resources/extensions/sf/skills/`. Skills are modular, self-contained packages that extend the agent's capabilities with specialised workflows, domain knowledge, and procedural patterns.

For the broader Agent Skills specification, see [agentskills.io/specification](https://agentskills.io/specification). This skill covers sf-specific conventions and design patterns on top of that.

## Core Principles

### Concise is Key

The context window is a public good. Skills share it with everything else: system prompt, conversation history, the actual user request, *other* skills' metadata.

**Default assumption: the agent is already very capable.** Only add context the agent doesn't already have. Challenge each piece of information:

- "Does the agent really need this explanation?"
- "Does this paragraph justify its token cost?"

Prefer concise examples over verbose explanations. A skill that reads like a textbook is bloating the context.

### Set Appropriate Degrees of Freedom

Match specificity to the task's fragility and variability:

| Freedom | Use when | Example |
|---|---|---|
| **High** (text instructions) | Multiple approaches valid; decisions depend on context | "Choose the test type that matches the behaviour." |
| **Medium** (pseudocode / parameterised scripts) | A preferred pattern exists; some variation OK | "Use this template; adjust the model based on cost." |
| **Low** (specific scripts, fixed parameters) | Operations are fragile; consistency is critical | "Run exactly: `npm run typecheck:extensions`." |

Think of the agent walking a path: a narrow bridge with cliffs needs guardrails (low freedom); an open field allows many routes (high freedom).

## Anatomy of a Skill

```
src/resources/extensions/sf/skills/<skill-name>/
├── SKILL.md              # Required: metadata + instructions
├── scripts/              # Optional: executable code (TS/bash)
├── references/           # Optional: docs loaded into context as needed
└── assets/               # Optional: templates, fixtures used in output
```

### `SKILL.md` (required)

Contains:

- **Frontmatter (YAML)** — `name` and `description`. These two fields are *all* the agent sees to decide whether to invoke the skill, so be specific and comprehensive.
- **Body (Markdown)** — instructions and guidance. Loaded only after the skill triggers (if at all).

### Scripts (`scripts/`)

Executable code for tasks needing deterministic reliability or repeatedly rewritten logic.

- **When to include**: same code is being rewritten repeatedly; deterministic reliability needed.
- **Example**: `scripts/score-spec.ts` for computing a numeric quality score on a markdown document.
- **Benefits**: token-efficient (script is *executed*, not read into context); deterministic; consistent.
- **Note**: scripts may still need to be read by the agent for patching or environment-specific tweaks.

### References (`references/`)

Docs loaded into context as needed.

- **When to include**: documentation the agent should reference while working on a specific sub-task.
- **Examples**: `references/phase-machine.md`, `references/provider-routing.md`, `references/sops-secrets.md`.
- **Benefits**: keeps `SKILL.md` lean; loaded only when the agent decides it's needed.
- **Best practice**: if a file is large (>10k words), include grep search patterns in `SKILL.md` so the agent can pinpoint sections without loading the whole file.

### Assets (`assets/`)

Files not loaded into context, but used in the output the skill produces.

- **Examples**: `assets/spec-template.md`, `assets/jsdoc-purpose-snippet.ts`.
- **Benefits**: separates output resources from documentation; copied or modified into the result.

## Progressive Disclosure

Skills use a three-level loading system:

1. **Metadata (name + description)** — always in context (~100 words).
2. **`SKILL.md` body** — loaded when the skill triggers (target <500 lines, <5k words).
3. **Bundled resources** — loaded as needed; scripts can execute without reading.

### Patterns

**Pattern 1 — high-level guide with references**

```markdown
# Doctrine

## Quick start
<core workflow>

## Advanced
- **Subsystem A**: see [REFERENCE-A.md](references/A.md)
- **Subsystem B**: see [REFERENCE-B.md](references/B.md)
```

**Pattern 2 — domain-specific organisation**

For multi-domain skills, split by domain to avoid loading irrelevant context:

```
porting-from-upstream/
├── SKILL.md              (overview + which-upstream selection)
└── references/
    ├── pi-mono.md        (cherry-pick patterns)
    ├── legacy-port.md          (manual port + naming translation)
    └── bunker.md         (skill harvest from remote host)
```

**Pattern 3 — conditional details**

Show core content; link to advanced:

```markdown
## Standard slice
<core flow>

**For multi-file slices:** see [WAVE.md](references/WAVE.md).
**For runtime/provider slices:** see [PROVIDER.md](references/PROVIDER.md).
```

### Important guidelines

- **Avoid deeply nested references.** Keep references one level deep from `SKILL.md`. Linking from `references/A.md` to `references/B.md` is fine; further is hard to discover.
- **Structure long reference files.** Files >100 lines should have a table of contents at the top so the agent can preview scope.
- **Avoid duplication.** Information lives in either `SKILL.md` or a reference file, not both. Prefer references for detail; keep `SKILL.md` for procedure.

## What NOT to Include

A skill should contain only essential files that directly support its functionality. Do **not** create:

- `README.md`
- `INSTALLATION_GUIDE.md`
- `QUICK_REFERENCE.md`
- `CHANGELOG.md`
- Any meta-documentation about the skill-creation process.

The skill exists for the agent to do the job. Auxiliary context about how the skill was made adds clutter.

## Frontmatter Conventions

```yaml
---
name: <kebab-case-skill-name>
description: <one-sentence what + when. Include trigger keywords.>
---
```

### `name`

- Lowercase letters, digits, hyphens.
- Must match the directory name exactly.
- Use *gerund* form for action skills: `creating-skills`, `dispatching-coding-agents`, `clarifying-spec`.
- Use *noun* form for doctrine skills: `code-review`, `advisory-partner`, `spec-first-tdd`.
- Max 64 chars.

### `description`

- Third person: "Dispatches stateless coding agents…", not "I help you dispatch…".
- State both *what* it does AND *when* to use it.
- Include trigger keywords the agent will recognise — phrases the user is likely to say.
- Max 1024 chars.

Example:

```yaml
---
name: dispatching-coding-agents
description: Dispatch stateless coding agents (Claude Code, Codex) via Bash as subagents. Use when stuck on a hard problem, want a second opinion, or need parallel research. They have no memory — provide all context.
---
```

## Body Writing Guidelines

- **Imperative or infinitive form.** "Use git worktrees" not "You should use git worktrees".
- **Tables for choices**, prose for procedure. Tables compress; prose expresses sequence.
- **Concrete file paths** in examples. `src/resources/extensions/sf/auto/loop.ts:140` beats "the auto-loop file".
- **Cross-link siblings.** When this skill hands off to another, link to it: `[finish-and-verify](../finish-and-verify/SKILL.md)`.
- **Cite the doctrine.** When a rule comes from `docs/SPEC_FIRST_TDD.md` or `AGENTS.md`, link those — don't restate them.

## Skill Creation Process

### 1. Understand with concrete examples

Before drafting, collect 2–3 concrete examples of how the skill will be used.

- "What user phrases should trigger this?"
- "What does the agent need to do that it can't already?"
- "What's the worst-case failure if this skill is wrong?"

If you can't name 2 concrete examples, the skill is probably premature.

### 2. Plan reusable contents

For each example, identify what scripts / references / assets would help repeated execution. The "is this code rewritten every time?" test is a good signal a `script` is worth bundling.

### 3. Initialise the skill

```bash
mkdir -p src/resources/extensions/sf/skills/<name>/{scripts,references,assets}
$EDITOR src/resources/extensions/sf/skills/<name>/SKILL.md
```

Delete unused subdirs — most skills only need `SKILL.md`.

### 4. Write the body

Open with one paragraph stating purpose. Then *when to run*. Then procedure (numbered steps if sequential, sections if not).

End with rules / red flags / cross-links to siblings — not a "summary" or "conclusion" section.

### 5. Test the skill

Trigger it on a real task. Notice what's confusing, what's missing, what's redundant. Iterate.

### 6. Iterate

Most skills get 3–5 iterations after first use. Common revisions:

- Tighten the description (the trigger keywords were wrong).
- Move detail from `SKILL.md` into `references/` (body is bloating).
- Add an example you wish you'd had on first use.

## Rules

- **Tools the skill assumes** must exist in sf. Don't reference Letta-MCP tools, claude-flow CLIs, or anything else not in this repo.
- **Cite real paths.** Every file path in a skill should resolve.
- **Sibling links must work.** When a skill says "see X-skill", that skill must exist.
- **Rule of three.** Don't write a skill until you've done the same task three times. The first two are how you learn what's stable.
- **Don't write a skill the agent can derive from existing context.** A skill that only lists files in `src/` is worse than `ls`.
