Skills

Lab setup

First, make sure you have completed the initial setup.

If you are part of a course

  1. Open Terminal. Run the update command to make sure you have the latest code.
    $ mwc update
  2. Move to this lab's directory.
    $ cd ~/Desktop/making_with_code/pilot/labs/lab_skills
    

If you are working on your own

  1. Move to your MWC directory.
    $ cd ~/Desktop/making_with_code
    
  2. Get a copy of this lab's materials.
    git clone https://git.makingwithcode.org/founders-studio/lab_skills.git

By now, you've developed ways of working with AI: how you set up a task, what you check, where you've learned not to trust the agent. Right now, that know-how lives in your head, and you have to explain it again every time you start a new session. In this lab, you'll write it down as skills: short instruction documents an agent loads when it takes on a kind of task. Writing a good skill turns out to require understanding your own practice very clearly.

By the end of this lab, you will be able to:

What a skill is

A skill is a folder containing a file called SKILL.md, and optionally other files the skill refers to. SKILL.md starts with a short header (called frontmatter), followed by instructions.

๐Ÿ‘ Open examples/verify-quotes/SKILL.md.

---
name: verify-quotes
description: Use this skill whenever writing or reviewing text that quotes from sources
  in the repository, to check that every quotation actually appears in its source.
---

# Verifying quotations

Never trust a quotation that has not been checked against its source...

1. Make sure every source is available as Markdown in the repository. If a source is a
   PDF, convert it first with `markitdown`.
2. Collect every quotation, with the source it is attributed to, in `quotes.txt`.
3. From the repository root, run
   `python .claude/skills/verify-quotes/scripts/verify_quotes.py quotes.txt`.
...

๐Ÿ’ป Copy the example skill into Claude Code's skills folder for this project, then start Claude Code.

$ mkdir -p .claude/skills
$ cp -r examples/verify-quotes .claude/skills/
$ claude

๐Ÿ’ป Ask the agent to write a paragraph about one of the texts in corpus/ with two quotations. Watch whether it loads the skill. Then ask it something unrelated, and check that it doesn't.

Writing a skill

๐Ÿ’ป Choose a task you've done in the studio and expect to do again. For example:

๐Ÿ’ป Before writing anything, describe how you do the task, out loud, to a teammate. Your teammate should write down every step, and ask "why?" and "how do you know it's right?" at each one.

๐Ÿ’ป Write your skill in .claude/skills/your-skill-name/SKILL.md. Keep in mind:

Testing and revising

A skill is like code: you don't know if it works until you test it.

๐Ÿ’ป Try your skill on at least two new cases: tasks like the one you wrote it for, but not identical. Start a fresh session each time. Note in testing.md:

๐Ÿ’ป Revise your skill based on what you found, and commit each revision with a message explaining what changed and why.

$ git add .claude/skills/your-skill-name
$ git commit -m "Tell agent to ask before merging themes, after it merged two distinct themes"

๐Ÿ’ป Trade skills with another team, and try theirs. Give them feedback.

Skills as metacognition

Metacognition means thinking about your own thinking: noticing how you approach a problem, what you know, and what you don't. Writing a skill is metacognition made visible. To write instructions for someone (or something) else, you have to figure out what you actually do, and why.

๐Ÿ’ป Discuss with your group, and answer in questions.md:

Skills and assessment

Throughout the rest of the studio, you will keep a small set of skills, at least one for each of these areas:

You'll revise your skills as you learn, and your skills, their revision history, and short reflections on your revisions are a central part of how your learning in the studio is assessed. A skill that changes because you learned something is evidence of learning.

๐Ÿ’ป As a class, draft rubric.md: what does a strong skill look like? Think about clear triggers, explicit criteria for good work, ways to check results, and a sensible division between what the agent does and what people decide.

Deliverables