# Skill Harness
Lifecycle management for AI agent skills — install, audit, eval, sync across environments.
Implements the [Agent Skills Standard](https://agentskills.io) with environment-aware installation, validation, and testing.
## The Problem
AI agents need domain-specific capabilities that load on demand. Currently each tool has its own approach:
- Claude Code has `.claude/skills/`
- Cursor has Agent Requested `.mdc` rules
- GitHub Copilot has `applyTo` scoped instructions
- Windsurf has `.windsurf/rules/` with triggers
- Gemini CLI has `@file` imports
- Aider has `--read` flag
There is no shared convention for bundling capabilities -- rules, runbooks, and examples -- into a portable, activatable unit. The result: skills are tool-locked, non-composable, and duplicated across formats.
## The Convention
Place skills in `.agent/skills/<name>/` directories:
```
.agent/skills/<name>/
├── SKILL.md # instruction content + activation metadata
├── runbooks/ # on-demand procedures (optional)
└── examples/ # reference material (optional)
```
Each skill is a self-contained directory with a `SKILL.md` file that defines the instruction content and activation metadata:
```markdown
---
description: "One-line description for contextual activation"
globs: ["**/*.test.ts"] # optional: file-pattern triggers
---
# Skill Name
Instructions, rules, and guidance for this capability.
## Runbooks
- **Deploy**: Follow `runbooks/deploy.md` when deploying this component.
```
The SKILL.md frontmatter tells the agent *when* to activate the skill. The body tells it *what to do*.
## Skill Content
A skill bundles three content types:
| Content | Purpose | Location |
|---------|---------|----------|
| **Rules** | Conventions and constraints for this capability | Inline in SKILL.md body |
| **Runbooks** | Step-by-step procedures | `runbooks/*.md` files |
| **Examples** | Reference implementations, templates | `examples/` directory |
Rules are the always-relevant policy. Runbooks are loaded when performing specific tasks. Examples provide concrete reference material the agent can consult.
## Activation Modes
Skills can be activated in four ways:
| Mode | Trigger | Frontmatter |
|------|---------|-------------|
| **Always** | Loaded on every interaction | `alwaysApply: true` |
| **File-pattern** | Loaded when matching files are open/relevant | `globs: ["**/*.rs"]` |
| **Agent-requested** | Agent decides based on `description` | `description: "..."` |
| **Manual** | User explicitly references the skill | (none needed) |
## Cross-Harness Compatibility
This convention works with any AI coding assistant that can read project files:
| Tool | Native format | Mapping from .agent/skills/ |
|------|--------------|---------------------------|
| Claude Code | `.claude/skills/*/SKILL.md` | Symlink or copy |
| Cursor | `.cursor/rules/*.mdc` | Generate .mdc from SKILL.md frontmatter |
| Windsurf | `.windsurf/rules/*.md` | Generate rule from SKILL.md |
| Copilot | `.github/copilot-instructions.md` | Merge skills into scoped instructions |
| Gemini CLI | `GEMINI.md` + `@file` imports | Add `@skill/SKILL.md` references |
| Codex | Per-directory `AGENTS.md` | Copy skill directory, add AGENTS.md |
| Aider | `--read` flag / `.aider.conf.yml` | Add to read list |
The skill *content* is portable -- write it once in `.agent/skills/`, then symlink, generate, or merge into tool-specific formats.
## Design Principles
1. **Composable.** One capability per skill. Skills combine but don't overlap.
2. **Portable.** Works across tools via symlinks, generation, or copy.
3. **On-demand.** Loaded when needed, absent when not. Activation metadata tells the agent when.
4. **Self-contained.** A skill directory has everything needed -- rules, procedures, examples.
5. **Version-controlled.** Skills are code. They belong in the repo.
## Relationship to Other Specs
Skills bundle the other content types into activatable units:
```
agent-skills (bundle format + activation)
├── agent-rules (instruction content within skills)
├── agent-runbooks (procedures within skills)
└── agent-memories (lessons generated by skills)
```
Rules define *what* policy applies. Runbooks define *how* to perform tasks. Memories capture *what was learned*. Skills bundle all three with *when* to activate.
## Spec
See [SPEC.md](SPEC.md) for the full format specification, including directory structure, frontmatter fields, activation modes, and validation rules.
## Related Work
- [Agent Rules](https://github.com/btakita/agent-rules) -- Convention for prescribed policy in instruction files
- [Agent Runbooks](https://github.com/btakita/agent-runbooks) -- Convention for externalizing procedures into on-demand runbook files
- [Agent Memories](https://github.com/btakita/agent-memories) -- Convention for committed memories (type, scope, why, how to apply)
- [AGENTS.md](https://agents.md/) -- Universal instruction file spec (Linux Foundation)
- [Claude Code Skills](https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills) -- Progressive disclosure for agent procedures
- [Cursor Rules](https://docs.cursor.com/context/rules-for-ai) -- Cursor's rule system with Agent Requested mode
## License
[CC0 1.0](LICENSE) -- Public domain. Use this convention however you like.