How harness-kit Works

harness-kit packages proven AI workflows as portable plugins. This page explains the pieces and how they fit together.

The Stack

Plugin Lifecycle

1. Source — You register harness-kit as a plugin source in your AI tool. This points to the collection — not individual plugins.
2. Install — You install a plugin by name. Your harness downloads the plugin directory and makes it available locally.
3. Discovery — At session start, your harness scans installed plugins and registers any skills it finds.
4. Invocation — You invoke a command (e.g. /research). Your harness loads the matching SKILL.md into context as the workflow definition.
5. Execution — The AI follows the steps in the SKILL.md, using available tools (file I/O, web fetch, shell commands, MCP servers).

Distribution today: harness-kit distributes through Claude Code's plugin marketplace. SKILL.md files are plain markdown — any tool that reads prompt templates can use them directly. See Using with Other Tools.

Starting Fresh on a New Machine

Your harness setup is fully reproducible. Config files live in version control; plugins reinstall from the registry with the same commands you used the first time.

Plugin Anatomy

Every plugin follows the same directory structure:

plugins/<name>/
├── .claude-plugin/
│   └── plugin.json         # name, version, description
├── skills/
│   └── <name>/
│       ├── SKILL.md        # the workflow (what Claude reads)
│       └── README.md       # human documentation
└── scripts/                # optional: automation scripts
    hooks/                  # optional: event hooks
    agents/                 # optional: agent configurations

Component	Role	When it runs
plugin.json	Metadata — name, version, description	At install and update
SKILL.md	Workflow definition — the actual instructions Claude follows	At slash command invocation
README.md	Human-facing docs — usage examples, notes	Never (reference only)
scripts/	Shell scripts for automation	Called by SKILL.md or hooks
hooks/	Event handlers (e.g., Stop hook)	On harness lifecycle events
agents/	Agent configurations	When a skill spawns subagents

What Makes a Skill Different from a Prompt

A SKILL.md is more than a prompt — it's a complete workflow specification:

• Mandatory step ordering — steps must execute in sequence, no skipping
• Input parsing rules — how to interpret arguments
• Tool usage patterns — which tools to use when and how
• Output structure — exact format for results
• Error handling — what to do when things fail
• Common mistakes table — known failure modes and fixes

This structure makes skills repeatable across sessions and transferable across users. The same /research invocation produces the same workflow regardless of who runs it.

Design Philosophy

harness-kit is a framework without a runtime. No SDK, no build step, no execution layer to depend on. The framework is the config format and the portability it creates — uninstall a plugin and nothing breaks, because nothing was ever coupled to it. Skills are plain markdown, readable and editable by anyone.

The SKILL.md is the portable unit. Plugins add distribution, versioning, and optional automation on top — but the workflow itself is just text that any AI tool can read.