功能描述

Agent engineering harness for any repo. Creates a short AGENTS.md table-of-contents, structured docs/ knowledge base (ARCHITECTURE, QUALITY, CONVENTIONS, COO...

使用说明 (SKILL.md)

harness — Agent Engineering Harness

Name: Agent Harness
Author: bowen31337

Implements the OpenAI Codex team's agent-first engineering harness pattern for any repo: short AGENTS.md TOC, structured docs/, custom linters with agent-readable errors, CI enforcement, execution plan templates, doc-gardening.

Validated against: Agent Tool Design Guidelines (2026-03-09)

When to use

Setting up a new repo for agent-first development
Upgrading an existing repo's AGENTS.md to table-of-contents style
Adding architectural lint enforcement to a repo
Any repo where agents are doing most of the coding

Supported Languages

Rust (Substrate pallets, cargo workspace)
Go (internal/ package structure)
TypeScript (src/, npm)
Python (pyproject.toml, uv/pytest) ← added 2026-03-09

Usage

SKILL_DIR="$HOME/.openclaw/workspace/skills/harness"

# Scaffold harness for a repo (language auto-detected: Rust/Go/TypeScript/Python)
uv run python "$SKILL_DIR/scripts/scaffold.py" --repo /path/to/repo

# Scaffold with force-overwrite of existing AGENTS.md
uv run python "$SKILL_DIR/scripts/scaffold.py" --repo /path/to/repo --force

# Audit harness freshness (tool lifecycle check — no writes)
uv run python "$SKILL_DIR/scripts/scaffold.py" --repo /path/to/repo --audit

# Run lints locally
bash /path/to/repo/scripts/agent-lint.sh

# Check doc freshness (finds stale references in docs/)
uv run python "$SKILL_DIR/scripts/doc_garden.py" --repo /path/to/repo --dry-run

# Check doc freshness and open a fix PR
uv run python "$SKILL_DIR/scripts/doc_garden.py" --repo /path/to/repo --pr

# Generate execution plan for a complex task
uv run python "$SKILL_DIR/scripts/plan.py" \
  --task "Add IBC timeout handling" \
  --repo /path/to/repo

What gets created

File	Description
`AGENTS.md`	~100 line TOC with L1/L2/L3 progressive disclosure markers
`docs/ARCHITECTURE.md`	Layer diagram + dependency rules (auto-generated from repo structure)
`docs/QUALITY.md`	Coverage targets + security invariants
`docs/CONVENTIONS.md`	Naming rules (language-specific)
`docs/COORDINATION.md`	Multi-agent task ownership + conflict resolution rules
`docs/RESILIENCE.md`	Agent recovery protocols, 7-point checklist, VBR standards ← from agent-motivator
`docs/EXECUTION_PLAN_TEMPLATE.md`	Structured plan format for complex tasks
`scripts/agent-lint.sh`	Custom linter with agent-readable errors (WHAT / FIX / REF)
`.github/workflows/agent-lint.yml`	CI gate on every PR

Lint error format

Every lint error produced by scripts/agent-lint.sh follows this format:

LINT ERROR [\x3Crule-id>]: \x3Cdescription of the problem>
  WHAT: \x3Cwhy this is a problem>
  FIX:  \x3Cexact steps to resolve it>
  REF:  \x3Cwhich doc to consult>

This means agents can read lint output and fix problems without asking a human.

Agent Design Checklist (from tool design guidelines)

Before shipping any tool or skill change, verify:

Is the tool shaped to what this model can actually do?
Does it schema-enforce structured output where correctness matters?
Is context loaded progressively (L1→L2→L3), not dumped upfront?
Does it support multi-agent coordination if needed? (see COORDINATION.md)
Have you measured model affinity (call frequency) vs just output quality?
Is the total tool count at or below your ceiling? (target: ≤ 20 per agent)
Do you have a plan to revisit this tool as model capabilities change?

Progressive Disclosure Layers

The harness enforces a 3-layer context discipline:

Layer	Where	When to load
L1	`AGENTS.md`	Always — orientation, commands, invariants
L2	`docs/`	Before coding — architecture, quality, conventions
L3	Source files	On demand — grep/read specific files as needed

Rule: Start with L1. Pull L2 before touching code. Pull L3 only when you need it. Never pre-load all three layers — it crowds out working context.

Tool Lifecycle (--audit)

Run --audit quarterly to check harness freshness:

AGENTS.md has depth layer markers
COORDINATION.md present (multi-agent support)
Lint script uses current language tooling
Python: ruff + pyright checks present
AGENTS.md under 150 lines

Safety

Never overwrites existing AGENTS.md without --force flag
Reads existing code structure before generating docs (no hallucinated APIs)
All writes are previewed in --dry-run mode before committing

References

安全使用建议

This skill mostly does what it says (scaffolding docs, generating lint scripts, checking docs and creating execution plans). Before installing or running it, review and consider the following: - These scripts call standard developer tools (git, grep, bash, gh CLI, and language-specific tools like cargo/go/npm/uv). The skill metadata lists no required binaries — make sure those tools are present and acceptable for your environment. - doc_garden.py can create branches, commit a docs/STALE_REFS.md, push to origin, and open GitHub PRs. Run it first with --dry-run (or avoid --pr) to see what it would change. - doc_garden.py contains a hard-coded commit author (Alex Chen) and forces git pushes using GIT_SSH_COMMAND pointing to '~/.ssh/id_ed25519_alexchen'. That is unexpected: it may fail on your machine, or (if that key exists) cause pushes using that key/identity. Remove or modify these hard-coded values to use your own git identity and auth flow (or rely on the existing git/gh auth) before allowing automatic pushes. - If you intend to let the tool open PRs automatically, ensure your GH CLI and git credentials are configured, and consider auditing the exact commit/branch behavior (branch names, commit messages) so that automated commits don't obscure authorship. - If you want higher assurance, run the scripts in a disposable clone or invoke only the read-only modes (dry-run / output-only) until you are comfortable with generated content and CI changes. If you want, I can point out the exact lines to change to remove the hard-coded GIT_SSH_COMMAND and commit identity or produce a safer variant that asks before pushing.

功能分析

Type: OpenClaw Skill Name: harness Version: 2.0.0 The skill bundle contains a script, `scripts/doc_garden.py`, which hardcodes a specific git user identity ('Alex Chen') and attempts to use a hardcoded private SSH key path (`~/.ssh/id_ed25519_alexchen`) for git operations. While this does not appear to exfiltrate the key, hardcoding specific identities and local file paths is a high-risk practice. Additionally, the `SKILL.md` and the generated `docs/RESILIENCE.md` include 'agent-motivator' instructions that explicitly direct the AI agent to act autonomously without seeking permission ('No-Permission Rule') and to be highly persistent, which increases the risk of unauthorized or harmful modifications to a repository.

能力评估

⚠ Purpose & Capability

Name/description promise: scaffold docs, linters, CI, and audit. The included scripts implement those features. However the SKILL metadata claims no required binaries or env vars while the scripts clearly rely on standard developer tools (git, grep, gh CLI, bash, possibly cargo/go/npm/uv for lint/test commands). The omission of those runtime requirements is an incoherence: the skill will fail or behave unpredictably if those binaries are absent.

ℹ Instruction Scope

The SKILL.md instructs running scaffold.py, doc_garden.py, and plan.py which inspect repo structure and create files. That matches the stated purpose. doc_garden.py can open fix PRs (writes docs/STALE_REFS.md, creates a git branch, commits and pushes, and calls 'gh pr create'). These write-and-push actions are within the harness purpose but are sensitive operations (create branches/commits/pushes to remotes). There is no unexpected data exfiltration, but the scripts will act on the user's repo and remote without further confirmation if invoked with flags that allow writes (e.g., --pr).

✓ Install Mechanism

No install spec (instruction-only with code files). That is lower risk than arbitrary downloads. The files are plain Python scripts and generated shell scripts; nothing is fetched from remote during install. This is coherent with the skill being instruction+scripts only.

⚠ Credentials

The skill declares no required environment variables, but doc_garden.py pushes via git and uses the 'gh' CLI and SSH for push. Notably, open_fix_pr sets GIT_SSH_COMMAND to 'ssh -i ~/.ssh/id_ed25519_alexchen' and commits with user.name/user.email hard-coded to 'Alex Chen <[email protected]>'. These are unexpected and disproportionate: they assume a specific SSH key path and identity that are unrelated to most users' repos. The scripts implicitly require access to the user's git credentials, SSH keys, and GH CLI authentication, which is not documented in the metadata.

✓ Persistence & Privilege

The skill is not always:true and is user-invocable; it does not request persistent privileges in the registry metadata. The scripts create files/branches in the repository and may push/open PRs when run with write flags, which is expected behavior for a scaffolding/audit tool. There is no evidence the skill attempts to modify agent/system-wide settings beyond operating on the target repo.

版本历史

v2.0.0

Integrate agent-motivator: scaffold now generates docs/RESILIENCE.md with 7-point recovery checklist, L1-L4 activation levels, VBR standards, failure pattern library, and sub-agent priming block. Audit mode checks for RESILIENCE.md presence.

v1.1.0

Python support, progressive disclosure (L1/L2/L3), COORDINATION.md generator, --audit flag, Agent Design Checklist

元数据

Slug harness

版本 2.0.0

许可证 MIT-0

累计安装 3

当前安装数 3

历史版本数 2

常见问题

Agent Harness 是什么？

Agent engineering harness for any repo. Creates a short AGENTS.md table-of-contents, structured docs/ knowledge base (ARCHITECTURE, QUALITY, CONVENTIONS, COO... 它是一个面向 Claude Code / OpenClaw 的 AI Agent Skill 插件，目前累计下载 469 次。

如何安装 Agent Harness？

在 OpenClaw 或 Claude Code 对话框中运行命令「/install harness」即可一键安装，无需额外配置。

Agent Harness 是免费的吗？

是的，Agent Harness 完全免费，采用 MIT-0 许可证，可自由下载、安装和使用。

Agent Harness 支持哪些平台？

Agent Harness 跨平台运行，可在任意部署了 OpenClaw / Claude Code 的环境中使用（cross-platform）。

谁开发了 Agent Harness？

由 bowen31337（@bowen31337）开发并维护，当前版本 v2.0.0。

Agent Harness