convez.ai
SkillAutomaçãoAvançado
ClydeShen

Harness Engineering Skills

ClydeShen/harness-skill

Framework operacional para agentes confiáveis em workflows de engenharia complexos

Ver no GitHub
InicialPluginScore · de 0 a 100

Conjunto de 10 skills Claude para fluxos de engenharia estruturados, focando em disciplina de sessão, auditoria de harness, governança de fases e pipeline de issues. Resolve problemas de agentes de longa duração através de máquinas de estado, rastreamento de contexto e padrões anti-falha documentados.

Instalação

$npx convez-ai ClydeShen/harness-skill

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Manter contexto e intenção entre múltiplas sessões de agente
  • Prevenir padrões de falha como 'Fuzzy Done' e conclusões prematuras
  • Estruturar fluxos compostos de develop-plan-execute-verify com rastreamento de estado
  • Auditoria e governança de harness para agentes long-running

Veredito

Framework maduro e bem documentado que endereça problemas reais de agentes long-running através de padrões operacionais comprovados. Recomendado para times que precisam de agentes confiáveis em produção, com boa integração com GSD Redux e agentmemory.

README

A tradução para o português deste README ainda está na fila.

Harness Engineering Skills

skills.sh License: MIT Version GitHub last commit

Agent skills for compound engineering workflows — structured sessions, context handover, issue lifecycle, and harness health.

Q&A — Practitioner Questions — deep-dive answers on memory systems, session lifecycle, GitHub Project rationale, anti-patterns, and evals.


Quickstart

Full collection (recommended)

npx skills@latest add ClydeShen/harness-skill

Pick the skills you want and which coding agents to install them on. Then run /setup-harness-skills in your agent to initialise .harness/state.json, create GitHub labels, and configure your instruction file.

Recommended companion collections

CollectionAdds
GSD Reduxgsd-* skills: full discuss → plan → execute → verify phase lifecycle
Superpowersbrainstorming, systematic-debugging, writing-plans, subagent-driven-development
agentmemoryPersistent memory across sessions — recommended memory system. Stop hook auto-generates session summaries; session-start reads past decisions on resume.
roam-codeCodebase intelligence via MCP — session-start calls roam_retrieve to inject architecture snapshot into the session briefing.

Why this framework exists

Anthropic's engineering team identified a hard ceiling on what long-running agents can reliably do without external scaffolding. In Effective Harnesses for Long-Running Agents (2025), they describe two failure modes that appear even with frontier models:

  • One-shot overreach — the agent attempts to build everything at once, runs out of context mid-implementation, and the next session inherits a half-finished codebase with no record of intent.
  • Premature done declaration — the agent sees partial progress and concludes the task is complete. No one catches it until a user or CI run reveals the gaps.

These are harness problems, not model capability problems. This framework is the operational layer that article describes, packaged as installable skills so you do not have to build it from scratch.


What you get

  • Named anti-patterns — Fuzzy Done, Proxy Signal, Confidence Exit, Planning=Done. When an agent fails, you can say which pattern it hit. (anti-patterns.md)
  • A session state machine — .harness/state.json tracks phase, status, and active task as machine-readable JSON. Every session starts with a briefing; every session ends with a handoff. An interrupted session leaves a detectable fingerprint.
  • Four-layer recoverable state — Intent (state.json + CLAUDE.md) → Position (.continue-here.json + GitHub issue) → Evidence (git log + issue comments) → Memory (agentmemory / mem0 / MEMORY.md). Any interruption is recoverable without human intervention.
  • Glue between issue tracker, agent, and memory — skills read from and write to GitHub Issues, .harness/, and the memory system as a coordinated unit.
  • A behavioral baseline — CLAUDE.md derived from Karpathy's observations on LLM coding pitfalls plus a fifth section (Harness Discipline) that enforces session boundary discipline.

Built on mattpocock/skills

Use mattpocock/skills alone if:

  • Your agent work fits in one context window
  • You do not need cross-session state recovery or structured handoffs

Use this collection if:

  • Agent tasks run across multiple context windows or days
  • You need verifiable session boundaries and interrupted-session recovery
  • You want named anti-patterns and continuous harness governance
  • You are coordinating agent work with a GitHub issue tracker

Five skills in this collection have no equivalent in mattpocock — they are the harness layer the Anthropic article describes but does not supply as ready-to-use tools:

