cgoinglove/thursday/skill-creator

Skill Creator

A skill for creating new skills and iteratively improving them.

At a high level, the process of creating a skill goes like this:

• Decide what you want the skill to do and roughly how it should do it
• Write a draft of the skill
• Create a few test prompts and run them yourself with the skill loaded
• Show the user the results and ask what they would change
• Rewrite the skill based on the user's feedback
• Repeat until you're satisfied
• Expand the test set and try again at larger scale

Your job when using this skill is to figure out where the user is in this process and then jump in and help them progress through these stages. So for instance, maybe they're like "I want to make a skill for X". You can help narrow down what they mean, write a draft, write the test cases, run all the prompts, and repeat.

On the other hand, maybe they already have a draft of the skill. In this case you can go straight to the test/iterate part of the loop.

Of course, you should always be flexible and if the user is like "I don't need to run a bunch of evaluations, just vibe with me", you can do that instead.

Cool? Cool.

In this app

This section replaces the parts of Anthropic's original that run only in Claude's own products. Where it and the rest of this skill disagree, this section wins.

Who does the writing

If you are Thursday, on a call, the interview is yours, out loud (one question per turn, no lists read aloud). Then hand the whole brief with thread_start to the bot whose work the skill is for, or to any bot when it serves every bot's work. The bot cannot hear the call, so the request carries every answer, anything the user said about who should have the skill, and that the skill is validated before it is reported. Writing and testing a skill takes minutes, which is a bot's work.

If you are a bot, the brief is in your hands. The user is not at your screen: what you need from them you ask as a question, the way your instructions say to ask the user (clearly, with the context to answer, and short options when they help), and your turn ends there until the answer brings you back. So ask what only the user knows in one question with parts, not an interview, and never ask what the brief or the conversation already answers.

Who it is for, and where it goes

Before you write a new skill, decide who it is for. This is yours to decide, not a question for the user; the request decides it when it says.

• Only this bot: <your own folder>/.agents/skills/<name>/ (the Environment names your own folder). Listed to you alone. Pick it when the skill serves your own line of work, and when you are unsure.
• Every bot: .agents/skills/<name>/ at the workspace root, where your shell starts. Listed to every bot, and to the call. Pick it when any bot would follow the skill whatever its work (how the user wants a kind of file made, a service or a tool they use in every kind of job), or when the user said it is for everyone.

Narrow comes first because a skill's description is read by every bot that has it on every step, and a method from one line of work is noise in the others. A skill kept to one bot moves to the workspace root later with one mv.

The shipped skills in $THURSDAY_SKILLS come with the app and are read-only: never write there. When two skills share a name, the shipped one wins and the other is not listed at all, and a bot's own skill wins over an every-bot skill of the same name. To change a shipped skill, copy its folder into one of the two places above under a new name and edit the copy. That is a new skill, so decide who it is for as above.

To improve a skill the user already has, edit it where it is and keep its name and its folder's name: they are what the user's earlier requests and other skills refer to. write_file replaces a whole file, so read the file first.

Testing, without a benchmark runner

There is no benchmark runner here: no subagents running each test with and without the skill, no baseline, no grading or benchmark scripts, no review viewer, no description optimization loop. Testing follows the path Anthropic's original gives for Claude.ai, which lacks them too:

1. Run the test prompts yourself, one at a time. Load the skill with load_skill (after an edit, read its SKILL.md again with the shell), then follow its instructions to accomplish the test prompt yourself, doing the real work in the job's scratch folder. This is less rigorous than independent runs (you wrote the skill and you're also running it, so you have full context), but it's a useful sanity check, and the human review step compensates. A step whose effect would outlast the test (sending, posting, buying, booking, deleting) stops at a draft that shows what it would have done.
2. Show the results and ask for feedback. In one question to Thursday: for each test case, the prompt and what came out, naming each file so the user can open it, then "How does this look? Anything you'd change?" A question ends your turn, so the test prompts go in this question with their results rather than in one of their own.
3. Fix the skill and run the test cases again, until the user is happy.

Keep the test prompts and their outputs in the job's scratch folder, not in the skill's folder: every file there is listed to whoever loads the skill.

Descriptions here

Every bot reads every skill's full description on every step; the call reads at most its first sentence, cut at 90 characters. So the first sentence says what the skill does on its own, and the when follows. Write it in the third person ("Turns a meeting transcript into…", not "I can…" or "You can…"), and with the words the user actually says, in the language they speak, not only English.

