# agent-skills spec

Format specification for contextually-activated instruction bundles. Skills package rules, runbooks, and examples into self-contained directories with activation metadata.

## Skill Directory Structure

```
.agent/skills/<name>/
├── SKILL.md           # required: instruction content + activation metadata
├── runbooks/          # optional: on-demand procedures
│   ├── deploy.md
│   └── migrate.md
└── examples/          # optional: reference material
    ├── config.yaml
    └── template.ts
```

The skill name is the directory name. It should be a lowercase slug (e.g., `testing`, `deploy`, `api-client`).

## SKILL.md Format

Each SKILL.md is a markdown file with optional YAML frontmatter:

```markdown
---
description: "One-line description for contextual activation"
globs: ["**/*.test.ts", "**/*.spec.ts"]
alwaysApply: false
---

# Skill Name

Instruction content here. This is the body that gets loaded when the skill activates.

## Rules

- Convention or constraint specific to this capability.

## Runbooks

- **Deploy**: Follow `runbooks/deploy.md` when deploying.
- **Migrate**: Follow `runbooks/migrate.md` for database migrations.
```

### Frontmatter Fields

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `description` | string | yes | -- | One-line summary used for agent-requested activation |
| `globs` | string[] | no | `[]` | File patterns that trigger activation |
| `alwaysApply` | boolean | no | `false` | Whether to load on every interaction |

### Body Content

The markdown body contains the skill's instruction content. It can include:

- **Rules** -- declarative policy (conventions, constraints, architecture decisions)
- **Runbook references** -- pointers to procedures in the `runbooks/` directory
- **Inline guidance** -- any other instruction content relevant to this capability

## Activation Modes

Skills activate based on their frontmatter configuration:

### Always

```yaml
---
description: "Project-wide coding conventions"
alwaysApply: true
---
```

Loaded on every interaction. Use sparingly -- this adds to base context cost.

### File-pattern

```yaml
---
description: "Testing conventions and utilities"
globs: ["**/*.test.ts", "**/*.spec.ts", "tests/**"]
---
```

Loaded when the agent is working with files matching the glob patterns. The matching semantics follow gitignore-style globs.

### Agent-requested

```yaml
---
description: "Database migration procedures and conventions"
---
```

The agent reads the `description` and decides whether to load the skill based on the current task. No `globs` or `alwaysApply` -- activation is the agent's judgment call.

### Manual

No frontmatter needed. The user explicitly tells the agent to use the skill:

> "Use the deploy skill for this."

Or references it directly:

> "Follow `.agent/skills/deploy/SKILL.md`."

## Runbooks Directory

Skills can include runbooks in a `runbooks/` subdirectory. These follow the [agent-runbooks](https://github.com/btakita/agent-runbooks) convention:

```
.agent/skills/deploy/
├── SKILL.md
└── runbooks/
    ├── production.md
    └── staging.md
```

Reference runbooks from SKILL.md:

```markdown
## Runbooks

- **Production deploy**: Follow `runbooks/production.md` for production releases.
- **Staging deploy**: Follow `runbooks/staging.md` for staging environments.
```

The trigger phrase (e.g., "Production deploy") tells the agent when to load the referenced runbook.

## Examples Directory

Skills can include reference material in an `examples/` subdirectory:

```
.agent/skills/api-client/
├── SKILL.md
└── examples/
    ├── basic-usage.ts
    └── error-handling.ts
```

Examples are not loaded by default -- the agent reads them when it needs concrete reference material.

## Install Semantics

To install a skill into a project:

1. Copy or symlink the skill directory into `.agent/skills/<name>/`
2. The skill is immediately available -- no registration step required
3. For tool-specific formats, generate the native representation:

**Claude Code:**
```bash
ln -s ../../.agent/skills/deploy .claude/skills/deploy
```

**Cursor (generate .mdc):**
```
---
description: "Deploy procedures and conventions"
globs:
alwaysApply: false
---
# Deploy
...
```

**Copilot (merge into scoped instructions):**
```markdown
## Deploy (from .agent/skills/deploy)
...
```

## Validation Rules

When auditing skills:

1. **SKILL.md required**: Every skill directory must contain a `SKILL.md` file
2. **Description required**: Frontmatter must include a `description` field
3. **Runbooks exist**: Any runbook referenced in SKILL.md must exist in the `runbooks/` directory
4. **No machine-local paths**: Same context invariant as other instruction files -- no `~/`, `/home/user/`, or absolute paths that won't resolve on other machines
5. **Valid frontmatter**: If YAML frontmatter is present, it must parse without errors
6. **Unique names**: No duplicate skill directory names within a project

## Relationship to Other Specs

| Spec | Role in Skills |
|------|---------------|
| [agent-rules](https://github.com/btakita/agent-rules) | Rule content appears inline in SKILL.md body |
| [agent-runbooks](https://github.com/btakita/agent-runbooks) | Procedures live in the skill's `runbooks/` directory |
| [agent-memories](https://github.com/btakita/agent-memories) | Skills may generate memories during use; memories reference the skill scope |

## Agentic Contracts

Behavioral promises the agent makes when performing skill lifecycle operations. These contracts are testable via the evals below.

### Install

When installing skills, the agent promises to:

- **Install to the correct environment-specific path.** Each target environment (Claude Code, Cursor, Windsurf, etc.) has a distinct native path. The agent resolves the correct one based on the detected or specified environment.
- **Never overwrite without checking.** If a skill file already exists at the target path, the agent compares content before deciding to update. It does not silently clobber existing customizations.
- **Report the installed path.** After installation, the agent tells the user exactly where the skill was placed so they can verify.

### Check

When checking skills, the agent promises to:

- **Compare content exactly (not just version).** Staleness is determined by byte-level content comparison, not version strings or timestamps.
- **Report outdated vs missing vs up-to-date accurately.** Each skill gets one of three statuses. The agent never conflates "missing" with "outdated" or reports false positives.

### Uninstall

When uninstalling skills, the agent promises to:

- **Remove only the skill file.** The agent deletes the specific skill artifact and nothing else.
- **Clean up empty parent directories.** After removing the skill file, the agent removes any directories that are now empty up to the environment root.
- **Not remove other files.** Sibling skills, user-created files, and unrelated content in the same tree are never touched.

## Evals

Planned evaluations that verify the agentic contracts above. Each eval is a scenario the agent must handle correctly.

| Eval | Contract | Description |
|------|----------|-------------|
| [install_idempotent](evals/install_idempotent.md) | Install | Installing a skill twice produces the same result -- no duplicates, no errors, identical output |
| [environment_path_resolution](evals/environment_path_resolution.md) | Install | Each target environment resolves to its correct native path |
| [uninstall_cleanup](evals/uninstall_cleanup.md) | Uninstall | Uninstall removes the skill file and empty parent directories only |
