🗺️ Why Study Real-World Anatomy
The best way to learn to write a SKILL.md is to dissect the ones that have already won. The ecosystem's most-installed skills (frontend-design with 488.299 installs, skill-creator with 246k, azure-ai with 358.744) aren't accidents: each solves the problem differently, and together they form a catalog of ready-made patterns to imitate.
The honest reuse rule
Don’t copy the content—copy the format. Each anatomy below solves a different trade-off (concision vs. coverage, simplicity vs. routing). Identify which one resembles your skill and use the corresponding skeleton.
🎨 frontend-design — short, surgical description
Anthropic’s most installed skill (488.299 installs) is also one of the leanest in its frontmatter. The description does three things in a single sentence: it says what it does, list when to use, with concrete examples, and ends with the differentiator ("avoids generic AI aesthetics").
real frontend-design frontmatter:
--- name: frontend-design description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics. license: Complete terms in LICENSE.txt ---
✓ What to copy
- ✓Action verb at the beginning ("Create...")
- ✓List of examples in parentheses as triggers
- ✓Final phrase that distinguishes the result
- ✓Zero folders: one body handles everything
✗ When NOT to imitate
- ✗If your skill covers several distinct domains
- ✗If it needs to run deterministic scripts
- ✗If the body would exceed 500 lines without folders
💡 Tip
Use the frontend-design template when your skill is "one competency"—no variants, no scripts. It’s the most common archetype and the easiest to maintain.
🧰 skill-creator — the multi-file anatomy
Anthropic’s skill-creator (246k installs, ~33KB) is the canonical example of a skill large, organized by folders. Keep the body of SKILL.md focused on the essentials; the rest lives in scripts/, references/ e assets/ — exactly the three canonical directories.
The anatomy documented by skill-creator itself:
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter (name, description)
│ └── Markdown instructions
└── Bundled Resources (optional)
├── scripts/ - código determinístico
├── references/ - docs sob demanda
└── assets/ - templates, ícones, fontes
See how the body points for resources instead of pasting the content — the pointer pattern that keeps SKILL.md short:
real pointers in the skill-creator body:
See `references/schemas.md` for the full schema. python -m scripts.package_skill <path/to/skill> Read the template from `assets/eval_review.html`
What to copy
The three directories and their exact roles, plus the discipline of citing each file in the body with a “when to read” sentence. This is the structure to imitate when your skill has reusable code, long docs, and output templates.
🗂️ supabase — domain routing in the description
The supabase skill (99k installs) has one of the most aggressive descriptions in the ecosystem: it starts with "Use when doing ANY task involving Supabase" and dumps a huge list of Triggers: — products, libraries, auth issues. Pure routing: the description alone already knows how to route the agent.
real supabase frontmatter (excerpt):
--- name: supabase description: "Use when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries (supabase-js, @supabase/ssr) in Next.js, React, SvelteKit; auth issues (login, sessions, JWT, RLS); Supabase CLI or MCP server; migrations, security audits, Postgres extensions." metadata: author: supabase version: "0.1.2" ---
✓ What to copy
- ✓The label
Triggers:followed by a list by category - ✓The assertive "ANY" to force triggering
- ✓Block
metadata:with author and version
✓ And in the body
- ✓"Core Principles" numbered at the top
- ✓Security checklists with real-world pitfalls
- ✓Links to official docs instead of pasting everything
💡 Tip
When your skill is the "gatekeeper" for an entire platform, copy the pattern from Triggers: categorized — that's what ensures the agent activates across every part of the domain.
☁️ microsoft-foundry & azure-ai — large operational skills
Microsoft’s skills (foundry and azure-ai, ~358–360k installs, 19KB+) show how to scale a skill operational and huge without losing control: the description uses USE FOR e DO NOT USE FOR to define the scope, and the body is a table of sub-skills that routes to files by workflow.
microsoft-foundry description (excerpt with scope limits):
description: "Deploy, evaluate, fine-tune, and manage Foundry agents end-to-end... USE FOR: deploy agent, hosted agent, create agent, evaluate agent, optimize prompt, deploy model, RBAC, quota, troubleshoot agent... DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy)."
body: sub-skill table that routes by workflow:
| Sub-Skill | When to Use | Reference | |-----------|------------------|------------------| | deploy | Build, push, ACR | deploy/deploy.md | | invoke | Send messages | invoke/invoke.md | | observe | Run evals | observe.md | | quota | Capacity, quota | quota/quota.md |
What to copy
- •USE FOR / DO NOT USE FOR — distinguishes neighboring skills and prevents incorrect triggering.
- •Sub-skill table — SKILL.md becomes a router, with each workflow in its own file.
- •Pre-Execution Requirements — explicit pre-checks before any action.
📋 Comparison table — which template to use
Bring it all together: each anatomy answers a different question about your skill. Use the table as a quick decision guide.
| Reference | Key pattern | Copy when… |
|---|---|---|
| frontend-design | surgical description, no folders | a skill is a single competency |
| skill-creator | scripts/ references/ assets/ | it has code, docs, and templates |
| supabase | Triggers: categorized | is a platform gatekeeper |
| azure-ai / foundry | USE FOR / DO NOT + sub-skills | is large and operational |
💡 Final tip
Most skills start from the frontend-design template and move to the skill-creator template when the body exceeds 500 lines. The supabase and foundry templates are for when the domain branches into many variants. In the next module, you’ll build a SKILL.md from scratch following these patterns.
✅ Module Summary
Next:
Module 3.4 — 🛠️ How to Create: build a SKILL.md from scratch, from frontmatter to body, with a complete template ready to copy.