Skills
Lab setup
First, make sure you have completed the initial setup.
If you are part of a course
-
Open Terminal. Run the update command to make sure you have the latest code.
$ mwc update -
Move to this lab's directory.
$ cd ~/Desktop/making_with_code/pilot/labs/lab_skills
If you are working on your own
-
Move to your MWC directory.
$ cd ~/Desktop/making_with_code -
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:
- Explain what a skill is, and how an agent decides when to use one.
- Write, test, and revise a skill for a task you do regularly.
- Describe what writing a skill taught you about your own way of working.
- Explain how your skills will be used to assess your learning in the studio.
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`.
...
nameidentifies the skill.descriptiontells the agent when to use the skill. The agent sees the descriptions of all available skills at the start of every session, and reads the fullSKILL.mdonly when a task matches. This keeps the context window free until the skill is needed.- The instructions tell the agent how to do the task.
scripts/holds code the skill runs. When a step must be done exactly the same way every time, a script is more reliable than instructions.
๐ป 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:
- Converting sources to Markdown and verifying quotations.
- Synthesizing interview notes into insights.
- Reviewing an agent's pull request.
- Writing a status update for a client.
๐ป 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:
- Write a description that triggers at the right time. Say what the skill is for and when to use it, in words a request for the task would likely include.
- Keep the instructions short. Every line costs context. Include what the agent wouldn't do well on its own, not what it already does.
- Say what good work looks like, and how to check it.
- Say what stays with people. If a decision should be made by you, not the agent, the skill should say so.
- Move detail into other files. Long references go in separate files the skill points to, which the agent reads only when needed.
- Use scripts for steps that must be exact.
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:
- Did the agent load the skill?
- Did it follow the instructions?
- Where did it go wrong, or where were your instructions unclear?
๐ป 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:
- What did you have to figure out about your own way of working to write your skill?
- What was hard to put into words?
- What does a skill capture that a finished product doesn't?
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:
- Technical: how you work with AI to build and understand software.
- Design: how you work with users and develop concepts.
- Collaboration and communication: how you work with your team and clients.
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
- Question: Where should this lab sit? Early (right after AI collaboration) lets skills serve as assessment all semester; it's placed after the other labs for now.
- Proposal: Add the skills portfolio to the assessment section of
pilot/curriculum.md, with a rubric mapping skill qualities to the four learning-objective strands.- Note: Check that pi reads the same
SKILL.mdformat and folder layout as Claude Code.