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.

Why not just copy SKILL.md files?

	Copy-paste	harness-ai-kit
Install a skill	git clone → find the right dir → copy files	harness-ai-kit add skill <url>
Pin versions	Manual tracking	ai-kit.lock with SHA-256
Team consistency	"Works on my machine"	ai-kit.yml + harness-ai-kit sync = identical state
Multiple AI runtimes	Repeat for each tool	--runtime codex/claude-code/cursor/kiro
Dependency conflicts	Silent breakage	SAT solver detects conflicts upfront
Offline / air-gapped	Re-download everything	harness-ai-kit sync --offline from cache

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 (ai-kit.yml + 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 ai-kit.yml 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

Command	What it does
harness-ai-kit init	First-time machine setup
harness-ai-kit add skill <id-or-url>	Add a skill to your project
harness-ai-kit sync	Install declared assets to runtime
harness-ai-kit list	Browse available skills
harness-ai-kit show <id>	Show skill metadata
harness-ai-kit lock	Pin exact versions to ai-kit.lock
harness-ai-kit doctor	Health check your environment
harness-ai-kit remove skill <id>	Remove a skill
harness-ai-kit outdated	Check for updates
harness-ai-kit cache clean	Clear local cache

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 (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

34 production-tested skills included. Install any with harness-ai-kit add skill <id>. 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.

Database Expert Bases (9 skills — schema design, indexing, query tuning, replication)

Skill	Domain
public-mysql-expert-base	MySQL/InnoDB — schema, indexes, locks, tuning
public-postgres-expert-base	PostgreSQL — B-Tree/GIN/GiST, JSONB, partitioning
public-redis-expert-base	Redis — data structures, connection pool, TTL
public-mongodb-expert-base	MongoDB — aggregation, indexes, replica sets
public-kafka-expert-base	Kafka — topics, consumer groups, exactly-once
public-rabbitmq-expert-base	RabbitMQ — exchanges, durability, dead letter
public-oracle-expert-base	Oracle — JDBC, LOB, character set
public-nl2sql-expert-base	NL2SQL — natural language to SQL
public-git-workflow-expert-base	Git — commit, branch, PR conventions

Diagnostic Playbooks (7 skills — enterprise troubleshooting chains)

Skill	Scenario
diag-mysql-deadlock	InnoDB deadlock capture + lock chain analysis
diag-mysql-slow-query	Slow query log + EXPLAIN + index analysis
diag-mysql-replication	Master-slave delay root cause
diag-container-oom	dmesg OOM killer → cgroup → Docker memory
diag-k8s-pod-crashloop	CrashLoopBackOff full-chain diagnosis
diag-k8s-node-pressure	CPU/Memory/Disk/PID pressure
diag-network-port-unreach	DNS → TCP → iptables → service → route

AI Engineering Methodology (5 skills — spec-driven dev, agent architecture, eval, tech debt)

Skill	Purpose
devlab-spec-driven-dev	Spec-driven AI collaboration (requirements → design → tasks)
devlab-ai-agent-engineering	AI agent app architecture methodology
devlab-eval-driven-agent	Eval-driven agent quality system
devlab-ai-kit-miner	Post-session retrospective → asset extraction
devlab-tech-debt-ops	Tech debt lifecycle (audit → refactor → verify)

Patent & Document Authoring (6 skills)

Skill	Purpose
patent-specification-writer	Patent specification drafting
patent-review	Patent quality review with dimensions checklist
patent-disclosure-workflow	Patent disclosure end-to-end workflow
work-sc-patent-specification-writer	Patent spec (work-sc namespace)
work-sc-software-copyright-writer	Software copyright application materials
document-reference-sop-builder	Turn an exemplar document into a reusable SOP

General & Infra (7 skills)

Skill	Purpose
base-cn-registry-mirror-strategy	China mirror acceleration (Docker/Debian/Python/Maven)
base-goal-execution	Goal-driven execution with checkpoints
markitdown	Document-to-Markdown conversion
work-convert / work-export	Document conversion/export
post-task-skill-miner	Post-task retrospective → skill extraction
infra-system-env-ops	Monit watchdog / service self-healing

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.

Phase	Content	Status
v0.1 (current)	CLI + schema + validate + GitHub direct install + curated skill library	✅ Released
v0.2 (planned)	Loop automation framework + hooks mechanism + skill authoring toolkit	🔜 Planned
v0.3 (future)	Expanded infra/devlab skill library + MCP assets + RBAC governance	📋 Backlog
Phase B (long-term)	Public registry backend + browser UI + admin/publisher system	🔬 Research

Project Layout

harness-ai-kit/
├── 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