harness-ai-kit

Package manager for AI agent assets — install, lock and govern skills / CLIs / MCPs / loops across Codex, Claude Code, Cursor and Kiro. Includes an enterprise-grade AI-ops skill library.

Quickstart · Skill Catalog · Usage Scenarios · Docs · Roadmap · Changelog · 中文文档

Why

As AI agents proliferate, teams accumulate reusable prompts, skills, CLIs and MCP servers — but there's no npm for these assets. harness-ai-kit fills that gap: one CLI to install, resolve, lock, validate and govern AI agent assets across multiple runtimes.

Build Less, Compose More (a.k.a. the REMIX methodology)

harness-ai-kit is a composition layer, not another vertical toolkit. It does not compete with well-known single-purpose community AI kits — it composes them. Where a focused community skill, CLI, or MCP server already does a job well, harness-ai-kit's role is to install, pin, and orchestrate it alongside everything else, never to reinvent it. Build less; reuse and compose more.

We call this composition-first stance the REMIX methodology:

• Reuse — pull in existing community skills / CLIs / MCP servers instead of rebuilding them.
• Extend — when something is close, extend it (via the extends mechanism) rather than fork-and-rewrite.
• Mix — combine assets across types (skill × CLI × MCP × loop) into one coherent workflow.
• Integrate — install, pin, lock and version everything through a single manifest (harness-ai-kit.yml + .lock).
• eXecute — orchestrate the composed assets across runtimes (Codex, Claude Code, Cursor, Kiro).

Why not just copy SKILL.md files?

No lock-in — you don't have to use harness-ai-kit

Every skill in the catalog is a plain folder of Markdown + JSON. If you don't want another CLI, you don't need one:

• Let your agent fetch it — paste the skill's GitHub URL to Codex / Claude Code / Cursor and ask it to install the skill into your runtime's skills directory.
• npx / one-off scripts — pull a single SKILL.md straight from the repo, no install step.
• Copy the folder yourself — drop it into .agents/skills/ (Codex) or .claude/skills/ (Claude Code) by hand.

harness-ai-kit is not a gatekeeper for the content. What it adds on top is the asset manifest: a curated, versioned, checksummed inventory (harness-ai-kit.yml + harness-ai-kit.lock) of what your project uses. If that inventory is useful to you, the CLI is the fastest way to manage it. If not, the skills work fine without it.

Team collaboration — commit the manifest, not the assets

The manifest is where harness-ai-kit pays off most. The intended team flow:

Member A (sets up)
  harness-ai-kit add skill devlab-spec-driven-dev
  harness-ai-kit add skill diag-mysql-deadlock
  git add harness-ai-kit.yml harness-ai-kit.lock        # commit ONLY the manifest
  git commit -m "chore: pin team AI skills"

Member B (joins / updates)
  harness-ai-kit sync                            # done — exact same assets, SHA-256 verified

Two concrete benefits:

1. Nothing sensitive leaves the repo. Member A commits only two small YAML/JSON files. The raw skill folders — which may carry local paths, personal runtime config, or credentials from a member's own machine — are never committed. Member B re-materializes them locally from the manifest.
2. Updates are cheap and non-destructive. When the team bumps a skill version, members just harness-ai-kit sync (or harness-ai-kit update) to pull the latest. Because the lockfile records exactly what's managed by harness-ai-kit, a member's own hand-added / custom skills are left untouched — sync reconciles the manifest, it doesn't wipe your local additions.

In short: the manifest is the team's shared source of truth for "which AI assets we run", and sync is how everyone stays identical without sharing anything sensitive.

Quick Start

pip install harness-ai-kit
harness-ai-kit init
cd your-project
harness-ai-kit add skill https://github.com/anthropics/skills/tree/main/skills/skill-creator
harness-ai-kit sync

Short alias: every command is also available as ai-kit (e.g. ai-kit sync). Use whichever you prefer — both invoke the same CLI.

