Explore: Add use-when sections to skill descriptions #70

New issue

Closed

opened 2026-07-08 11:54:59 -04:00 by jasper · 0 comments

jasper commented

2026-07-08 11:54:59 -04:00

Contributor

Pocock's skills are organized around diagnosed failure modes — each skill explicitly states the problem it addresses. Adding "use-when" and "use-not-when" sections would make these skills more self-orienting.

What to explore

What a standard "When to use / When not to use" header block should look like
Whether this should be in SKILL.md frontmatter or as a markdown section
Whether some skills already have implicit use-when signals in their descriptions that could be made explicit
How to characterize "not when" — is it about scale, context, or preconditions?
Whether this connects to the specialist-delegation approach in the Hermes workflow

Relationship to existing work

The Hermes profile system uses trigger conditions in skill descriptions. This exploration would define what those triggers look like for agent-skills.

Most skills in this repo describe what they do and how to use them, but few describe the specific problem they solve or the conditions under which they should (or should not) be loaded. This makes it harder for an agent to decide which skill to reach for. Pocock's skills are organized around diagnosed failure modes — each skill explicitly states the problem it addresses. Adding "use-when" and "use-not-when" sections would make these skills more self-orienting. ## What to explore 1. What a standard "When to use / When not to use" header block should look like 2. Whether this should be in SKILL.md frontmatter or as a markdown section 3. Whether some skills already have implicit use-when signals in their descriptions that could be made explicit 4. How to characterize "not when" — is it about scale, context, or preconditions? 5. Whether this connects to the specialist-delegation approach in the Hermes workflow ## Relationship to existing work The Hermes profile system uses trigger conditions in skill descriptions. This exploration would define what those triggers look like for agent-skills.

jasper referenced this issue from a pull request that will close it,

2026-07-11 17:02:58 -04:00

docs(skills): define use-when guidance #106