Explore Real Skills
No one walks into a kitchen and invents a recipe from scratch. You cook someone else's dish first. You follow a recipe that works, notice how it's structured, and then you start riffing.
We're going to do the same thing. Before we build a skill, we need to see what production skills look like. What files do they include? How do they structure their instructions? What patterns show up again and again?
Outcome
Explore real-world skills on skills.sh and identify the documentation patterns that make them effective.
Fast Track
- Browse the skills directory on skills.sh
- Examine 2-3 skills and their file structure
- Note the patterns that appear across multiple skills
Browse the directory
Head to skills.sh and scroll through the list. You'll see skills for everything from frontend design to database management to deployment workflows. Each one is a package that teaches an AI agent how to do something specific.
Pick any skill that catches your eye and click into it. We'll look at a couple together, but you should explore on your own too.
Look at the structure
Let's start with vercel-react-best-practices. This skill teaches an agent to follow React best practices when building with Next.js and Vercel.
Notice the file structure:
SKILL.md
references/
├── react-patterns.md
├── next-app-router.md
└── ...
Every skill follows the same shape. A SKILL.md at the root that acts as the entry point, and a references/ directory with supporting documentation.
The SKILL.md is the file an agent reads first. It's the instruction manual. Let's look at what makes a good one.
What goes in SKILL.md
Open the SKILL.md for vercel-react-best-practices (or whichever skill you're examining). You'll see a pattern:
A description with trigger phrases. The opening paragraph isn't fluff. It tells the agent exactly when this skill is relevant. Phrases like "when building React components" or "when setting up a Next.js project" act as triggers. The agent reads these to decide whether to use the skill.
Step-by-step instructions. Not vague guidelines. Concrete steps: "Check if the component uses client-side state. If yes, add the 'use client' directive." The agent follows these literally, just like it follows API docs literally.
Quality checklists. A list of things to verify before considering the task done. "Ensure all components have proper TypeScript types." "Verify that server components don't import client-only hooks." These give the agent a self-check mechanism.
The description in SKILL.md isn't marketing copy. It's how the agent decides whether to activate the skill. Vague descriptions like "helps with React" give the agent nothing to match on. Specific phrases like "when creating React Server Components in Next.js App Router" tell the agent exactly when to reach for this skill.
Look at a second skill
Now check out frontend-design or another skill that interests you. Compare its structure to the first one you looked at. You'll notice the same bones:
- A clear description at the top with specific trigger phrases
- Instructions written as concrete steps, not abstract advice
- References organized in separate files so the main SKILL.md stays focused
- Checklists or criteria for evaluating the output
The reference files in the references/ directory are where the deep knowledge lives. These are the detailed docs, examples, and patterns that the SKILL.md points to. Think of SKILL.md as the table of contents and the references as the chapters.
Patterns worth stealing
After browsing a few skills, you'll start to see the recurring patterns:
Documentation is structured, not conversational. The same patterns from the previous lesson (code blocks, tables, explicit examples) show up everywhere. Skills don't tell agents to "consider best practices." They list the practices with code examples.
Instructions are imperative. "Do this, then check that, then verify the other thing." Not "you might want to think about..." Agents need clear directives.
References stay separate. The SKILL.md stays short and focused. Heavy documentation goes in references/. This keeps the agent's initial read fast and lets it dig deeper only when needed.
Checklists close the loop. Almost every skill ends with verification criteria. The agent knows when it's done.
A skill isn't magic. It's a folder with markdown files, organized so an agent can find what it needs quickly. The patterns are the same ones you'd use for good human documentation, with more structure and less ambiguity.
Try It
Find a skill on skills.sh that's relevant to your work. Read through its SKILL.md and answer these questions:
- What trigger phrases does the description use?
- How many steps are in the instructions?
- Does it have a quality checklist at the end?
- How are the reference files organized?
If you can answer all four, you've got a feel for the anatomy of a skill. That's the reference point we needed.
Now you know what good looks like. Let's build one.
Commit
No code changes to commit.
Done-When
- You've browsed at least 3 skills on skills.sh
- You can describe the standard file structure of a skill (SKILL.md + references/)
- You can identify trigger phrases in a skill's description
- You've noted the pattern of imperative instructions with quality checklists
- You can explain why reference files are kept separate from SKILL.md
Solution
No code solution for this lesson. The patterns you identified here inform the skill you'll build in Section 3.
Was this helpful?