| name | harness-engineering |
| description | Design and maintain vendor-neutral coding-agent harnesses with AGENTS.md and Agent Skills. Use when creating, reviewing, or restructuring repository instructions, AGENTS.md files, Claude Code compatibility links, or skill directories. |
Harness Engineering
Use portable standards as the primary interface:
- Put repository-wide agent context in
AGENTS.md.
- Put reusable domain knowledge and capabilities in Agent Skills.
- Do not introduce vendor-specific command or agent formats unless the user explicitly requires them.
- Isolate unavoidable vendor-specific configuration under
references/tools/<tool>/.
Keep every automatically loaded file small. Retain only information required at that loading stage and defer task-specific details through explicit indexes.
Base every change on explicit user requirements and inspected project sources. Do not invent technologies, commands, files, target locations, or adjacent capabilities to make an example appear complete. When a required fact is unknown, keep an explicit placeholder or request the missing input instead of filling it from convention or path names.
Required references
Read the reference that matches the artifact before editing it. This is mandatory: do not draft vendor syntax or portable file structure from memory.
Load only references whose listed condition matches an artifact that will change. A tool-specific configuration task does not require the AGENTS.md or Agent Skills references unless those portable artifacts will also change. Do not traverse adjacent files for background context.
Design boundaries
- Treat
AGENTS.md and SKILL.md as runtime context, not maintenance documentation.
- Put activation criteria in the
description and human-facing discovery in README.md; never restate when to use a skill in the SKILL.md body.
- Put human-facing maintenance information in
README.md.
- Put details that are not needed for every activation in
references/ and index them with the condition for reading them.
- Turn repeated or sufficiently complex deterministic operations into tested scripts under
scripts/ instead of embedding long command sequences in prose.
- Put opt-in procedural runbooks under
workflows/; keep the core skill focused on reusable knowledge.
- Preserve one canonical source for shared instructions and expose tool-specific filenames through symlinks where possible.
- Change only the requested harness capabilities; do not add unrelated permissions, hooks, workflows, or compatibility files.