Scripts

Node is guaranteed (the app runs on it); Python and anything else may be missing. Write a bundled script for Node, or have the skill check for what its script needs before it runs it. load_skill lists a skill's files along with its body, up to a limit, and past it only says how many more there are; keep the tree small enough to be listed whole.

Before you report

node $THURSDAY_SKILLS/skill-creator/scripts/validate.mjs <the skill's folder>

It checks what fails silently: frontmatter the app cannot parse, keys outside the spec, a name that does not match its folder, a name another skill already holds. A folder that does not pass is a skill the app skips or another app refuses, without telling anyone, which looks exactly like one that was never written. Fix it and run it again until it passes.

Then report the path, who the skill is for and why, and the description you settled on: to the user that line is the whole skill, because it is what makes it trigger. load_skill finds the skill by its exact name at once; the skill lists show it from the next turn or call.

Communicating with the user

The skill creator is liable to be used by people across a wide range of familiarity with coding jargon. If you haven't heard (and how could you, it's only very recently that it started), there's a trend now where the power of AI agents is inspiring plumbers to open up their terminals, parents and grandparents to google "how to install npm". On the other hand, the bulk of users are probably fairly computer-literate.

So please pay attention to context cues to understand how to phrase your communication! In the default case, just to give you some idea:

• "evaluation" and "benchmark" are borderline, but OK
• for "JSON" and "assertion" you want to see serious cues from the user that they know what those things are before using them without explaining them

It's OK to briefly explain terms if you're in doubt, and feel free to clarify terms with a short definition if you're unsure if the user will get it. Here the user usually hears your words in Thursday's voice, which makes plain words matter even more.

Creating a skill

Capture Intent

Start by understanding the user's intent. The current conversation might already contain a workflow the user wants to capture (e.g., they say "turn this into a skill"). If so, extract answers from the conversation history first — the tools used, the sequence of steps, corrections the user made, input/output formats observed. The user may need to fill the gaps, and should confirm before proceeding to the next step.

1. What should this skill enable a bot to do?
2. When should this skill trigger? (what user phrases/contexts)
3. What's the expected output format?
4. Should we set up test cases to verify the skill works? Skills with objectively verifiable outputs (file transforms, data extraction, code generation, fixed workflow steps) benefit from test cases. Skills with subjective outputs (writing style, art) often don't need them. Suggest the appropriate default based on the skill type, but let the user decide.

Interview and Research

Proactively ask questions about edge cases, input/output formats, example files, success criteria, and dependencies. Wait to write test prompts until you've got this part ironed out.

Check your connected tools and the web if useful for research (searching docs, finding similar skills, looking up best practices); the find-skills skill searches the open registry for skills that already exist. Come prepared with context to reduce burden on the user.

Write the SKILL.md

Based on the user interview, fill in these components:

• name: Skill identifier, and the name of its folder
• description: When to trigger, what it does. This is the primary triggering mechanism - include both what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body. Note: currently models have a tendency to "undertrigger" skills -- to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit "pushy". So for instance, instead of "How to build a simple fast dashboard to display internal company data.", you might write "How to build a simple fast dashboard to display internal company data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'" (How this app shows it: In this app › Descriptions here.)
• compatibility: Required tools, dependencies (optional, rarely needed)
• the rest of the skill :)

Skill Writing Guide

Anatomy of a Skill

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/    - Executable code for deterministic/repetitive tasks
    ├── references/ - Docs loaded into context as needed
    └── assets/     - Files used in output (templates, icons, fonts)

Progressive Disclosure

Skills use a three-level loading system:

1. Metadata (name + description) - Always in context (~100 words)
2. SKILL.md body - In context whenever skill triggers (<500 lines ideal)
3. Bundled resources - As needed (unlimited, scripts can execute without loading)

These word counts are approximate and you can feel free to go longer if needed.

Key patterns:

• Keep SKILL.md under 500 lines; if you're approaching this limit, add an additional layer of hierarchy along with clear pointers about where the model using the skill should go next to follow up.
• Reference files clearly from SKILL.md with guidance on when to read them
• For large reference files (>300 lines), include a table of contents

Domain organization: When a skill supports multiple domains/frameworks, organize by variant:

cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

The model reads only the relevant reference file.

Principle of Lack of Surprise