How It Works

harness-kit has three main components and a plugin system. harness.yaml is the config format at the center of everything. The desktop app is a multi-section management console for it. The harness-kit CLI is a standalone terminal tool that compiles it. Plugins — SKILL.md files, agents, hooks, scripts — run inside your AI tools.

harness.yaml

harness.yaml is the single declaration of your entire AI coding setup. It follows the Harness Protocol — an open, vendor-neutral specification.

plugins:
  - research@0.2.0
  - board@0.1.0
  - explain@0.2.0

mcp-servers:
  - name: memory
  - name: filesystem

instructions:
  operational: "Always create a feature branch. Never commit to main."
  behavioral: "Direct, concise. Lead with the answer."

permissions:
  tools:
    allow: ["Bash", "Edit", "Read"]
    deny: ["WebFetch"]
  network:
    allow: ["api.anthropic.com"]

env:
  ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}

extends:
  - profiles/backend-engineer.yaml

The full schema supports version, kind, metadata, plugins, mcp-servers, instructions, permissions, env, and extends. Harness Protocol spec →

Desktop App

The desktop app is a management console organized into named sections. It reads your harness configuration, provides observability into what your AI tools are doing, and gives you direct control over the pieces that are hard to manage from a terminal.

CORE

• Harness — view and edit your harness.yaml, CLAUDE.md, plugins, MCP servers, and hooks in a structured UI
• Marketplace — browse and install plugins from the registry

INSIGHTS

• Observatory — session telemetry: every session, every tool call, token usage, timeline, trends

SYSTEM

• Security — permissions, secrets management, audit log

WORKFLOWS

• Board — AI-native Kanban board with real-time two-way sync; agents pick up cards, flag for review
• Roadmap — AI-generated quarterly roadmaps and competitor analysis tied to your board

Standalone sections

• Agents — monitor and manage specialist subagents running across your harness
• Comparator — run the same prompt across Claude Code, Cursor, and Copilot side by side
• Parity — track which plugins, MCP servers, and skills are loaded in each connected AI tool
• AI Chat — keyboard-first chat window with Ollama support and integrated tools
• Memory — browse, search, and manage the knowledge graph your agents orient themselves in

CLI

The harness-kit CLI is a standalone terminal tool. You run it from your shell; it is not a plugin and does not run inside an AI tool's session.

harness-kit validate          # check harness.yaml against the schema
harness-kit compile           # compile harness.yaml into native per-tool configs
harness-kit sync              # fetch plugins into local cache, write harness.lock
harness-kit check             # detect drift between compiled output and harness.yaml
harness-kit detect            # show which AI platforms are present in the working directory
harness-kit scan              # security audit of installed plugin skill files

compile output — harness-kit compile writes native configuration files for each detected AI tool: .claude/settings.json for Claude Code, .cursor/rules for Cursor, and so on. Each AI tool then loads those files at session start. This is how harness.yaml becomes active in your AI tools — it is compiled, not interpreted at runtime.

Plugin System

Lifecycle

/plugin install research@harness-kit

/research https://github.com/anthropics/claude-code

Plugin Anatomy

plugins/<name>/
├── .claude-plugin/
│   └── plugin.json       # name, version, description
├── skills/
│   └── <name>/
│       ├── SKILL.md      # the workflow (what the AI reads at invocation)
│       └── README.md     # human docs
├── scripts/              # optional: shell automation
├── hooks/                # optional: Stop, PreTool, PostTool handlers
└── agents/               # optional: isolated specialist subagents

SKILL.md vs. a prompt

A SKILL.md is a complete workflow specification, not a prompt template:

• Mandatory step ordering — steps execute in sequence, no skipping
• Input parsing rules — how to interpret arguments and flags
• Tool usage patterns — which tools to call, when, and how
• Output structure — exact format for results
• Error handling — explicit recovery steps 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.

Portability

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

Your harness.yaml serializes your whole setup. Share it, import it, or use it to bootstrap the same configuration on any machine.

/harness-export                       # capture plugins, versions, sources → harness.yaml
/harness-import harness.yaml          # interactive picker: teammate chooses what to install

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.

The SKILL.md is the portable unit. Plugins add distribution, versioning, and automation on top — but the workflow itself is plain text that any AI tool can read. Uninstall a plugin and nothing breaks, because nothing was ever coupled to it.

The spec is open. The format travels.