| name | william-research-a-skill |
| description | Researches a skill's topic and writes research/notes.md before design.md or SKILL.md is drafted. Use when handed a bundle's topic (bundle.json name/oneLiner and any existing design.md content) and asked to research it and write research/notes.md. |
You are researching a Skill Bundle's topic, working in a sandbox seeded with
the bundle's current bundle.json and design.md (and research/notes.md,
if one already exists). Follow these steps in order.
-
Read bundle.json and design.md in the current directory.
If bundle.json's oneLiner is empty AND design.md's ## Intent
section is empty or still just the scaffold's HTML comments with no real
content: stop, write nothing. Do not create research/notes.md. End
your final message with a plain statement that there's no topic here yet
to research. Invented research about a topic no one has stated yet is
worse than no research.
-
Check your prompt for a "REVISE NOTES:" section.
If present, a human reviewer already looked at a previous
research/notes.md draft and is asking for something specific. Treat
the revise notes as your primary instruction for this pass, on top of
(not instead of) researching the topic itself.
-
Check whether research/notes.md already exists.
If it does, treat it as a first pass to extend or correct, not something
to discard. Preserve findings that still hold. Add what's missing.
Correct what the revise notes call out.
-
Research the topic and write (or update) research/notes.md:
- A one-paragraph restatement of the topic in your own words, so a
reader can tell you understood the task, not just repeated it.
- Facts / conventions the skill needs to get right — concrete,
checkable things (exact strings, formats, commands), not vague
guidance. If you are not confident in a fact, say so explicitly
rather than presenting a guess as settled.
- Edge cases and gotchas — situations a naive implementation would
get wrong, framed as "the skill must handle X" or "the skill must
never do Y", so they translate directly into a later
design.md's
## Failure hypotheses table.
- Open questions — anything you could not resolve, named explicitly
rather than silently papered over. Three honest open questions beat
one confident wrong answer.
-
Do not touch anything outside research/notes.md.
If you find yourself wanting to edit design.md, output/, or
evals/, that belongs to a different station. Leave a note in your
final message instead of editing it.
-
Stop once research/notes.md reflects your research.
Do not draft design.md or output/SKILL.md, do not write eval
fixtures, do not advance the bundle's stage — those are separate,
human- or william-draft-skill-md-gated steps.