SkillWhat it adds
/harness-auditScans for harness gaps, outputs prioritised list with paste-ready snippets. Never writes files. Stop hook is always gap #1.
/harness-guideContinuous coaching loop: inspect → classify → recommend one next step → repeat. Detects anti-patterns by name.
/session-startReads .harness/state.json and .continue-here.json. Outputs structured briefing or recovery brief when an interrupted session is detected.
/context-handoverSession boundary manager: writes .continue-here.json, updates .harness/state.json, posts GitHub progress comment, updates memory system (skips if Stop hook already handles it automatically).
/skill-cleanupAudits installed skills across all agent platforms for stale or duplicate entries. Interactive, dry-run mode, never deletes without confirmation.
/fullerComprehensive reasoning partner — maps whole systems before examining parts, finds the trim tab (smallest intervention with largest leverage), interrogates assumptions through Socratic one-question-at-a-time dialogue. Internal finding log accessible on request.
/harness-verify-before-moveComprehensive pre-phase-transition sweep: verifies exit criteria, syncs code (git/lint/build/tests), cleans design docs and implementation-notes, prunes stale documents and memory, syncs GitHub (milestones, issues, labels, board), updates README, writes memory snapshot, outputs a clean project snapshot.

GitHub as the agent's operating system

No external project management tool required. The framework uses GitHub Issues and GitHub Project Kanban natively — the same APIs available to every repo — as the agent's task queue and state machine.

GitHub Kanban board

A GitHub Action (sync-status.yml) keeps the board in sync automatically — no webhooks, no third-party service, no extra dependencies:

  • A status:* label applied to any issue → board column updates instantly
  • PR opened against an issue → issue moves to In Progress
  • PR merged → linked issue closes and moves to Done

The agent reads status:ready-for-agent issues to know what to work on next. When it finishes, it applies status:done. The board reflects live project state without any manual moves.

ColumnWho moves itMeaning
TriageAgentNew issue, needs classification
Needs PRDAgentStory not writable yet — requirements missing
Needs ReviewAgentHuman must validate before agent starts (HITL)
Ready for AgentHuman or AgentAgent confident — can start autonomously (AFK)
In ProgressGitHub ActionPR opened against this issue
DoneGitHub ActionPR merged

Context window discipline

Compound engineering works like compound interest: each session should make subsequent sessions more effective, not harder. (Compound Engineering with AI) The mechanism that enables this is context window discipline — keeping each session clean, bounded, and explicitly handed off.

A Claude Code session opens with 1 million tokens. Task size is measured in context windows, not hours or days. When sessions overflow, bleed into each other through /compact, or take on tasks too large to hand off cleanly, the compounding effect degrades: context pollution accumulates, drift builds across transfers, and the original intent becomes unrecoverable. (Effective Context Engineering for AI Agents)

flowchart LR
    A([New session]) --> B["Active work<br/>0% to 70%"]
    B --> C{">= 70% used?"}
    C -->|no| B
    C -->|yes - trigger| D["/context-handover<br/>writes .continue-here.json<br/>updates state.json + GitHub"]
    D --> E([New session<br/>resume with /session-start])
    E --> B

    C -. "avoid: auto-compact" .-> F["/compact<br/>unknown state retained"]
    F --> G["Degraded session<br/>compound effect lost"]

Effort estimate (unit: context windows)

Every GitHub issue carries an Effort field — the number of context windows estimated to complete it:

  • 1 = fits in one session
Effort = 3 CW example:

CW 1  [████████████████████████████░░░░░░░]  → /context-handover
CW 2  [████████████████████████████░░░░░░░]  → /context-handover
CW 3  [████████████░░░░░░░░░░░░░░░░░░░░░░░]  → done ✓
       ←── active work (70%) ──→ ←─ buffer ─→
  • Maximum: 8 context windows. Any issue estimated above this must be split into smaller tasks before the agent starts. Beyond 8, handoff drift compounds: each session-to-session transfer carries a small loss of precision, and enough transfers make the original intent unrecoverable. (Effective Harnesses for Long-Running Agents)

The /harness-issues skill enforces this ceiling at creation time. An issue scoped above 8 CW cannot be created — the agent must break it down first.

Session boundary: trigger at 70%, not later

  0%                                         70%            100%
  [████████████████████████████████████████░░░░░░░░░░░░░░░░░░░]
   ←─────────────── active work ────────────→ ←── buffer ────→

The agent monitors token usage after every tool call. At the system-configured threshold (≥70% of the context window):

  1. Run /context-handover — writes .continue-here.json, updates .harness/state.json, posts a GitHub progress comment
  2. Close the current Claude Code session
  3. Open a new Claude Code session
  4. Run /session-start — reads the handoff artifact and resumes exactly at <next_action>

The remaining 30% is the buffer for executing the handover itself. Triggering late leaves insufficient budget for a clean handoff. (Effective Context Engineering for AI Agents)

Do not let the agent auto-run /compact

