Build Your Own Teaching Skill: Lessons from Anthropic's SKILL.md Design

Most people meet a Claude skill as a magic trick. You ask for a lesson differentiated three ways, and a classroom-ready plan appears a moment later. Useful — but the trick teaches you nothing about how to build the next one. When Anthropic open-sourced two of its K-12 teaching skills at github.com/anthropics/k12-teacher-skills, it did something more valuable than ship a trick. It published the blueprint.

That matters because a good teaching skill is not a clever prompt. It's a small, opinionated system with three non-negotiable commitments: it knows where its facts come from, it produces an artifact a student can actually hold, and it can be graded against a rubric before it ever meets a classroom. Add a fourth — awareness of the data connector it depends on — and you have the design principles behind k12-lesson-planning and k12-lesson-differentiation. Here's how to steal them for whatever you're building.

Grounding lives in references/, not in the prompt

The first thing you notice opening either skill is that the domain knowledge isn't crammed into one giant instruction block. It's split into a references/ directory with a file per subject: ela.md, math.md, science.md, social_studies.md, and a learning-commons-kg.md describing how to read the standards connector. The skill pulls in the guidance relevant to the task instead of carrying every subject's pedagogy at once.

This is the single most transferable idea in the repo. Subject-specific rigor beats one-size-fits-all: what makes a strong science investigation is not what makes a strong close reading of a text, and a skill that pretends otherwise produces bland, averaged output. By keeping guidance modular, the authors let each subject's reference file be genuinely opinionated — and let a maintainer improve the math guidance without touching the ELA guidance.

The prompt is where you tell Claude what to do; references/ is where you tell it what "good" looks like in a specific domain. Conflating the two is why most homemade skills feel generic.

If you're building a skill for legal drafting, financial modeling, or clinical notes, the pattern is identical: one reference file per sub-domain, loaded as needed, each written by someone who actually knows that corner of the work.

Scripts turn chat into an artifact

The second commitment is the one most skill authors skip. Inside each skill's scripts/ directory are render_lesson_docx.py, render_lesson_html.py, and a theme.css. The skill doesn't just describe a lesson in the chat window — it emits a structured lesson JSON and then renders that JSON into a .docx file and a styled .html page.

That's not a cosmetic flourish. A teacher's finish line is a document they can print, project, or drop into a sub folder — not a wall of chat text they have to reformat at 10pm. By treating the artifact as the deliverable and the conversation as scaffolding, the skill respects where the work actually ends. It's also a cleaner architecture: the model reasons about pedagogy and produces structured data; a deterministic script handles layout. You get consistent, on-brand output every time instead of the model re-inventing formatting on each run.

The reusable lesson: decide what file your user needs to walk away with, and make producing that file part of the skill. For the marketplace equivalent of this idea, see how Lesson Plan Studio frames the plan itself as the product rather than the conversation about it.

Evals make "good" a testable claim

The third directory is evals/, and it's what separates a hobby skill from one you'd trust in front of thirty students. The evaluation framework ships rubrics as CSV files — per subject (ela, math, science, social_studies, plus a shared rubric), a dedicated clarifying_question rubric, and a differentiation rubric. The repo also includes a technical write-up of how the skills were evaluated.

Anthropic evaluated the skills for rigor, pedagogical alignment, and classroom usability, and refined them with early classroom feedback — including from Prospect Schools in Brooklyn. But you don't need their exact process to benefit; you need the habit. A rubric turns a vague hope ("this makes good lessons") into a checklist you can score a hundred outputs against and watch a change either improve or regress the number.

The clarifying_question rubric deserves special attention. It grades whether the skill asks the right question when a request is ambiguous — because a skill that confidently guesses is worse than one that pauses to ask. If you're forking this framework for your own domain, that piece is covered in depth in Fork the Evals: writing rubric-based tests for your own education skills.

Write for the connector — and for its absence

The fourth principle is the subtlest. Both skills are written to use the Learning Commons Knowledge Graph connector — the data source that gives Claude academic standards across all 50 states and the learning progressions beneath them. That dependency is explicit, documented in learning-commons-kg.md, not buried as a silent assumption.

Being explicit about your data dependency is a design virtue. It tells a user exactly what the skill needs to do its best work, and it tells a future maintainer what to swap if the environment changes. The repo even advises adapting the skills if your setup lacks the connector — bring your own standards and curriculum. That graceful-degradation mindset is worth building in from day one; it's the whole subject of adapting the skills without the Learning Commons connector.

What to copy into your next skill

If you're authoring a skill this month — teaching or otherwise — treat the K-12 repo as a checklist, not a curiosity. The four moves generalize cleanly:

• Modularize your domain knowledge. One reference file per sub-domain in references/, loaded on demand. Let each be opinionated; don't average them into mush.
• Ship an artifact, not a transcript. Decide the file your user needs — a doc, a deck, a spreadsheet — and put a rendering script in scripts/ that produces it deterministically from structured data.
• Write the rubric before you trust the output. Encode "good" as a rubric you can score against, and give ambiguity its own test so the skill asks instead of guessing.
• Name your dependencies, then plan for their absence. State which connector or data source the skill assumes, document it, and describe how to run without it.

None of this requires a research team. It requires deciding that a skill is a system with sources, outputs, and tests — not a paragraph of instructions you hope works. The teaching skills are a particularly honest example because education punishes vagueness: a lesson that's subtly wrong wastes a class period. That pressure produced a repo worth reading line by line.

You can install the skills as a Claude Code plugin and read the source directly, or browse curated education agent skills for more patterns. Either way, the takeaway is the same. The next great teaching skill probably won't come from Anthropic. It'll come from a teacher who opened this repo, recognized their own subject in a references/ file, and decided to write a better one.

---

Part of the Claude for Teachers series. Related: Adapting the Skills Without the Learning Commons Connector · Fork the Evals: Rubric-Based Tests for Education Skills. Browse AI tutoring skills or more builder insights.