Agent Harness
Production-grade engineering skills for AI coding agents.
Skills encode the workflows, quality gates, and best practices that senior engineers use when building software. These ones are packaged so AI agents follow them consistently across every phase of development.
DEFINE PLAN BUILD VERIFY REVIEW SHIP
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
│ Idea │ ───▶ │ Spec │ ───▶ │ Code │ ───▶ │ Test │ ───▶ │ QA │ ───▶ │ Go │
│Refine│ │ PRD │ │ Impl │ │Debug │ │ Gate │ │ Live │
└──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘
/spec /plan /build /test /review /ship
Commands
7 slash commands that map to the development lifecycle. Each one activates the right skills automatically.
| What you're doing | Command | Key principle |
|---|---|---|
| Define what to build | /spec |
Spec before code |
| Plan how to build it | /plan |
Small, atomic tasks |
| Build incrementally | /build |
One slice at a time |
| Prove it works | /test |
Tests are proof |
| Review before merge | /review |
Improve code health |
| Simplify the code | /code-simplify |
Clarity over cleverness |
| Ship to production | /ship |
Faster is safer |
Want fewer manual steps once the spec exists? /build auto generates the plan and implements every task in a single approved pass — you approve the plan once, then it runs autonomously. It removes the human stepping between tasks, not the verification: every task is still test-driven and committed individually, and it pauses on failures or risky steps.
Skills also activate automatically based on what you're doing — designing an API triggers api-and-interface-design, building UI triggers frontend-ui-engineering, and so on.
Quick Start
Marketplace install:
/plugin marketplace add https://github.com/Ghosteken/agent-harness.git
/plugin install agent-harness
Direct CLI install:
claude plugin install https://github.com/Ghosteken/agent-harness.git --scope user
Authentication issues? If you encounter Git or SSH errors, using the full HTTPS URL as shown above is the most robust method. It bypasses SSH configuration and uses standard HTTPS cloning.
Local / development:
git clone https://github.com/Ghosteken/agent-harness.git
claude --plugin-dir /path/to/agent-harness
Script installer (local clone → global install):
bash scripts/install.sh --global # macOS / Linux / Git Bash
.\scripts\install.ps1 -Global # Windows PowerShell
Claude desktop upload (.plugin file):
Use agent-harness.plugin at the repo root. To rebuild it after making changes:
bash scripts/build-plugin.sh # macOS / Linux / Git Bash
.\scripts\build-plugin.ps1 # Windows PowerShell
.\scripts\build-plugin.ps1 -Out "C:\Desktop\agent-harness.plugin" # custom output path
Then in Claude desktop: Settings → Extensions → Upload local plugin → select the .plugin file.
Copy any SKILL.md into .cursor/rules/, or reference the full skills/ directory. See docs/cursor-setup.md.
Install as a native plugin for skills, subagents, and slash commands. See docs/antigravity-setup.md.
Install from the repo:
agy plugin install https://github.com/Ghosteken/agent-harness.git
Install from a local clone:
git clone https://github.com/Ghosteken/agent-harness.git
agy plugin install ./agent-harness
Install as native skills for auto-discovery, or add to GEMINI.md for persistent context. See docs/gemini-cli-setup.md.
Install from the repo:
gemini skills install https://github.com/Ghosteken/agent-harness.git --path skills
Install from a local clone:
gemini skills install ./agent-harness/skills/
Add skill contents to your Windsurf rules configuration. See docs/windsurf-setup.md.
Uses agent-driven skill execution via AGENTS.md and the skill tool.
Use agent definitions from agents/ as Copilot personas and skill content in .github/copilot-instructions.md. See docs/copilot-setup.md.
Skills are plain Markdown - they work with any agent that accepts system prompts or instruction files. See docs/getting-started.md.
Skills
The library contains a curated set of 173 skills across every engineering domain — the rest of the original bulk import lives in archive/skills-community/, unexposed but recoverable. The commands above are built on a 24-skill core — 23 lifecycle workflow skills plus the using-agent-harness meta-skill — that runs the spec → plan → build → review → ship cycle. Every specialist skill in the library can also be invoked directly or through an agent scope (see docs/SCOPE.md).
Core Lifecycle Skills
Meta - Discover which skill applies
| Skill | What It Does | Use When |
|---|---|---|
| using-agent-harness | Maps incoming work to the right skill workflow and defines shared operating rules | Starting a session or deciding which skill applies |
Define - Clarify what to build
| Skill | What It Does | Use When |
|---|---|---|
| interview-me | One-question-at-a-time interview that extracts what the user actually wants instead of what they think they should want, until ~95% confidence | The ask is underspecified, or the user invokes "interview me" / "grill me" |
| idea-refine | Structured divergent/convergent thinking to turn vague ideas into concrete proposals | You have a rough concept that needs exploration |
| spec-driven-development | Write a PRD covering objectives, commands, structure, code style, testing, and boundaries before any code | Starting a new project, feature, or significant change |
Plan - Break it down
| Skill | What It Does | Use When |
|---|---|---|
| planning-and-task-breakdown | Decompose specs into small, verifiable tasks with acceptance criteria and dependency ordering | You have a spec and need implementable units |
Build - Write the code
| Skill | What It Does | Use When |
|---|---|---|
| incremental-implementation | Thin vertical slices - implement, test, verify, commit. Feature flags, safe defaults, rollback-friendly changes | Any change touching more than one file |
| test-driven-development | Red-Green-Refactor, test pyramid (80/15/5), test sizes, DAMP over DRY, Beyonce Rule, browser testing | Implementing logic, fixing bugs, or changing behavior |
| context-engineering | Feed agents the right information at the right time - rules files, context packing, MCP integrations | Starting a session, switching tasks, or when output quality drops |
| source-driven-development | Ground every framework decision in official documentation - verify, cite sources, flag what's unverified | You want authoritative, source-cited code for any framework or library |
| doubt-driven-development | Adversarial fresh-context review of every non-trivial decision in-flight - CLAIM → EXTRACT → DOUBT → RECONCILE → STOP, with optional user-authorized cross-model escalation | Stakes are high (production, security, irreversible), working in unfamiliar code, or a confident output is cheaper to verify now than to debug later |
| frontend-ui-engineering | Component architecture, design systems, state management, responsive design, WCAG 2.1 AA accessibility | Building or modifying user-facing interfaces |
| api-and-interface-design | Contract-first design, Hyrum's Law, One-Version Rule, error semantics, boundary validation | Designing APIs, module boundaries, or public interfaces |
Verify - Prove it works
| Skill | What It Does | Use When |
|---|---|---|
| browser-testing-with-devtools | Chrome DevTools MCP for live runtime data - DOM inspection, console logs, network traces, performance profiling | Building or debugging anything that runs in a browser |
| debugging-and-error-recovery | Five-step triage: reproduce, localize, reduce, fix, guard. Stop-the-line rule, safe fallbacks | Tests fail, builds break, or behavior is unexpected |
Review - Quality gates before merge
| Skill | What It Does | Use When |
|---|---|---|
| code-review-and-quality | Five-axis review, change sizing (~100 lines), severity labels (Nit/Optional/FYI), review speed norms, splitting strategies | Before merging any change |
| code-simplification | Chesterton's Fence, Rule of 500, reduce complexity while preserving exact behavior | Code works but is harder to read or maintain than it should be |
| security-and-hardening | OWASP Top 10 prevention, auth patterns, secrets management, dependency auditing, three-tier boundary system | Handling user input, auth, data storage, or external integrations |
| performance-optimization | Measure-first approach - Core Web Vitals targets, profiling workflows, bundle analysis, anti-pattern detection | Performance requirements exist or you suspect regressions |
Ship - Deploy with confidence
| Skill | What It Does | Use When |
|---|---|---|
| git-workflow-and-versioning | Trunk-based development, atomic commits, change sizing (~100 lines), the commit-as-save-point pattern | Making any code change (always) |
| ci-cd-and-automation | Shift Left, Faster is Safer, feature flags, quality gate pipelines, failure feedback loops | Setting up or modifying build and deploy pipelines |
| deprecation-and-migration | Code-as-liability mindset, compulsory vs advisory deprecation, migration patterns, zombie code removal | Removing old systems, migrating users, or sunsetting features |
| documentation-and-adrs | Architecture Decision Records, API docs, inline documentation standards - document the why | Making architectural decisions, changing APIs, or shipping features |
| observability-and-instrumentation | Structured logging, RED metrics, OpenTelemetry tracing, symptom-based alerting - instrument as you build | Adding telemetry, or shipping anything that runs in production |
| shipping-and-launch | Pre-launch checklists, feature flag lifecycle, staged rollouts, rollback procedures, monitoring setup | Preparing to deploy to production |
Agent Personas
12 specialist personas — each adopts a single engineering role and operates within a curated skill scope.
Quality & Review Personas
| Agent | Role | Best for |
|---|---|---|
| code-reviewer | Senior Staff Engineer | Five-axis code review before merge |
| security-auditor | Security Engineer | Vulnerability detection, OWASP assessment |
| test-engineer | QA Specialist | Test strategy, coverage analysis, Prove-It pattern |
| web-performance-auditor | Web Performance Engineer | Core Web Vitals audit; run via /webperf |
| senior-qa-engineer | Senior QA Engineer | Feature verification, fix validation, regression checks |
Engineering Domain Personas
| Agent | Role | Best for |
|---|---|---|
| api-developer | Senior API Engineer | REST/GraphQL design, OpenAPI spec-first, auth, error contracts |
| db-architect | Senior Database Architect | Schema design, indexing, migrations, query optimisation |
| senior-devops | Senior DevOps Engineer | CI/CD pipelines, IaC, containerisation, GitOps |
| senior-frontend-engineer | Senior Frontend Engineer | React/TS components, WCAG accessibility, Core Web Vitals |
| senior-cloud-architect | Senior Cloud Architect | Multi-region design, IAM, HA/DR, cost optimisation |
| senior-backend-engineer | Senior Backend Engineer | Service architecture, async patterns, message queues, caching |
| ai-ml-engineer | AI/ML Engineer | Prompt engineering, RAG, LLM evaluation, AI safety |
See docs/agents.md for the decision matrix, orchestration rules, and how personas compose with skills and slash commands.
Reference Checklists
Quick-reference material that skills pull in when needed:
| Reference | Covers |
|---|---|
| testing-patterns.md | Test structure, naming, mocking, React/API/E2E examples, anti-patterns |
| security-checklist.md | Pre-commit checks, auth, input validation, headers, CORS, OWASP Top 10 |
| performance-checklist.md | Core Web Vitals targets, frontend/backend checklists, measurement commands |
| accessibility-checklist.md | Keyboard nav, screen readers, visual design, ARIA, testing tools |
| orchestration-patterns.md | Endorsed and anti-pattern agent orchestration — who's allowed to invoke whom |
How Skills Work
Every skill follows a consistent anatomy:
┌─────────────────────────────────────────────────┐
│ SKILL.md │
│ │
│ ┌─ Frontmatter ─────────────────────────────┐ │
│ │ name: lowercase-hyphen-name │ │
│ │ description: Guides agents through [task].│ │
│ │ Use when… │ │
│ └───────────────────────────────────────────┘ │
│ Overview → What this skill does │
│ When to Use → Triggering conditions │
│ Process → Step-by-step workflow │
│ Rationalizations → Excuses + rebuttals │
│ Red Flags → Signs something's wrong │
│ Verification → Evidence requirements │
└─────────────────────────────────────────────────┘
Key design choices:
- Process, not prose. Skills are workflows agents follow, not reference docs they read. Each has steps, checkpoints, and exit criteria.
- Anti-rationalization. Every skill includes a table of common excuses agents use to skip steps (e.g., "I'll add tests later") with documented counter-arguments.
- Verification is non-negotiable. Every skill ends with evidence requirements - tests passing, build output, runtime data. "Seems right" is never sufficient.
- Progressive disclosure. The
SKILL.mdis the entry point. Supporting references load only when needed, keeping token usage minimal.
How It Works: End-to-End Workflow
Agent Harness uses a three-layer architecture. Understanding the layers helps you get the most out of it.
┌─────────────────────────────────────────────────────────────────┐
│ Layer 1 — Commands (the WHEN) │
│ /spec /plan /build /test /review /code-simplify /ship │
│ User-facing entry points. Each command knows which agent and │
│ skill(s) to activate for a given phase of the lifecycle. │
└──────────────────────────┬──────────────────────────────────────┘
│ invokes
┌──────────────────────────▼──────────────────────────────────────┐
│ Layer 2 — Agent Personas (the WHO) │
│ api-developer / senior-backend-engineer / code-reviewer │
│ Each persona adopts a single engineering role and perspective. │
│ It holds a curated scope of skills for its domain. │
└──────────────────────────┬──────────────────────────────────────┘
│ invokes
┌──────────────────────────▼──────────────────────────────────────┐
│ Layer 3 — Skills (the HOW) │
│ spec-driven-development / test-driven-development / etc. │
│ Step-by-step workflows with checkpoints, exit criteria, and │
│ anti-rationalization guards. The process knowledge lives here. │
└─────────────────────────────────────────────────────────────────┘
Step-by-step: Building an API Feature
Here is how responsibilities flow from layer to layer when you build a new API endpoint:
Step 1 — Define the spec
User: /spec "add a user authentication endpoint"
→ /spec command activates the spec-driven-development skill
→ Skill produces SPEC.md covering: objective, endpoint contract, auth scheme, error codes, test strategy
Step 2 — Plan the tasks
User: /plan
→ /plan command activates planning-and-task-breakdown skill
→ Skill decomposes the spec into atomic, verifiable tasks with acceptance criteria
→ Produces tasks/plan.md + tasks/todo.md
Step 3 — Build incrementally
User: /build
→ /build command activates the api-developer agent persona
→ api-developer consults its skill scope, invokes test-driven-development first (write failing tests)
→ Then invokes incremental-implementation (implement one slice at a time)
→ Each task: RED → GREEN → commit → mark done
Step 4 — Review from multiple perspectives
User: /review
→ /review activates code-reviewer persona
→ code-reviewer applies the code-review-and-quality skill
→ Five-axis assessment: correctness · readability · architecture · security · performance
Step 5 — Ship with confidence
User: /ship
→ /ship fans out THREE personas in parallel:
code-reviewer→ code quality reportsecurity-auditor→ vulnerability audit (appliessecurity-and-hardeningskill)test-engineer→ coverage report
→ Main agent merges all reports → single go/no-go decision with rollback plan
Responsibility Summary
| What you type | Who picks it up | What they do |
|---|---|---|
/spec |
spec-driven-development skill |
Writes the spec before any code |
/plan |
planning-and-task-breakdown skill |
Decomposes spec into tasks |
/build |
api-developer or senior-backend-engineer persona |
Invokes TDD + incremental-implementation skills |
/review |
code-reviewer persona |
Five-axis review via code-review-and-quality skill |
/ship |
Three personas in parallel | Each applies its domain skill; main agent synthesises |
Which persona for which work?
| Work type | Persona to invoke |
|---|---|
| REST or GraphQL endpoint | api-developer |
| Database schema or migration | db-architect |
| CI/CD pipeline or Dockerfile | senior-devops |
| React component or accessibility | senior-frontend-engineer |
| Cloud architecture or IaC | senior-cloud-architect |
| Backend service or async job | senior-backend-engineer |
| LLM integration or RAG system | ai-ml-engineer |
| Pre-merge code review | code-reviewer |
| Security audit | security-auditor |
| Test coverage analysis | test-engineer |
| Web performance audit | web-performance-auditor |
| Feature verification or fix validation | senior-qa-engineer |
Intent → Skill routing
How agents get involved differs by platform. In Claude Code, only skills fire automatically from your words — agents never activate unless you name one explicitly (e.g. "use the api-developer agent") or run a slash command. In OpenCode / Cursor / Copilot, the agent column below applies — the platform routes your intent to the agent first, which then invokes the skill.
Domain intents:
| If you say... | Skill(s) invoked (Claude Code) | Agent auto-invoked (OpenCode / Cursor) |
|---|---|---|
| API, endpoint, REST, GraphQL, JWT, OAuth, webhook | api-and-interface-design, spec-driven-development |
api-developer |
| database, schema, migration, SQL, query, index, ORM | database-design, database-migration |
db-architect |
| Docker, Kubernetes, CI/CD, pipeline, deploy, IaC | ci-cd-and-automation, git-workflow-and-versioning |
senior-devops |
| component, React, CSS, accessibility, WCAG, bundle | frontend-ui-engineering, react-best-practices |
senior-frontend-engineer |
| cloud, AWS, Azure, GCP, IAM, multi-region, serverless | cloud-architect, documentation-and-adrs |
senior-cloud-architect |
| backend, microservice, async, Kafka, cache, Redis | backend-architect, api-and-interface-design |
senior-backend-engineer |
| AI, LLM, prompt, RAG, vector, embedding, hallucination | spec-driven-development, llm-app-patterns |
ai-ml-engineer |
| review, check my code, feedback, before merge, PR | code-review-and-quality |
code-reviewer |
| security, vulnerability, XSS, OWASP, harden, CVE | security-and-hardening |
security-auditor |
| test, coverage, unit test, E2E, Jest, Playwright, mock | test-driven-development |
test-engineer |
| verify, QA, does this work, confirm the fix, smoke test | quality-assurance |
senior-qa-engineer |
| slow, LCP, INP, CLS, Core Web Vitals, Lighthouse | performance-optimization |
web-performance-auditor |
Cross-cutting intents (skill only on both platforms — no agent):
| If you say... | Skill(s) invoked |
|---|---|
| build, implement, add, create, new feature | spec-driven-development → domain agent → incremental-implementation → test-driven-development |
| plan this, how should I approach, break this down | writing-plans |
| plan, break down, tasks, roadmap, where do I start | planning-and-task-breakdown |
| execute the plan, follow the plan, implement the plan | executing-plans |
| bug, broken, not working, crash, something is wrong, root cause | systematic-debugging |
| simplify, clean up, reduce complexity, hard to read | code-simplification |
| brainstorm, ideas for, what are the options, explore approaches | brainstorming |
| someone reviewed my code, here are review comments, address these comments | receiving-code-review |
| request a review, ready for review, PR is ready | requesting-code-review |
| I'm done, implementation complete, ready to merge, all tests pass | finishing-a-development-branch |
| it works, looks good, should be fixed, I think it's done | verification-before-completion |
Project Structure
agent-harness/
├── skills/ # 24 core lifecycle skills + curated specialist skills (173 total)
│ ├── interview-me/ # Define
│ ├── idea-refine/ # Define
│ ├── spec-driven-development/ # Define
│ ├── planning-and-task-breakdown/ # Plan
│ ├── incremental-implementation/ # Build
│ ├── context-engineering/ # Build
│ ├── source-driven-development/ # Build
│ ├── doubt-driven-development/ # Build
│ ├── frontend-ui-engineering/ # Build
│ ├── test-driven-development/ # Build
│ ├── api-and-interface-design/ # Build
│ ├── browser-testing-with-devtools/ # Verify
│ ├── debugging-and-error-recovery/ # Verify
│ ├── code-review-and-quality/ # Review
│ ├── code-simplification/ # Review
│ ├── security-and-hardening/ # Review
│ ├── performance-optimization/ # Review
│ ├── git-workflow-and-versioning/ # Ship
│ ├── ci-cd-and-automation/ # Ship
│ ├── deprecation-and-migration/ # Ship
│ ├── documentation-and-adrs/ # Ship
│ ├── observability-and-instrumentation/ # Ship
│ ├── shipping-and-launch/ # Ship
│ └── using-agent-harness/ # Meta
├── agents/ # 12 specialist personas
│ ├── code-reviewer.md # Quality & review
│ ├── security-auditor.md # Quality & review
│ ├── test-engineer.md # Quality & review
│ ├── web-performance-auditor.md # Quality & review
│ ├── senior-qa-engineer.md # Quality & review
│ ├── api-developer.md # Engineering domain
│ ├── db-architect.md # Engineering domain
│ ├── senior-devops.md # Engineering domain
│ ├── senior-frontend-engineer.md # Engineering domain
│ ├── senior-cloud-architect.md # Engineering domain
│ ├── senior-backend-engineer.md # Engineering domain
│ └── ai-ml-engineer.md # Engineering domain
├── references/ # 5 supplementary checklists
├── hooks/ # Session lifecycle hooks
├── .claude/commands/ # 8 slash commands (Claude Code)
├── .gemini/commands/ # Slash commands (Gemini CLI)
├── commands/ # Slash commands (Antigravity CLI)
├── plugin.json # Plugin manifest
└── docs/ # Setup guides per tool
Why Agent Harness?
AI coding agents default to the shortest path - which often means skipping specs, tests, security reviews, and the practices that make software reliable. Agent Harness gives agents structured workflows that enforce the same discipline senior engineers bring to production code.
Each skill encodes hard-won engineering judgment: when to write a spec, what to test, how to review, and when to ship. These aren't generic prompts - they're the kind of opinionated, process-driven workflows that separate production-quality work from prototype-quality work.
Skills bake in best practices from Google's engineering culture — including concepts from Software Engineering at Google and Google's engineering practices guide. You'll find Hyrum's Law in API design, the Beyonce Rule and test pyramid in testing, change sizing and review speed norms in code review, Chesterton's Fence in simplification, trunk-based development in git workflow, Shift Left and feature flags in CI/CD, and a dedicated deprecation skill treating code as a liability. These aren't abstract principles — they're embedded directly into the step-by-step workflows agents follow.
Contributing
Skills should be specific (actionable steps, not vague advice), verifiable (clear exit criteria with evidence requirements), battle-tested (based on real workflows), and minimal (only what's needed to guide the agent).
See docs/skill-anatomy.md for the format specification and CONTRIBUTING.md for guidelines.
License
MIT - use these skills in your projects, teams, and tools.
No comments yet
Be the first to share your take.