Skills

Skills bundle a multi-step behavior — prompt, tool sequence, acceptance criteria — into a reusable unit the agent can compose.

If a playbook is "knowledge", a skill is "procedure".

Where they live

<workspace>/.insightworker/skills/<name>/
├── SKILL.md          # the skill definition (required)
├── examples/         # optional reference data the skill can read
└── templates/        # optional output templates

Or globally:

~/.insightworker/skills/<name>/

Bundled skills (shipped with InsightWorker)

Skill	Purpose
`claims-file-prep`	Build a complete claims file from inbound documents
`code-review`	Review the diff on the current branch
`dag-migration-compare`	Translate Airflow + Redshift to Oracle ADW
`dag-run-diagnose`	Walk a failed DAG run to root cause
`document-ocr`	OCR + extract structure from scanned docs
`email-draft-reply`	Draft a reply learning from the user's past sent emails
`email-style-learn`	Sample sent emails, extract the user's voice
`git-app`	Project-specific git conventions
`insurance-intake`	Extract policy terms from broker submission docs
`pipeline-triage`	Classify root cause as data / infra / code / auth
`policy-comparison`	Cross-check loss against bound policy coverage
`project-setup`	Bootstrap a new InsightWorker workspace
`stored-proc-review`	Diff two stored procedures, surface dialect/correctness drift

List installed:

ls $(npm root -g)/@verticalserve/insightworker/skills/

Each SKILL.md is a few hundred lines of plain markdown — readable, fork-able.

Anatomy

---
name: my-skill
triggers: [keyword1, keyword2]
description: One-line description shown in tool catalog
required_tools: [read_file, jira_search, edit_file]
---

# Skill — My Skill

## When to invoke
<plain-language description of the user request shape that triggers this>

## Inputs
- `project` (string, required): JIRA project key
- `since` (string, optional): ISO date, defaults to 7 days ago

## Steps
1. Call `jira_search` with JQL `project = {{project}} AND created >= {{since}}`
2. For each issue, call `jira_issue` to get full description
3. Group by status; format as markdown table
4. Write to `<workspace>/reports/<project>-digest-<date>.md`

## Acceptance criteria
- Output file exists at the expected path
- Contains a row per issue grouped by status
- Total issue count matches `jira_search` result count

## Failure modes to handle
- Empty result set → write a "No new issues" placeholder, don't fail
- JIRA 401 → fail clearly, don't retry (loop detector will catch)

Frontmatter fields

Field	Required	Description
`name`	yes	Slug used to invoke from CLI / args
`triggers`	yes	Keywords that auto-load this skill in conversational use
`description`	recommended	Shown in skill catalog and tool listings
`required_tools`	recommended	Auto-approve list scope; daemon mode enforces this
`model`	optional	Pin a specific model for this skill (e.g. `claude-sonnet-4-5` for hard reasoning)
`max_iterations`	optional	Override `MAX_AGENT_ITERATIONS` for this skill

Invoking a skill

From conversation (auto-resolve via triggers)

> draft a reply to the broker

Agent matches email-draft-reply skill (trigger: draft, reply, broker), loads it, executes.

Explicitly from the CLI

insightworker skill run code-review
insightworker skill run pm-agent-sprint-digest --project PROJ --recipients "team@example.com"

From a daemon schedule

# ~/.insightworker/schedules.yaml
schedules:
  - name: morning-digest
    cron: "0 9 * * MON-FRI"
    skill: pm-agent-sprint-digest
    args:
      project: PROJ

Hierarchy of context the agent loads

In order of precedence (later overrides earlier):

Built-in identity prompt (InsightWorker by VerticalServe)
~/.insightworker/playbooks/global/*.md (globally-installed playbooks)
<workspace>/.insightworker/playbooks/*.md matching the message's triggers
<workspace>/.insightworker/skills/<matched>/SKILL.md (one matched skill)
<workspace>/.insightworker/memory/*.md (long-term memory)
The current user message

The skill's instructions take precedence over generic agent behavior.

Designing a skill — patterns that work

Be explicit about steps. The agent does best when the skill is a numbered procedure, not abstract guidance.

Include acceptance criteria. The agent self-validates against them; without them, you get plausible-looking output that may not be what you wanted.

Name failure modes. "If JIRA returns 401, fail clearly" — the agent will follow it. Otherwise it might try to retry forever (the loop detector catches that, but a clear failure is better).

Keep skills single-purpose. A skill that does both "gather data" and "write report" is harder to debug than two skills chained.

Use templates. If output should follow a structure, drop a templates/report.md.tpl in the skill dir and reference it from SKILL.md. The agent will read it.

Versioning

Skills are markdown — commit them to your project's git repo. PR review applies.