Skip to main content
plugin CX Codex

agent-harness-skills — Claude Code and Codex plugin

agent-harness-skills — a plugin for Claude Code and Codex that builds the repository control layer agents need: entry points, boundaries, validation, runtime traces, and delivery records.

MIT ★ 1,596 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install agent-harness-skills@awesome-codex-plugins
Open on GitHub

What agent-harness-skills does

The plugin includes five reusable skills: assess harness maturity, define contracts and architecture boundaries, design validation, trace runtime behavior, and coordinate work state. Each skill provides a repeatable pattern the agent can apply to your repository — from explicit entry points in AGENTS.md through test matrices and run artifacts with error traces.

The harness does not replace your project's architecture decisions or add ceremony. It maps existing checks, scripts, and tracking systems (Jira, GitHub Issues, CI commands), then creates new files only for missing parts. In practice, this means the agent won't rediscover where to run validation, what boundaries separate subsystems, or which logs to include in a delivery record.

What it helps with

  • design agent entry points and signals into an existing repository
  • specify architecture boundaries and validation rules
  • collect error traces, logs, and artifacts into a single proof bundle
  • leave delivery records that are auditable and reusable for follow-up work
  • improve code quality incrementally without requiring a full refactor

Example prompts for the agent

  • Run repo-harness-assessment against your repository to see what harness structures already exist and what to add first.
  • Design validation in validation-harness-design so the agent can pick a check that actually proves a change is safe.
  • Set up runtime evidence in runtime-evidence-and-tracing to connect failures to request IDs, session traces, and artifacts.

How to install agent-harness-skills

Plugin marketplace

/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install agent-harness-skills@awesome-codex-plugins

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about agent-harness-skills

How do I install agent-harness-skills in Claude Code?

Run two commands in Claude Code in order: first /plugin marketplace add hashgraph-online/awesome-codex-plugins, then /plugin install agent-harness-skills@awesome-codex-plugins. The skills will then be available to the assistant.

What does agent-harness-skills do?

The plugin helps agents navigate a repository: where to start, which checks to run, what boundaries to respect, and what logs to leave on delivery. It is not a new system — the plugin connects existing documents, scripts, and CI to a single interface.

Do I have to restructure my repository to use this plugin?

No. The plugin first identifies what you already have — tests, validation scripts, PR templates, issue trackers — and maps their existing roles. It creates new files only for missing parts.

Source text

agent-harness-skills · MIT
# Agent Harness Skills

Reusable skills for turning real software repositories into agent-ready engineering environments.

Agent Harness Skills helps teams build the repo-side control layer that coding agents need: clear entrypoints, explicit boundaries, runnable validation, runtime evidence, and reviewable delivery records.

## Repository

Canonical Git remote:

```bash
[email protected]:yfge/agent-harness-skills.git
```

Use this remote for git-backed installs and for publishing repository updates. A local clone path can still be used anywhere the installation examples accept `<repo-url-or-local-path>`.

## What It Is

Agent Harness Skills is a reusable skill library for designing repository harnesses.

A repository harness is the engineering layer around a codebase that tells an agent where to start, which rules matter, what boundaries it must respect, how to prove a change is safe, and what evidence should be left behind for review. It is not a separate product runtime. It is the control layer that makes an existing repository easier for agents and humans to operate together.

Use it when a project has grown beyond "read the README and run the tests" and needs a more explicit way for agents to navigate source-of-truth documents, validation commands, runtime traces, quality gates, and delivery records.

The guidance is role-based. `AGENTS.md`, `tasks.md`, `agent_chats/`, and `artifacts/runs/` are default artifacts, not mandatory forms. If a repository already has an equivalent issue tracker, review template, validation command, generated report, or runtime artifact system, the skills should map those surfaces first and create defaults only for missing roles.

## Why It Exists

Coding agents can edit files quickly, but real repositories need more than fast edits. They need a stable operating surface.

