mirror of
https://github.com/mattpocock/skills.git
synced 2026-09-12 18:38:06 +07:00
Add changeset; re-sync the two docs pages tied to this bug
CLAUDE.md requires a docs re-sync when a promoted skill's behaviour changes, and a changeset for versioning. Full re-syncs of all ten touched skills' docs pages would be disproportionate for a wording-only change to internal invocation instructions, but two pages specifically document the exact reliability problem this phrasing targets — the "most reported problem" FAQ on grill-with-docs's page, and the matching "rough edge" FAQ on grilling's page, plus a stale literal quote of grill-me's SKILL.md body. Updated those three spots to reflect the new mechanism without overclaiming the bug is fully fixed, and added a changeset summarizing the change across all ten affected skills. Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
@@ -55,7 +55,7 @@ Scope decides it. Use this for anything you can settle in one session; use [wayf
|
||||
Two known causes. The mundane one: nothing qualified. ADRs need all three gates, and a session about a change with no new vocabulary genuinely has nothing to write. The real bug: when the skill runs inside another orchestration layer — a spec-driven-development wrapper, a multi-agent framework, a rule that invokes it as a step in someone else's pipeline — the file-writing half is reported to silently not happen, while the interview still runs. This is filed and unfixed. If you are in that setup, check the working directory before you trust the session's output.
|
||||
|
||||
**It asked everything at once, with no recommendations, and never mentioned `CONTEXT.md`.**
|
||||
That is the skill failing to load its two dependencies. Because `SKILL.md` is a one-line delegation, an agent that does not pick up [grilling](https://aihero.dev/skills-grilling) and [domain-modeling](https://aihero.dev/skills-domain-modeling) guesses at what grilling means, and you get an undifferentiated question dump. Partial loading is the more confusing case — `grilling` loads, `domain-modeling` does not, and you get a good interview with no paper trail. It correlates with model and [effort](https://www.aihero.dev/ai-coding-dictionary/effort) level, and it is the most reported problem with this skill. If you suspect it, ask the agent directly which skills it loaded.
|
||||
That is the skill failing to load its two dependencies. `SKILL.md` is a one-line delegation that now names both explicitly as separate Skill tool calls ("Call the Skill tool twice, for `grilling` and `domain-modeling`") rather than a bare mention, which is intended to raise the hit rate — but an agent that still doesn't pick up [grilling](https://aihero.dev/skills-grilling) and [domain-modeling](https://aihero.dev/skills-domain-modeling) guesses at what grilling means, and you get an undifferentiated question dump. Partial loading is the more confusing case — `grilling` loads, `domain-modeling` does not, and you get a good interview with no paper trail. It correlates with model and [effort](https://www.aihero.dev/ai-coding-dictionary/effort) level, and it has been the most reported problem with this skill. If you suspect it, ask the agent directly which skills it loaded.
|
||||
|
||||
**Where did all my other decisions go?**
|
||||
Into the conversation only. This is the most substantive open complaint about the skill: the glossary is not a spec, most answers do not earn an ADR, and there is no ledger tying each resolved answer through to a spec, a ticket and a test. Precise answers — ordering guarantees, negative requirements, numeric defaults — get softened into weaker prose downstream, and the result can look complete while missing the thing you actually decided. The mitigation available today is to keep the session and feed it straight to [to-spec](https://aihero.dev/skills-to-spec), and to re-read the spec against your own answers rather than assuming it captured them.
|
||||
|
||||
Reference in New Issue
Block a user