[AI Library] Chapter 12: Skills: Reusable Workflow Recipes
Mastering Claude Code
Chapter 12: Skills: Reusable Workflow Recipes
Kim Kyung-jin
Mastering Claude Code
Introduction
At 7 a.m., you type into Claude Code: "Run the morning coffee skill." The agent checks your calendar, pulls this week's tasks from your project management tool, checks your quarterly goal progress, and proposes a schedule for the day. At the same time, in another window you sent "Analyze recent YouTube comments," and in yet another window "Run a team pulse check."
Three agents work in parallel. Each is running a different skill. The time spent typing all this is just over one minute, and doing this manually would have taken at least 25 minutes.
Welcome to the world of Skills.
The Relationship Between Skills and Workflows
Earlier, the WAT framework covered Workflows,instructions written in Markdown that agents read and execute, like Standard Operating Procedures. Skills are essentially the same thing.
Only the name differs. The word workflow suggests a one-time task flow, while skill implies a technique you can use repeatedly with expertise. Workflows have Python scripts attached as tools, and so do skills. Workflows are Markdown files, and so are skills. The structure is identical.
One difference: skills include YAML Front Matter, a section at the top of the file enclosed by --- that records the skill's name and description. This front matter dramatically improves how agents discover skills. Rather than reading the entire content of every skill file, agents scan just the names and descriptions in the front matter.
They scan the front matter's name and description, select the appropriate skill for the current request, then read only the body of the chosen skill in detail. This is called Progressive Context Loading.
You can view a skill as an evolved form of a workflow, or simply as a different name for the same concept. What matters is that both are natural language instructions for agents, readable and editable by humans. You define agent behavior using everyday sentences, not programming languages.
Creating Skill Files in the .claude/skills Directory
Skill files live in your project's .claude/skills/ directory. Each skill is organized in its own subfolder, with skill.md as the core file.
[Figure 12-1: Example .claude/skills Directory Structure]
Alongside skill.md, a skill folder can contain supporting files: Python scripts in a scripts/ subfolder, reference documents in a references/ subfolder, and so on. Organizing everything inside the skill itself is called a Self-Contained structure.
Another approach exists. Scripts or reference files can be elsewhere in your project. For example, your YouTube analysis skill's skill.md can reference ../../references/youtube_channel.md, and the agent will follow the path to read that file even if it lives outside the skill folder. This is called an External Reference structure.
This is called an External Reference structure.
Either way, the core principle is simple: the correct path must be recorded inside skill.md.
Creating your first skill doesn't mean writing Markdown directly. You build it through conversation with an agent. In plan mode, ask: "Build me a research skill that uses the Perplexity API and sets up API key placeholders in .env." The agent designs the folder structure, writes skill.md, generates necessary scripts, and updates CLAUDE.md to register the new skill.
Why delegate this to an agent rather than do it manually? The agent already knows best practices: YAML front matter format, file path conventions, efficient structures that count tokens well. However, agents don't always create perfect structures. Sometimes they generate a skill as pure Markdown without the YAML front matter.
When this happens, you can add the front matter yourself, or give the agent Anthropic's official documentation URL and instruct: "Follow this document and build it to best practices."
The recommended length for skill.md is 500 lines or fewer. Keep detailed reference materials in separate files to save on token counts.
How to Write Effective Skill Descriptions
For a skill to work properly, the agent must be able to find it. When the agent analyzes the user's request and selects from dozens of available skills, the description plays a critical role.
In the first stage of Progressive Context Loading, agents read only the name and description of each skill. This scanning costs roughly 100 tokens per skill. If the description is vague, the agent may choose the wrong skill or miss an appropriate one entirely.
An effective description has three qualities.
State the trigger situation. Describe the specific moment when this skill should be invoked, such as: "Use when the user creates a daily plan or says morning coffee." This lets the agent match the user's natural language request against your description.
Specify the output. Describe what the skill produces, such as: "Synthesizes calendar, tasks, and goals to output a time-blocked daily schedule." This gives the agent a way to confirm the results match what the user expects.
Define the boundaries. State what the skill does not cover, such as: "This skill addresses scheduling only and excludes content creation or research." When multiple similar skills exist, clear boundaries prevent agent confusion.
[Figure 12-2: Three Stages of Progressive Context Loading: Front Matter Scan → Load Skill Body → Load Reference Files]
Skills can be invoked two ways. First, with a slash command: type /morning-coffee and the skill runs immediately. Second, with natural language: say "Set up my day" and the agent searches descriptions to find the morning coffee skill.
Slash commands are fast and precise,no interpretation needed, instant execution. Natural language is flexible,you don't need to know the skill name, just convey your intent. Both are typically enabled, but if a skill triggers too often unintentionally, you can set disable_model_invocation: true in the YAML front matter to allow only slash command activation.
When a skill isn't being called, the description is usually the culprit. A vague description like "useful skill" matches nothing. But a specific one,"Call the Perplexity API to generate a PNG infographic in your brand guidelines whenever the user requests one",matches much more accurately.
Committing to GitHub and Sharing with Your Team
As long as a skill exists in .claude/skills/, it works only in that project. When you push the project folder to GitHub, any team member can clone the repository and use the same skills.
Think about what this means. One person creates a research skill and runs it dozens of times, refining it. They adjust prompts, improve output formatting, and optimize to reduce unnecessary API calls. The moment they commit this to GitHub, the entire team gains access to research of the same quality. One person's learning curve becomes the team's competence.
The process is straightforward. Initialize a Git repository with git init, or ask an agent: "Upload this project to GitHub." The agent creates the repository, commits, and pushes. Each time you modify a skill, make a commit, and version control is automatic. You can compare which version of a skill performed better and roll back if problems arise.
[Figure 12-3: The Skill-Sharing Flow: Personal Creation → Git Commit → GitHub Push → Team Clone]
One more choice exists regarding where skills are stored: Project Skills versus Global Skills.
Project Skills live in .claude/skills/ and work only within that project. You can share them with team members. If a frontend design skill is needed only in a web development project, keep it as a project skill.
Global Skills live in ~/.claude/skills/ in your home directory and are available in every project you open. They aren't shared with team members. Personal skills you use alone, or skills common to all projects, belong here. If a frontend design skill is needed in any project, store it globally for convenience.
A skill's real value doesn't lie in any single finished skill. It lies in the feedback loop. You run the skill, watch how the agent works, give feedback like "That API call was unnecessary" or "I don't like the output format," and the agent updates skill.md.
Repeat this cycle ten times, twenty times, and the skill that felt awkward at first transforms into a tool perfectly suited to your workflow. Expecting a perfect skill from an agent from the start is unrealistic. Perfection comes from repetition.
There are patterns you discover while optimizing skills. If an agent wastes time searching the same data repeatedly, hardcode frequently referenced IDs or paths into skill.md. If an agent consumes too much of its reading window at once, add instructions to the skill directing it to delegate heavy work to a secondary agent.
If an agent queries external API documentation every time, collect that information from the web and save it as a reference Markdown file. Reading a Markdown file is far faster and cheaper than crawling API documentation.
All these optimizations share a single direction. Execute a skill, work on other things for ten minutes, then return to check the finished result. When you reach that point, the image of one person running four agents simultaneously and completing a full day's work by morning ceases to be fantasy and becomes daily routine.
And when these skills connect to each other, secondary agents call one another, and external services begin conversing with agents through MCP, something is created that transcends the level of a personal assistant.
Gyeong-jin Kim, Attorney and AI Expert
AI Legal Policy Specialist · Former National Assemblyman · Author of Multiple Works
If this book has remained beside you, even briefly, please support bringing the next story to the world.
(Voluntary support account: Nonghyup 302-1096-0948-81 Account holder: Gyeong-jin Kim)
Kim Kyung-jin
Attorney · Former Member of the National Assembly · AI Policy Researcher
© 2026 Kim Kyung-jin. All rights reserved.