3.3 Writing Skills That Actually Work

🎥 Video lesson — video not yet migrated (source Skool video id: cdc5c8e7c32c4e478bf8aaaf14b5a6a8).

Learning Objective

Understand the anatomy of a SKILL.md file and write clear, testable skills that produce consistent results - by thinking of it as training a new employee, not programming a machine.

Train an Employee, Not a Machine

Forget "prompt engineering." Instead, think about how you would train a smart new hire on their first day.

What would you explain to them? What would you show them? What does a great result look like, and what mistakes should they avoid? That is exactly what goes into a skill file.

Here is the real test: if a capable new employee could not follow your instructions and produce the result you want, Claude will not be able to either. Write for a human first. Claude benefits from the same clarity.

The Two Parts of a SKILL.md

Every skill file has two sections: the frontmatter at the top and the body below it. Think of the frontmatter as the label on the outside of a folder, and the body as the full set of instructions inside.

Frontmatter - The Label

The frontmatter has three fields.

name is a short, descriptive identifier. Use lowercase with dashes. Examples: "generate-proposal", "monitor-campaigns", "scrape-leads". Keep it clear enough that you know what the skill does just from the name.

description is one or two sentences explaining what the skill does AND when to use it. This is critical because Claude reads the description to decide if a skill is relevant to what you are asking. A bad description like "Handles proposals" gives Claude nothing to work with. A good description like "Generates a client proposal based on discovery call notes. Use after a qualified lead completes a discovery call." tells Claude exactly when and why to use this skill.

allowed-tools defines which tools Claude can use when running this skill. Options include Bash, Read, Write, WebFetch, and others. Only give access to what the skill actually needs. Do not open everything up.

Body - Prerequisites

Start with what needs to exist before this skill can run. What files need to be in place? What data does Claude need access to? What context should already be available?

Be specific. "Discovery call notes must exist in the client folder" is better than "have the right information ready." If Claude cannot find what it needs, the skill fails before it even starts.

Body - Process Steps

These are numbered, sequential actions that walk Claude through exactly how to complete the task. Each step should be one clear action, not a paragraph of mixed instructions.

Include decision points where needed. "If the client mentioned a specific budget, include it in the pricing section. If no budget was mentioned, use the standard pricing tier." This kind of branching logic makes your skills handle real-world variation instead of only working in perfect conditions.

Body - Output Format

This is where you define exactly what the result should look like. Specify the structure, the sections, the length, and any formatting requirements.

Including a real example of good output is the single biggest quality booster you can add to any skill. An example is worth more than three paragraphs of instructions. When Claude can see what "done" looks like, it produces dramatically better results.

Body - Rules

Rules are your quality checks, constraints, and guardrails. These are the "always do this" and "never do that" instructions.

Examples: "Always include pricing in the proposal." "Never mention competitor names." "Output must be under 500 words." "Use the client's company name at least twice."

You will not know all your rules on day one. Most rules come from testing - you run the skill, notice something off, and add a rule to prevent it next time.

Common Mistakes to Avoid

Being too vague. "Write good content" means nothing. What does "good" mean for your business? Define it with specifics.

Skipping the output format. Without a clear format, Claude guesses what you want. Sometimes it guesses right. Often it does not.

No examples. Examples anchor Claude's understanding of quality better than any amount of written instructions.

No quality checks. Without rules, output quality is inconsistent. You will get great results sometimes and mediocre results other times.

Too many steps. If a skill has more than 15 steps, it is doing too much. Break it into two or three smaller skills that each do one thing well.

Missing prerequisites. The skill fails because it cannot find the data it needs. Always specify exactly where inputs come from.

Tips for Writing Great Skills

Start with the output. What do you want to see when the skill is done? Work backwards from there to define the steps.

Include one or two real examples of good output. Define what "done" looks like so you can measure success. Add rules last, because the best rules come from testing and finding gaps.

Action Items

• Write at least 2 complete SKILL.md files for your department
• For each skill, include frontmatter, prerequisites, process steps, output format, and rules
• Include at least 1 example of expected output in each skill
• Review each skill with this test: could a smart new employee follow these instructions and produce the right result?
• Share one skill in the community for peer review