Verify it worked:

harness-ai-kit doctor              # health check — should be all green
ls .agents/skills/          # skill-creator should be here

The skill is now available to your AI agent. See examples/ for real-world usage patterns (team sync, multi-runtime, offline mode).

Command Cheatsheet

Full reference: docs/cli-reference.md

Features

• Unified asset schema — skills, CLIs, MCPs, plugins, hooks, subagents and loops share one typed dependency model with pinned versions
• Dependency resolution — resolvelib-based solver with lockfile (harness-ai-kit.lock) and checksum verification
• Multi-runtime support — install to Codex, Claude Code, Cursor, Kiro (project or global scope)
• GitHub direct install — install skills from any GitHub repo, no private registry required
• Staging + rollback — atomic installs with automatic rollback on failure
• Offline mode — cache-driven install without network access
• Enterprise skill library — curated ops skills (MySQL deadlock diagnosis, K8s CrashLoopBackOff, container OOM, etc.) included

Installation

pip install harness-ai-kit

Requires Python >= 3.10 and git.

Built-in Skill Library

56 production-tested skills + 6 companion CLIs included. Install any with harness-ai-kit add skill <id> (or pip install sf-<cli>). Full categorized index: CATALOG.md.

New here? Read Usage Scenarios first — it explains how skills get pulled into real work via an SDD framework (e.g. Trellis), and how loops bind to a runtime.

Full catalog with install commands: CATALOG.md · usage patterns: docs/usage-scenarios.md

Architecture

┌─────────────────────────────────────────────────────┐
│                    harness-ai-kit CLI                        │
│  init · add · install · sync · lock · resolve ·     │
│  graph · why · validate · doctor · upgrade · cache  │
├─────────────────────────────────────────────────────┤
│              Package Manager Core                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐   │
│  │ Resolver │  │ Lockfile │  │ Runtime Adapters  │   │
│  │ (resolve)│  │ (lock)   │  │ codex·claude·kiro│   │
│  └────┬─────┘  └────┬─────┘  └────────┬─────────┘   │
│       │              │                  │             │
│  ┌────▼──────────────▼──────────────────▼─────────┐  │
│  │          Source Abstraction Layer               │  │
│  │  GitHub repos · PyPI · raw registries · cache   │  │
│  └─────────────────────────────────────────────────┘  │
├─────────────────────────────────────────────────────┤
│              Enterprise Skill Library                │
│  public-*-expert-base · diag-* · infra-* · loops     │
└─────────────────────────────────────────────────────┘

Roadmap

See ROADMAP.md for the full plan with milestone criteria.

Project Layout

harness-ai-kit/
├── harness_ai_kit/      # CLI source code
│   ├── commands/        # Command handlers (install, resolve, lock, ...)
│   ├── domain/          # Domain models (manifest, lockfile, resolver, ...)
│   ├── infrastructure/   # Infrastructure (git ops, registry client, ...)
│   └── data/             # Default config seed
├── skills/              # Curated enterprise skill library
├── examples/            # Real-world usage examples
├── docs/                # Documentation
│   ├── quickstart.md    # Step-by-step getting started
│   ├── cli-reference.md # Complete CLI command reference
│   ├── concepts.md      # Core concepts explained
│   ├── skill-authoring.md # Write your own skills
│   ├── asset-map.md     # Skill library catalog
│   └── troubleshooting.md # Common issues and fixes
├── .github/             # CI, issue templates, community files
├── pyproject.toml       # Package metadata
└── LICENSE              # Apache-2.0

Community & Support

• Questions: GitHub Discussions or SUPPORT.md
• Bugs & features: Issue tracker
• Security: See SECURITY.md
• Changes: See CHANGELOG.md

Contributing

See CONTRIBUTING.md. We use the Developer Certificate of Origin (DCO) — all commits must be signed off.

License

Apache-2.0 © 2026 SeedForge