/compact compresses conversation history, but neither you nor the agent knows exactly what was retained. Critical context — constraints established earlier in the session, in-progress decisions, partial implementation state — can silently disappear. The session continues in a degraded, unverifiable state.

/context-handover + new session is the correct alternative. The handoff artifact (.continue-here.json) is explicit, human-readable, and fully recoverable by any fresh agent with no prior context. Each new session starts with a full 1M token budget and a clean context — the compound effect is preserved, not diluted.


Skill lifecycle

flowchart TD
    A([New project]) --> B

    subgraph ONCE["One-time setup"]
        B["/harness-audit<br/>Detect gaps and snippets"]
        B --> C["/setup-harness-skills<br/>CLAUDE.md + state.json + GitHub labels"]
    end

    C --> D

    subgraph LOOP["Every session"]
        D["/session-start<br/>Briefing or recovery"]
        D --> WORK["Agent does work<br/>phase skills as needed"]
        WORK --> CTX{">= 70% used?"}
        CTX -->|yes| HO["/context-handover<br/>Write .continue-here.json<br/>update state.json + GitHub"]
        HO --> COM["Close and open new session"]
        COM -->|"/session-start"| D
        CTX -->|no| WORK
    end

Run /harness-guide anytime for governance — inspects project state, recommends one next step. Phase skills (discuss / execute / verify) shown in the Use cases section below. Harness design from Anthropic 2025


Use cases

flowchart LR
    subgraph PHASES["Phase skills - invoke by need"]
        DISC["discuss<br/>/grill-with-docs /harness-prd /harness-triage"]
        EXEC["execute<br/>/systematic-debugging /harness-guide"]
        VER["verify<br/>/gsd-verify-work /gsd-code-review<br/>companion: GSD Redux"]
        DISC -.->|or skip| EXEC -.->|or skip| VER
    end

    subgraph GOV["Governance - anytime"]
        G["/harness-guide<br/>inspect and recommend one next step"]
    end

New project — detect gaps and configure once

/harness-audit

Outputs a prioritised gap list with paste-ready snippets. Typical first run:

1. Missing Stop hook         → paste .claude/settings.json snippet
2. No instruction file       → paste CLAUDE.md template
3. No memory system          → install agentmemory or mem0, or create MEMORY.md
4. CI runs build only        → paste .github/workflows/ci.yml snippet

Close gap #1 first. Nothing else matters until the agent cannot declare done without running a verification. Then:

/setup-harness-skills

One-time interactive setup: writes CLAUDE.md, creates GitHub labels, initialises .harness/state.json. Shows a draft before writing anything.

Sustained multi-day feature work

Every session starts with:

/session-start

Output on a clean resume:

Phase: execute
Active task: #12 — Add payment webhook handler
Effort remaining: ~2 context windows
Pick up from: implement idempotency key check in webhook.ts:handleEvent()

Output when the previous session was interrupted without /context-handover:

⚠️ Recovery briefing — interrupted session detected
Last session started: 2026-05-27T14:32:00Z — no handover recorded.

git log since interruption:
  a3f91c2 feat: add webhook signature verification
  (no further commits)

Resume from last commit. Run lint+build before continuing.

At ~70%, follow the session boundary protocol — /context-handover → close → new session → /session-start.

Harness drift — ongoing governance

After weeks of work, CLAUDE.md has grown past 200 lines, the Stop hook was removed during a config refactor, CI no longer runs lint.

/harness-guide

Reads instruction file, .harness/state.json, .harness/config.json, and .claude/settings.json. Classifies every finding into three buckets (✅ aligned / ⚠️ weak / ❌ missing) and recommends exactly one next step. The coaching loop continues after you act on each recommendation.


Sources and attribution

SourceRole in this framework
Effective Harnesses for Long-Running Agents — Anthropic EngineeringCore design: initializer + coding agent + clean-state discipline
Effective Context Engineering for AI Agents — Anthropic EngineeringContext as a finite, depletable resource; compaction strategy; structured note-taking across sessions
Compound Engineering with AI — The Definitive GuideCompound of time: each session makes subsequent sessions more effective; 40/10/40/10 cycle (Plan/Work/Review/Compound)
Andrej Karpathy — LLM coding pitfallsCLAUDE.md behavioral baseline: Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution
mattpocock/skillsharness-triage, harness-prd, harness-issues, write-harness-skill adapted (MIT License); grill-me, handoff, zoom-out, caveman, grill-with-docs used verbatim from that collection — install separately
obra/superpowersCompanion collection: brainstorming, systematic-debugging, writing-plans, subagent-driven-development
open-gsd/get-shit-done-reduxRecommended companion: discuss → plan → execute → verify phase lifecycle
Ver o original no GitHub

Bom para

Relacionados