The Skill System

What a skill is

A skill is a reusable instruction file. It captures “how this type of task should be done” in Markdown; the AI loads it when relevant and follows the proven path.

Without a skill, it rediscovers the approach every time. With one, it executes the path you already validated.

Two storage locations

Level	Path	Use for
User	`~/.workbuddy/skills/<name>/SKILL.md`	Cross-project workflows
Project	`{workspace}/.workbuddy/skills/<name>/SKILL.md`	Repo-specific procedures

Default to user level unless the skill is meaningless outside one project.

How a skill gets triggered

1. Automatic, by relevance When your request matches the skill’s description, it loads itself. Which means: a poorly written description is a skill nobody ever triggers.

2. You name it directly “Use the xxx skill to…”

⚠️ Skills aren’t magic. If it isn’t following yours, the description is probably too narrow to match how you phrased the request.

Skeleton of a skill

Create ~/.workbuddy/skills/my-workflow/SKILL.md:

---
name: my-workflow
description: Use when the user needs to [do the thing]. Triggers: [keyword], [synonym]
---

# Skill Name

## When to use
(one sentence)

## Steps
1. First thing
2. Second thing
3. How to verify it's done

## Gotchas
(mistakes you've already made here)

The description is the critical part. State when it applies and how users will phrase the request — list several synonyms.

A real example

Suppose you publish a weekly digest: scrape sources → translate → format → publish.

The first run might take 20 turns. Afterward:

Turn the workflow we just did into a skill at ~/.workbuddy/skills/weekly-digest/SKILL.md — include sources, translation rules, formatting spec, publishing steps, and the two mistakes we hit.

Next week you say “do this week’s digest” and it follows the skill.

Maintaining skills

After each real use, if you find unclear steps, a better path, or a changed environment — update it.

An unmaintained skill is a liability, not an asset. A stale one makes the AI do things the old, wrong way.

Installing third-party skills

A skill is an instruction file the AI will execute — equivalent to code. Before installing, check for:

Reads of sensitive files (keys, browser cookies)
Outbound data transmission
Destructive commands (delete, format)

If you find anything critical, don’t install it.

Subagents and Parallel Tasks.