skill-harness 0.1.0

Lifecycle management for AI agent skills — install, audit, eval, sync across environments
Documentation

Skill Harness

Lifecycle management for AI agent skills — install, audit, eval, sync across environments.

Implements the Agent Skills Standard 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:

---
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 for the full format specification, including directory structure, frontmatter fields, activation modes, and validation rules.

Related Work

  • Agent Rules -- Convention for prescribed policy in instruction files
  • Agent Runbooks -- Convention for externalizing procedures into on-demand runbook files
  • Agent Memories -- Convention for committed memories (type, scope, why, how to apply)
  • AGENTS.md -- Universal instruction file spec (Linux Foundation)
  • Claude Code Skills -- Progressive disclosure for agent procedures
  • Cursor Rules -- Cursor's rule system with Agent Requested mode

License

CC0 1.0 -- Public domain. Use this convention however you like.