Optimizing Descriptions
Descriptions are short but load-bearing. They are the primary signal an agent uses during the Discovery phase to decide which directories and files are relevant to a given task. A poor description means content gets ignored or loaded unnecessarily.The description field
EveryHARNESS.md and every routing file has a description field in its frontmatter. Individual markdown files should include one too. Write this field as if you’re answering the question: “When should an agent look here?”
Rules for good descriptions
Be specific about the trigger
A description should make it obvious when this skill, directory, or document applies. Include the input type, the output type, or the situation.Use verbs for actions, nouns for context
Skills and capabilities are actions; reference material is knowledge. This distinction helps agents classify what they’re loading.- Capability: “Generate a social media caption from a product description”
- Context: “Brand voice guidelines and prohibited language list”
Don’t describe implementation details
The description is for relevance matching, not for explaining how something works. Keep implementation detail in the body.Match the vocabulary users will use
Agents compare task descriptions against content descriptions. If your users say “summarize this” and your description says “condense and abridge”, there’s a mismatch. Use the words your users reach for naturally.Descriptions in HARNESS.md body
Inside theHARNESS.md body, you list top-level directories with inline descriptions. These should be even shorter — one clause is ideal — because the agent is scanning a list, not reading a document.