Without a harness, an agent has to infer too much: which document is authoritative, which directories are owned by which subsystem, which checks are meaningful, whether an observed failure maps to a runtime error, and what evidence belongs in a review or delivery record. That creates drift, repeated rediscovery, weak validation, and delivery summaries that cannot be audited.

Agent Harness Skills turns those expectations into reusable repository practices. The goal is not to add ceremony. The goal is to make the important work discoverable, executable, and reviewable.

## What It Helps Agents Do

- Find the correct entrypoint and source of truth before making changes.
- Understand architecture, ownership, and dependency boundaries.
- Choose the validation surface that actually proves a change.
- Connect observed runtime behavior to logs, traces, request IDs, screenshots, and artifacts.
- Separate code regressions from environment, external dependency, data, or quota blockers.
- Keep task state and acceptance criteria tied to the change that fulfills them.
- Leave concise delivery records through commits, review notes, ledgers, and handoffs.
- Improve quality incrementally without turning every task into a broad refactor.

## Included Skills

The suite deliberately stays small: four core skills plus one optional governance skill.

- `repo-harness-assessment`: assess harness maturity, reconcile agent entrypoints, map existing roles, and identify the smallest useful next slice.
- `repo-contracts-and-boundaries`: turn architecture, schemas, structural quality, baselines, and allowlists into mechanical checks and gradual debt reduction.
- `validation-harness-design`: design repo validation entrypoints, test matrix, JSON/JUnit outputs, and CI gates.
- `runtime-evidence-and-tracing`: design run IDs, request IDs, artifact bundles, runtime traces, and failure evidence.
- `work-state-and-delivery`: optionally coordinate design docs, tracked work, execution plans, delivery records, acceptance criteria, artifacts, and repository commit-coupling policy.

General model knowledge such as ordinary commit execution is not kept as a standalone skill. It belongs in the target repository's entrypoint or contributor policy. A standalone skill must add a stable schema, mechanical procedure, repository context, high-risk guardrail, or measured evaluation benefit.

For version `0.1.x` users, `agent-entrypoint-design` moved into `repo-harness-assessment`, `quality-gardening` moved into `repo-contracts-and-boundaries`, and the design/task, ledger/delivery, and repository commit-policy skills became `work-state-and-delivery`.

Shared methodology support:

- `references/harness-profiles.json`: machine-readable repository archetypes, role mappings, and role-to-skill routing for library, service, monorepo, CLI/tooling, docs-only, and regulated/high-audit repositories.
- `templates/`: neutral starter templates for missing roles such as entrypoints, validation matrices, delivery records, work-state surfaces, runtime evidence summaries, and quality reports.
- `Detected Mapping`: every skill output should name the repository's existing equivalent artifacts before recommending new files.

## When To Use

Use this repository when you want to:

- Prepare a repository for agent-driven engineering work.
- Turn scattered docs, scripts, and conventions into a navigable harness.
- Design `AGENTS.md` and related entrypoints so agents know where to start.
- Add validation gates that are useful locally and reusable in CI.
- Connect observed behavior, runtime signals, external dependency results, and logs into artifact bundles.
- Create durable delivery records for reviews, commits, handoffs, and follow-up work.
- Use `tasks.md` or `docs/tasks.md` as a lightweight repo-local default when there is no reliable Jira, Linear, GitHub Issues, or internal board.

It is especially useful when a repository already has product code, tests, and scripts, but agents still lose time rediscovering rules, guessing boundaries, or reporting work without enough evidence.

## What It Is Not

- It is not a product template or business scaffold.
- It is not a private workflow bundle copied from one team or project.
- It is not a replacement for project-specific architecture decisions.
- It is not only a test harness; tests are one part of the validation surface.
- It is not a platform requirement; a small script or document is often the right first layer.

## Installation

Installation differs by agent runtime. If you use more than one agent, install Agent Harness Skills separately for each one.

Use one of two patterns:

- Packaged install: use the metadata files in this repo when the agent runtime supports plugins or extensions.
- Skills-path install: point the agent runtime directly at this repository's `skills/` directory.

