Skip to main content

​
Best Practices

​
Keep skills atomic

Each skill should do one thing. Resist the temptation to build a large skill that handles many related tasks — prefer composing several small skills at the harness level instead. Instead of: 
skills/
└── content/         # drafts posts, generates images, scans social, emails stakeholders
Prefer: 
skills/
├── create-blog-post/
├── generate-images/
├── scan-social/
└── email-stakeholders/
Atomic skills are easier to test, easier to reuse across harnesses, and easier to update independently. While broad skills can be employed within a harness, smaller and more atomic skills are encouraged.

​
Put cross-skill knowledge in the harness references, not in individual skills

Individual skills may have their own references/ directory for knowledge specific to that skill. The harness also has a top-level references/ directory for knowledge that applies across multiple skills. If a piece of information is relevant to more than one skill, it belongs in the harness-level references/, not inside any individual skill. This avoids duplication and keeps cross-cutting knowledge in one place.

​
Keep HARNESS.md as short as possible

HARNESS.md is loaded into the agent’s context window on every activation. Write the minimum body that lets the agent understand the harness structure and navigate to the right skill or reference. A good body:
  • One short paragraph describing the agent’s role
  • A bulleted list of skills with one-line descriptions
  • A bulleted list of references with one-line descriptions
A bad body:
  • Repeats information already in skill or reference files
  • Explains how skills work
  • Contains lengthy prose that could live in a reference file

​
Use subdirectories for large harnesses

When a harness grows large, group related skills and references into named subdirectories. Adding a SKILLS.md to each skill subdirectory and a REFERENCES.md to each reference subdirectory is optional but strongly encouraged — these summary files exist primarily to support routing, letting the agent decide which group to explore without opening every file. REFERENCES.md is particularly valuable when references vary in type or lack a description field. This structure can be nested arbitrarily. See Organizing Large Harnesses for the full pattern.