--- name: skill-creator description: "Write a new skill, or fix one that exists. Reach for it whenever the user describes a repeatable way of working rather than a one-off task, even when the word skill never comes up." --- # Skill Creator A skill is a folder with a SKILL.md in it. The model reads every skill's name and description when a call starts, and reads the body only when it calls `load_skill`. So a skill is two things written for two different moments: a description that has to survive being skimmed in a list, and a body that only has to be right once it is opened. Everything below follows from that. ## Where a new skill goes Where it sits decides who gets it, and the app reads two places: - `/.agents/skills//` (the Environment names your folder) — yours alone. The default for a way of working that belongs to your subject. - `.agents/skills//` at the workspace root, your working directory — every bot and the call get it. When the user wants it for everyone, or it is not about your subject. Both are also where `npx skills add` downloads to, depending on the folder it is run from. The shipped skills (`$THURSDAY_SKILLS`, the folder a bot's shell names) come with the app and are read-only. Do not write there. When a name collides, the app's skill wins — a user skill with the same name is not listed at all. To change a shipped skill, make one under a different name, and copy the original folder as a starting point if that helps. `bash` runs in the workspace, so a shared skill's path is simply `.agents/skills//` and a shipped skill's is `$THURSDAY_SKILLS//`. If `load_skill` handed you an absolute path, use that. ## Who does the writing Writing a skill is not one turn of a conversation. It is reading, drafting, rewriting, and checking — minutes of work, not a sentence. **If you are Thursday**: do the interview yourself, out loud. That part is conversation and it is the part you are good at — one question per turn, no lists read aloud. Then hand the whole brief to a bot with `thread_start`. The bot cannot hear the call, so the request has to carry all of the answers, the exact target path, and the fact that it must validate before reporting. If no bot fits, write it yourself — but say first that you are going quiet for a moment. **If you are a bot**: the brief is in your hands. Write the files, run the validator, and report the path and the description line you settled on — to the user that line is the whole skill, because later it is what makes it trigger. ## The interview Four questions are enough, and needing more is rare: 1. What should this let you do? 2. When should it trigger — what will you be saying at that moment? 3. What should come out at the end? 4. Do you already have a way in mind, or is that mine to decide? If the procedure is already in the conversation — the user just walked through something and said "do it like that from now on" — you already have most of the answers. Play it back in one sentence and ask only about the gaps. Do not interview someone who has just finished explaining. ## The description is the skill Nothing else about a skill is loaded until it triggers, and triggering happens on the description alone. A perfect body behind a vague description is a skill that never runs. Write both halves: what it does, and when to reach for it. Put in the words the user would actually say — in the language they actually speak, not only English. Lean toward eager. The common failure is not a skill that fires too often; it is a skill that sits still while the model makes a mess of the job from scratch. Weak: `Helps with meeting notes.` Better: `Turns a raw meeting transcript into the user's note format — decisions first, then owners, then open questions. Use whenever the user mentions a meeting, minutes, or a standup, or hands over a transcript and asks what to do with it, even if they never say the word notes.` ## Writing the body Imperative, and explain why. A model that understands the reason handles the cases you did not think of; a model handed only a rule pushes that rule to its end. If you are writing ALWAYS or NEVER in capitals, the reason is missing from that sentence — write the reason instead. Keep it under 500 lines. It is read in full every time, and a call is a live conversation waiting on it. When it grows past that, the fix is not to cut content but to move it: ``` / SKILL.md the workflow, and signposts to the rest references/ detail read when needed — one file per variant scripts/ deterministic work. Executed, not read assets/ templates, files that go into the output ``` Of the three, `scripts/` is the strongest. If the procedure has a step that is the same every time, a script does it identically for free — no tokens, no drift. Write it here once instead of having the model reinvent it every call. Node is guaranteed (the app runs on it). Anything else may be missing. Remember that `load_skill` returns up to 50 file paths along with the body. A tree bigger than that is a tree with files nobody will open. ## Fixing a skill that already exists `write_file` replaces the whole file, so read it first unless you mean to lose what is there. Leave the name and the folder name alone — they are what the user's earlier requests and other skills pointing here refer to. Do not edit skills that ship with the app (`$THURSDAY_SKILLS`) — make a copy under a different name in one of the two places above and edit that. ## Before you report ```bash node $THURSDAY_SKILLS/skill-creator/scripts/validate.mjs ``` It checks the things that fail silently: frontmatter the app cannot parse, a name that does not match the folder, a name another skill already owns. A folder that does not pass is not a broken skill — it is a skill the app skips without telling anyone, which looks exactly like one that was never written. ## Listed from the next call The skill list is read when a session opens, so a skill written during a call is not in this one's list. `load_skill` with its exact name still finds it on disk. Report it as there, valid, and listed from the next call on. ## What this app does not do There is no eval harness here — no A/B runs against a baseline, no benchmark viewer, no bundling into a distributable file. When the user asks whether the skill actually works, the honest answer is to use it on a real request in the next call and fix it from what happens there. One real use tells you more than assertions written with the same head that wrote the skill. --- Adapted from Anthropic's skill-creator for this app (Apache-2.0, see LICENSE.txt).