In the examples below, replace `<repo-url-or-local-path>` with this repository's git URL (`[email protected]:yfge/agent-harness-skills.git`) or an absolute local path to the repository root.

### Generic Skills Directory

Use this fallback for any agent runtime that supports an explicit skills path:

```text
<repo-url-or-local-path>/skills
```

Verify by asking the agent to list or load the `repo-harness-assessment` skill.

### Codex CLI And Codex App

This repository includes `.codex-plugin/plugin.json`, which exposes `./skills/` as a Codex plugin.

- For a packaged or marketplace install, install `agent-harness-skills` through the Codex plugin UI or `/plugins` flow once the repository is published in that channel.
- For local development, register this repository through a configured marketplace entry, then install `agent-harness-skills` from that marketplace.
- Keep `.codex-plugin/plugin.json` as the Codex source of truth. It must point `skills` at `./skills/`, omit `apps` and `mcpServers` unless their companion manifests exist, and keep version metadata aligned with the other extension manifests.
- When publishing through a marketplace, update that marketplace entry after the release commit so its source, ref, or sha points at the published revision.
- Validate packaging changes with `python3 scripts/validate_plugin_metadata.py`.
- Verify by asking Codex to use `repo-harness-assessment` on a repository.

### Claude Code

This repository includes `.claude-plugin/plugin.json` for Claude Code plugin packaging.

- Install from the plugin marketplace once published, or use Claude Code's local/plugin-from-repository workflow for this repository.
- Verify by asking Claude Code to load `repo-harness-assessment` or assess a repository's harness maturity.

### Cursor

This repository includes `.cursor-plugin/plugin.json`, with `skills` set to `./skills/`.

- Install from the Cursor plugin marketplace once published, or add this repository through Cursor's plugin flow.
- Verify by asking Cursor to list available skills or load `repo-harness-assessment`.

### Gemini CLI

This repository includes `gemini-extension.json` and `GEMINI.md`.

Install the extension from a git URL or local path:

```bash
gemini extensions install [email protected]:yfge/agent-harness-skills.git
```

Gemini loads `GEMINI.md`, which points it to `INDEX.md` for skill routing. Verify by asking Gemini which Agent Harness Skills are available.

### OpenCode

This repository includes an OpenCode plugin entrypoint at `.opencode/plugins/agent-harness-skills.js`. On startup, the plugin injects a compact bootstrap that points the agent to `INDEX.md`, the native OpenCode skill tool, and this repository's `skills/` directory.

For a local clone, add the repository root to the `plugin` array in your global or project-level `opencode.json`:

```json
{
  "plugin": ["/absolute/path/to/agent-harness-skills"]
}
```

For a git-backed install:

```json
{
  "plugin": ["agent-harness-skills@git+ssh://[email protected]/yfge/agent-harness-skills.git"]
}
```

Restart OpenCode, then verify that the startup bootstrap is present and that skills can be loaded:

```text
use skill tool to list skills
use skill tool to load repo-harness-assessment
```

See `docs/README.opencode.md` for the longer OpenCode guide.

## Usage

Install through the runtime-specific path above, or point your agent runtime at this repository's `skills/` directory.

Use this repository when you want an agent to answer questions like:

- "What harness pieces is this repo missing?"
- "How should this project structure `AGENTS.md` and validation commands?"
- "How do we connect observed behavior to request traces?"
- "Should this requirement live in a work-state surface such as `tasks.md`, a design doc, or an exec plan?"
- "Define how task updates and delivery artifacts should couple to commits in this repository."

## Repository Layout

```text
.codex-plugin/
  plugin.json
.claude-plugin/
  plugin.json
.cursor-plugin/
  plugin.json
.opencode/
  INSTALL.md
  plugins/agent-harness-skills.js
GEMINI.md
gemini-extension.json
skills/
  <skill-name>/SKILL.md
docs/
  model-evaluation.md
  README.opencode.md
  scenario-tests.md
references/
  harness-profiles.json
  harness-patterns.md
scripts/
  check_skill_closure.py
  check_profile_consistency.py
  check_skill_language.py
  check_reference_neutrality.py
  validate_plugin_metadata.py
  validate_skill_quality.py
templates/
  AGENTS.md
  delivery-record.md
  quality-report.md
  runtime-evidence-summary.md
  task-state.md
  validation-matrix.md
```

