d-kimuson 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.
AGENTS.mdor a compatibility link: references/agents-md.md- An Agent Skill or its directory: references/skills.md
- Claude Code permissions: references/tools/claude-code/permissions.md
- Claude Code hooks: references/tools/claude-code/hooks.md
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.mdandSKILL.mdas runtime context, not maintenance documentation. - Put activation criteria in the
descriptionand human-facing discovery inREADME.md; never restate when to use a skill in theSKILL.mdbody. - 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.