## Validation

```bash
python3 -m unittest discover -s scripts -p 'test_*.py'
python3 scripts/validate_skill_quality.py
python3 scripts/check_skill_language.py
python3 scripts/check_skill_closure.py
python3 scripts/check_reference_neutrality.py
python3 scripts/check_profile_consistency.py
python3 scripts/validate_plugin_metadata.py
node --check .opencode/plugins/agent-harness-skills.js
```

For substantial skill wording changes, record at least one realistic prompt and observed output in `docs/scenario-tests.md`.

## License

MIT License. See `LICENSE`.

© Agent Harness Skills contributors · MIT · hashgraph-online/awesome-codex-plugins

Similar plugins

All plugins for Agent setup: memory, context, orchestration →
debug-my-harness zernie debug-my-harness reads the local .vigiles/runs.jsonl ledger to explain why an agent harness misbehaved. Use it when a skill stopped firing, a hook let something through, or a subagent broke its tool contract. CX Codex +1 1,500installs om-setup-agent-harness open-mercato The om-setup-agent-harness Claude Code skill configures or diagnoses a multi-model agent harness. It activates when asked to pick worker and reviewer models or check the harness configuration. CX Codex +1 503installs harness-eval Tech Leads Club - github.com/tech-leads-club harness-eval audits repository instructions and skills for broken paths, repeated guidance, and practical value. Use it to review an agent harness before making changes. CX Codex +1 ★ 7,191repo stars agent-harness Alireza Rezvani agent-harness — a Claude Code plugin that turns any skills domain folder into a bounded agentic loop with a hard close gate. The cycle runs execute → verify → close and blocks completion until every task is verified or explicitly waived. ★ 30,251repo stars harness-designing-plugin BilLogic harness-designing-plugin — a Claude Code plugin that pulls scattered team AI artifacts — Figma comments, Notion prompts, AGENTS.md rules, chat histories — into a five-layer design harness versioned in your repo. ★ 5repo stars harness-spec-anatomy hedera-dev harness-spec-anatomy — a skill for Claude Code, Codex, Cursor and other agents that holds the shared vocabulary for hedera-harness v3 recipes — files, defaults, stages, and the blind/evaluate-checklist rule. CX Codex +1 592installs

From the same set391

The whole set →
codiris-agentizer The codiris-agentizer plugin turns a website into a Next.js agent interface with chat, voice calls, and interactive products. Use it to generate and deploy the project. CX Codex ★ 1,596repo stars agentic-readiness-assessment The agentic-readiness-assessment plugin for Claude Code and Codex checks whether an agent can work independently in a repository, then returns a 14-area scorecard and prioritized fixes. CX Codex ★ 1,596repo stars agent-workflow-system agent-workflow-system — a plugin with seven skills that turn vague ideas into step-by-step plans, guide projects from start to handoff, and restore context after closing the window. CX Codex ★ 1,596repo stars agent-retro agent-retro is a plugin for Claude Code and Codex that reviews weekly activity in 12 animated slides with stats and four prompt-coaching tips to inspect your own habits. CX Codex ★ 1,596repo stars agent-guard The agent-guard plugin for Claude Code and Codex intercepts tool inputs and outputs to block secrets. It runs locally by default without telemetry. CX Codex ★ 1,596repo stars agent-deck agent-deck binds MCP services, credentials, and playbooks to a workspace session. Use it when the same working process must carry across Claude Code and Codex. CX Codex ★ 1,596repo stars agency-continuity-audit The agency-continuity-audit plugin for Claude Code and Codex checks persistent agent workspaces, separating evidence of goals, state, and recovery from self-reports. CX Codex ★ 1,596repo stars aegis aegis — a methodology pack bringing planning, TDD, and verification evidence to AI coding agents. Useful when you need safer changes without constant oversight. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open