What You Will Learn

• Understand skill anatomy and choose general vs. work skills
• Design lean skill.md files with progressive reference-file routing
• Build effective work skills using the perform-first and planning methods
• Prevent context rot by modularizing tasks and routing connectors to sub-agents
• Test skills with evals, add self-improvement rules, and iterate

Study Guide

# How to Actually Build Claude Skills like a Pro ## Introduction Here's the thing about AI skills that nobody tells you upfront. Everyone's talking about them like they're some kind of magic bullet. Download a few files, write a prompt, and suddenly your work automates itself. The reality? Most skills out there are garbage. I've seen the numbers, and they're not pretty. Roughly ninety percent of skills floating around on the internet don't apply even the most basic best practices. That's not an exaggeration. That's the actual state of things. But here's the good news. Building skills that genuinely work isn't some dark art reserved for AI engineers. It's a methodology. A repeatable process. And once you understand how it works, you'll never go back to the old way of prompting again. This course is going to walk you through everything. From the fundamental mindset shifts you need before you even open a chat window, all the way to advanced optimization techniques like sub-agent routing and self-improvement rules. You'll learn why most skills fail, how to build ones that actually deliver value, and how to test and refine them until they become genuine automation assets for your business. Let's start with the foundation. --- ## Section 1: Understanding What Skills Actually Are ### The Basic Anatomy of a Skill A skill is essentially a preset instruction package for an AI agent. Think of it as a job description for Claude. When you invoke a skill, Claude reads a set of instructions that tell it exactly how to perform a specific task. No re-explaining. No "here's what I need you to do" every single time. The instructions are already there. Every skill consists of two potential components. The first is the primary instruction file, typically called skill.md. This is the text file that Claude reads to understand the steps required to accomplish the goal. It's the backbone of the whole operation. The second component is reference files. These are supplementary files that provide additional context, examples, or information that helps Claude perform the task better. Not every skill needs reference files, but the good ones usually have them. Here's a simple example. Let's say you want a skill that writes LinkedIn posts. Your skill.md file would contain the step-by-step process for how to approach the post. Your reference files might include examples of posts you loved, your tone-of-voice guide, or a list of hooks that have performed well for you in the past. ### The Two Main Categories of Skills Now, here's where things get interesting. Not all skills are created equal, and understanding the difference between types is crucial for knowing what to build, what to download, and what to avoid. **General skills** are your versatile helper tools. They work across many different contexts, tasks, and user types. A fact-checking skill. A content humanizer. A skill that helps you build other skills. These are broadly applicable, which means they're often available for download from public marketplaces. You can usually adopt them without significant customization because they're designed to be universal. **Work skills** are where the real automation magic happens. These are business-specific automations. A LinkedIn content writer that knows your voice. A client call preparation assistant that pulls from your CRM. An email triage system that understands your priorities. These skills are inherently unique to each organization and professional because they encode your specific processes, preferences, and institutional knowledge. And here's the critical point. Work skills must be built by the people who use them. You can't download these. You can't buy them. You have to create them yourself because they're built on your tacit knowledge, your workflows, your edge cases. This is the category where most practitioners struggle, and it's the category this course focuses on. ### Subcategories of Work Skills Within work skills, you'll find two distinct types that serve different purposes. **Autonomous skills** run without human intervention. They execute on a schedule or trigger without anyone steering the ship. Imagine an email triage system that runs every morning at eight AM. It reads your inbox, categorizes messages, flags urgent items, and prepares summaries. You wake up, and the work is already done. Or a research aggregation tool that scans industry news overnight and delivers a briefing to your team. These skills are set-and-forget automation. **Assistant-type skills** require human-in-the-loop steering. The agent follows a defined process, but you guide direction at key decision points. A content writing skill where you select the angle and the hook. A sales outreach skill where you approve the messaging before it goes out. These skills don't replace you. They amplify you. They handle the heavy lifting while you make the judgment calls. Understanding which type you need is essential because it changes how you structure the skill. Autonomous skills need clear decision rules because no one's there to make judgment calls. Assistant skills need well-designed human-in-the-loop steps with multiple options to choose from. --- ## Section 2: The Mindset That Makes or Breaks Skill Building ### When You Should Actually Build a Skill Most people build skills for the wrong reasons. They see someone else doing it, they think it sounds cool, they want to automate everything at once. That's backwards thinking. You need to be strategic about this. Build a skill when you're performing a task repetitively. That's the obvious one. If you're writing a proposal every week, that's a candidate. If you're triaging emails daily, that's a candidate. The less obvious signals are often more telling. Pay attention to when you find yourself giving the AI the same corrections over and over. You know the pattern. You ask Claude to write something, it produces output, and you say "no, that's not quite right, I need it more like this." Then next week you're saying the exact same thing. That repetition is a massive signal. The correction you're making should be encoded into a skill so you never have to make it manually again. Similarly, notice when you're repeatedly providing the same context to get better outputs. If you always paste in your company background, your target audience description, and your tone-of-voice guide before asking Claude to do something, that context belongs in a skill. And here's the one that most people overlook. Build a skill when you want to hand off a process to another person. Skills are essentially institutional knowledge embedded into a transferable format. Instead of spending weeks training a new hire on how you approach client calls, you give them a skill that encodes your entire approach. They invoke it, and suddenly they're performing at a level that would have taken months to reach. ### The Intern Onboarding Analogy Here's the biggest misconception I see everywhere. People expect skills to work perfectly on the first iteration. They build a skill, try it once, and when the output isn't flawless, they declare the whole approach broken and abandon it. That's like expecting a new intern to perform their entire job flawlessly on day one. It's absurd. You wouldn't do that with a human. Why would you do it with an AI? Think of skills like onboarding an intern or developing software. The process is never truly finished. The first version of a skill, like the first version of a product or the first day of an intern, will not deliver full value. Only through deliberate observation, use, and iterative optimization does a skill reach the point where it meaningfully automates work. This might require two iteration loops. It might require five. Sometimes more. The key is that the effort must be intentional. You can't just assume the skill will improve on its own. You have to consciously observe what's going wrong, make corrections, and update the skill accordingly. I've seen people give up after one failed attempt, convinced that AI automation doesn't work for their use case. The technology wasn't the problem. The mindset was. ### The Principle of Modularity Now let's talk about one of the most common errors in skill building. It's so common, in fact, that even experienced builders fall into this trap. People try to automate an entire end-to-end workflow within a single skill. Let me give you an example. Imagine you have a content process. It involves research, LinkedIn post writing, newsletter drafting, and image creation. That's four distinct tasks. And yet, someone will sit down and try to build one massive skill that does all four things in sequence. This fails because of a phenomenon called context rot. As a conversation progresses, the AI model increasingly forgets the initial skill instructions. The further along in a process you get, the less reliably the model adheres to what it read at the beginning. By the time it reaches the newsletter drafting step, it might barely remember that it's supposed to follow your tone-of-voice guidelines. The solution is the smallest-unit principle. When you're approaching a process to automate, identify the smallest component that would still deliver value. Build only that first. Once that component works reliably, build outward. And crucially, build outward as separate skills that can be invoked sequentially within the same chat. Here's a practical example from a YouTube workflow. Instead of one monster skill, you break it into four separate skills used in sequence. YouTube ideation. YouTube title generation. Packaging. YouTube outline. Each skill is read fresh when the step begins. Each one gets the full attention of the model without competing with the context of three other tasks. The result is dramatically better output quality at every stage. This approach ensures each skill reads fresh instructions at each stage of a multi-step process, maintaining performance quality throughout. --- ## Section 3: The Four Approaches to Building Skills ### Method One: One-Shot Prompting Let's start with the most common and least effective approach. This is what most people do when they first discover skills. They open up a chat, type something like "create a skill that writes LinkedIn posts for me," and hit enter. This rarely produces quality skills. The AI lacks sufficient context about your actual process, your goals, and your edge cases. It makes assumptions and moves forward too quickly. The result is a skill that requires endless optimization or gets abandoned entirely after a few frustrating attempts. One-shot prompting is essentially gambling with your time. You might get lucky occasionally, but the odds are heavily stacked against you. I'd recommend avoiding this approach entirely for anything that matters. ### Method Two: Structured Planning with AI This approach involves using a planning mode or a dedicated process-interviewer skill to systematically elicit requirements before building. Instead of asking for a skill directly, you first go through an in-depth Q&A session where the AI asks you about your process, your goals, your constraints, and your edge cases. The key here is depth. Standard planning modes often move too quickly. The AI asks a few surface-level questions, draws conclusions, and creates the skill without achieving a genuine understanding of what you need. A dedicated process-interviewer skill goes much deeper. It asks extensive questions designed to establish a shared understanding between you and the AI before any skill file is created. This method is particularly appropriate when you're building something entirely new. A new product, a new feature, a new process that doesn't exist yet. When there's nothing to reference, the structured planning approach forces you to think through what the skill needs to accomplish and ensures alignment between you and the AI before any implementation begins. The advantage is that it forces you to think through what the skill needs to accomplish. The disadvantage, as we'll see in the next method, is that it relies on your ability to articulate your process accurately. ### Method Three: Perform the Task First, Then Build the Skill This is the most effective approach for knowledge work, which is the domain where most professionals will be building skills. And it's grounded in something called Polanyi's Paradox. Let me explain. Michael Polanyi was a scientist who studied the nature of expertise. His finding was that the better someone becomes at a task, the more automatic it becomes, and the more tacit knowledge they possess that cannot be articulated. As Polanyi put it, "We know more than we can tell." Think about your own work. Can you fully explain every step of how you write a great proposal? Can you articulate every subtle judgment call you make when qualifying a lead? Probably not. Not because you're bad at your job, but because expertise becomes automatic. The knowledge lives in your hands and your instincts, not in your conscious verbal descriptions. This has profound implications for skill building. When professionals attempt to describe their processes through planning questions, they inevitably omit edge cases and subtle decision rules. They describe a simplified version of their process that doesn't capture the full complexity of what they actually do. But here's the beautiful thing. When you perform the task collaboratively with AI, those tacit rules emerge naturally through corrections and feedback. You don't have to articulate your process. You just have to correct Claude when it does something slightly wrong. The process works like this. You perform the actual task collaboratively with Claude in a chat session. You make corrections as Claude produces imperfect outputs. You iterate through the natural back-and-forth of the task. Then, once the task is complete, you ask Claude to distill the entire process, including the corrections, edge cases, and decisions made along the way, into a formal skill. It is far easier to correct Claude when it does something slightly wrong than to explain your whole process from a blank page. That's the core principle. And it's why this method produces functional skills that actually work. Here's a concrete example. Let's say you want to build a lead qualification skill. Instead of trying to explain your qualification criteria to Claude, you actually work through a batch of leads together. You say things like "no, not those data points, I want engagement data instead" and "this one's actually a bad fit because of X reason." By the end of the session, Claude has seen your judgment in action. It understands the edge cases. And when you ask it to build a skill from that process, it creates something that genuinely reflects how you work. This method takes more initial time than the others, but it's completely worth it because it produces skills that actually work. The time investment pays off in the long run. ### Method Four: Adapting Existing Skills Skills can be sourced from marketplaces, communities, or other professionals. This can be a great way to get good skills fast, especially for general purposes. But here's the critical caveat. These skills will not fit your specific workflow, connectors, or context. They were built by someone else, for someone else's process. Adaptation is mandatory, not optional. You'll need to either use plan mode to customize the skill to your needs, or use the skill yourself and correct it based on your requirements. Either way, expect to invest time in making someone else's skill work for you. The skills that are worth adapting are typically general skills that don't require much customization. For work skills, you're almost always better off building from scratch using the perform-first method. --- ## Section 4: Structuring Skill Files Like a Professional ### The Skill.md Structure Now we're getting into the technical weeds. This is where the pros separate themselves from the amateurs. According to established best practices, the skill.md file should be simple, clean, and direct. Shorter and clearer files are more efficient and reliable. I know it's tempting to cram as much information as possible into the main instruction file, but resist that urge. The skill.md should contain only three elements. The trigger, which is how the skill is invoked. The steps of the process, which is what Claude should do. And routing instructions to reference files, which tells Claude when to load additional context. Everything else belongs in reference files. Output examples. Extra context. Prompts. All of that goes into separate files that Claude loads when needed. Let me give you an example of what this looks like in practice. A LinkedIn writer skill that follows best practices would have a skill.md that's short and to the point. It lays out the steps. It routes to the right reference files at each stage. The actual examples of good posts, the tone-of-voice guide, the hook templates, all of that lives in separate reference files. ### Three Common Structural Problems to Avoid I've analyzed hundreds of skills at this point, and I keep seeing the same three problems over and over. **Over-scoped skills** are the first problem. This is when someone includes an entire end-to-end workflow instead of a single task. Remember the modularity principle. Each skill should handle one task, not a full process. If your skill.md covers research, writing, editing, and publishing, you've built a monster that will suffer from context rot. **Context bloat** is the second problem. This happens when people embed additional context, output examples, or prompts directly in the skill.md rather than as reference files. The skill.md should route to reference files at each step, not contain the content itself. When you stuff everything into the main file, you pollute the context window and degrade performance. **Filler content** is the third problem. AI-generated skills often contain unnecessary discursive text that bloats the file. You'll see paragraphs of explanation that add no value, redundant phrasing, and general wordiness. The skill.md should reduce to essential steps and routing, with all supplementary information stored in reference files. When you're building skills, consider adding this instruction: "Keep the skill.md steps short and direct. Write each step as a plain instruction." This simple prompt can dramatically improve the quality of your skill structure. ### Managing Triggers Skills have two trigger mechanisms, and understanding the trade-offs is important. The first is human-triggered. This means the skill is activated via a slash command. You type /linkedin-writer and the skill kicks in. This is predictable and controlled. You decide when the skill runs. The second is AI-triggered. This means the agent reads the skill's description and invokes it automatically when it determines the skill is appropriate. This can be convenient, but it comes with significant drawbacks. AI triggering costs tokens. The agent reads all skill descriptions in every chat, which adds up over time. And the agent might invoke skills at inappropriate times, interrupting your flow with an unwanted process. For most scenarios, I recommend disabling AI auto-triggering and relying on explicit slash commands. It's more efficient and more predictable. You can add this instruction: "Make this a human-triggered skill only. I don't want Claude to auto-invoke it." ### Managing Connectors and Research Here's a problem that trips up a lot of people. Skills that use connectors, external APIs, or perform extensive research face a significant challenge. These operations are among the largest token consumers in AI agents, and they degrade the model's performance and memory of skill instructions. The problem is exacerbated when research steps occur early in a skill's execution. Here's what happens. The skill is used at the beginning of a chat. Claude reads the skill instructions with everything fresh. The first step involves extensive research or connector calls. Massive amounts of tokens get consumed within the context window. By the time the research is done, Claude has already burned substantial tokens. It's "dumber" now. It's more prone to forgetting the skill instructions. And when it gets to follow-up steps, performance significantly degrades. There's a two-part solution to this problem. First, ask yourself whether the data actually needs to be live. If static information suffices, embed it as a reference file rather than performing live research. You'd be surprised how often people think they need real-time data when they actually just need last month's numbers. Second, if live data is required, instruct the skill to use sub-agents for connector calls and research. Sub-agents perform the work without populating the main context window. They operate in a separate context, do the heavy lifting, and return only the results. This preserves the model's performance for subsequent steps. This technique has been shown to produce significant performance improvements in multi-step skills. I've seen title ideation skills go from mediocre to excellent just by routing the VidIQ research through sub-agents. The main context stays clean, the model stays sharp, and the output quality reflects it. Here's the instruction you can embed: "Use the skill creator skill to update this skill so it keeps connectors and research out of the main context, and routes the connector call or research to a sub-agent." ### Implementing Self-Improvement Rules This is one of my favorite techniques because it turns skills into living systems that evolve through use. A self-improvement rule enables a skill to update itself automatically. The skill.md contains a rule instructing the AI to watch for two signals. The first signal is when the user corrects an output. The second signal is when the user explicitly expresses satisfaction with an output. On either signal, the AI asks: "Should this become a permanent update to the skill?" If confirmed, the skill automatically updates itself using a skill-builder utility. This mechanism allows skills to continuously accumulate knowledge, edge cases, and improved examples without requiring manual editing. Every time you use the skill, it gets smarter. Let me give you a concrete example. You're using a title ideation skill. It suggests ten titles. You select two that you really like. The AI notices your selection and asks: "Want me to log these two formats as saved examples in the title ideation skill?" You say yes. The skill updates itself. Next time you use it, it has those examples to draw from. The confirmation question is a design choice. You could make it fully automated, but confirmation prevents unwanted modifications. It's a safety mechanism that ensures you only apply changes you actually want. Here's the prompt template: "Add a self-improvement rule to this skill: anytime I correct your output during the process or give an output an explicit like, ask me whether that should become a permanent update to the skill." ### Progressive Disclosure of Reference Files This principle is about when reference files get loaded. The rule is simple. Reference files should be loaded only when they are needed for a specific step, not all at the beginning of the process. Loading all reference files upfront pollutes the context window. The AI reads everything at once, and by the time it reaches later steps, it has forgotten information it read earlier. Output quality degrades. The solution is to map each reference file to the specific step where it is most relevant. In each step of the skill.md, specify exactly which reference file or files the AI should read before executing that step. Here's an example. In a LinkedIn content process, step one might read the ICP and company background files. Step two reads three additional files most relevant to that step. Step three reads one more file. When the skill runs, only the files needed for each specific step are loaded at that time. The practical impact is dramatic. Reading hook templates immediately before the hook-suggestion step produces much better output than having the model read those templates at the beginning of the process. Here's the prompt template: "Use the skill creator skill to update this skill so it uses progressive disclosure for reference files. Map each reference file to the specific step where it's actually needed." ### Human-in-the-Loop Steps with Multiple Options For skills that involve human oversight, there's a simple structural change that dramatically improves efficiency. Structure each human-in-the-loop step to produce multiple options. Instead of asking the AI to produce one angle, ask it to produce five to ten variations. Instead of one hook, ask for a selection of hooks. Why does this work? With five to ten variations offered, there's a high likelihood that at least one will resonate with you. Without this, you end up in a back-and-forth loop of explaining why each suggestion is wrong. You repeat your preferences and direction repeatedly. It's exhausting and inefficient. Multiple options eliminate the friction. You select a preferred option, and the skill proceeds to the next step. The workflow becomes smooth and fast. Here's what this looks like in practice for a LinkedIn repurposing skill. At the angle brainstorming step, the AI suggests five to ten angle variations and you select. At the hook selection step, the AI suggests five to ten hooks and you select. At the writing framework step, the AI suggests several frameworks and you select. Then the AI writes the draft based on your selections. Here's the prompt template: "Use the skill creator skill to update the skill so every human-in-the-loop step gives me multiple options to choose from." ### Using a Skill-Builder Skill The best way to apply all of these best practices consistently is to use a skill-builder skill. This is a specialized skill designed to build and optimize other skills. A well-designed skill-builder skill can automatically apply all of the best practices we've covered. When you ask it to build a new skill from a process you performed in chat, it structures the skill.md correctly, sets up reference files with progressive disclosure, adds self-improvement rules, routes connectors through sub-agents, and disables auto-triggers. When you ask it to optimize an existing skill, it can identify and fix structural problems. Add sub-agent routing. Add self-improvement rules. Disable auto triggers. Split skill.md and reference files properly. This is the difference between building skills manually and building them professionally. The skill-builder skill encodes all of the best practices so you don't have to remember them every time. --- ## Section 5: Testing Your Skills ### The Eval Feature Most practitioners skip testing. This is a mistake. Testing is a critical step that can be performed quickly and yields significant dividends. The evaluation feature, often called eval, is built into skill-builder tools. Here's how it works. The skill is run through multiple unbiased sub-agents. These sub-agents test the skill against criteria you define. The result is a comprehensive report showing pass or fail rates for each step, along with suggestions for improvement. When you run an eval, you should define a real test case. Give the test actual content to run against. Don't test with empty inputs and expect meaningful results. Here are some example test criteria. Does the skill function as intended per the goals and steps in its skill.md? Does it execute the process steps in the correct order? Does it load reference files at the appropriate point? Does it call connectors correctly? ### Testing Functional vs. Qualitative Criteria Here's the challenge with knowledge work. Evaluation tools work best with hard, quantifiable criteria. Software engineering has clear test cases. Knowledge work doesn't. Output quality for tasks like LinkedIn writing is subjective. It involves taste. It can't be easily measured. What makes a great LinkedIn post? That's a matter of opinion. But here's what you should always test. Skill functionality. Whether the skill executes its process in the correct order. Whether it loads reference files at the appropriate steps. Whether it calls connectors correctly. This functional testing catches structural and logical errors that would otherwise undermine the skill regardless of output quality. A skill that loads the wrong reference file at the wrong time will produce poor output no matter how good your examples are. For advanced applications, if a skill has hard, quantifiable criteria, automated improvement loops can be implemented. These frameworks function by giving the system a criterion or goal, then having it iteratively test and modify the skill until the goal is reached. While powerful, this approach requires well-defined, measurable criteria, which are often unavailable for knowledge-work tasks. --- ## Section 6: The Continuous Optimization Loop ### Three Core Principles of Optimization Optimization through usage consists of three commitments. First, don't expect perfection on the first build. Second, use the skill even when it doesn't work perfectly on initial attempts. Third, actively observe and refine based on real usage. This last point is crucial. You can't just use the skill and hope it improves. You have to consciously observe what's going wrong, make corrections, and update the skill accordingly. ### Handling Skill Failures There are two common scenarios when skills fail, and they require different responses. **Scenario A: The skill doesn't execute correctly.** When a skill fails to function as designed, the most efficient first step is to ask the AI why the failure occurred. The model can often identify unclear instructions or errors in the skill or reference files. After receiving the diagnosis, update the skill accordingly and consider re-running the eval to verify the fix. **Scenario B: The skill executes correctly but produces poor outputs.** This is more common and indicates that the skill needs additional rules, edge cases, or examples. The optimization loop involves identifying the correction or new edge case, adding it as a rule to the skill, and using the self-improvement rule to automatically suggest and implement updates. This is the continuing process of onboarding the intern. The tacit rules living in your head that are hard to articulate emerge through usage and correction. Each correction you make reveals another piece of your expertise that can be encoded into the skill. ### Learning from Examples For many knowledge-work skills, the single best way to improve outputs is to learn from real examples of good output. Each time the skill generates a good output, save it back into the skill as an output example. The self-optimization rule should prompt this automatically. For a LinkedIn writer, accumulating good post examples is one of the most effective improvement strategies. Real examples of quality work are among the most powerful training material for improving AI output quality in knowledge tasks. ### The Patience Imperative Building good skills, especially for knowledge work, requires time and iteration. The early phases will feel like work. This is an investment, and it requires patience. Remember the intern onboarding analogy. You wouldn't expect a new hire to be productive on day one. You'd expect a ramp-up period. The same applies to skills. Once a skill reaches maturity, it can automate substantial portions of work, freeing up significant time and resources. But that maturity only comes through deliberate iteration. The skills that yield the greatest returns are those built for the specific, repetitive workflows that define each professional's daily work, and built with the patience and rigor this framework outlines. --- ## Conclusion Let's bring this all together. The ability to build effective AI agent skills represents a critical competency for the modern workforce. As AI agents become more powerful, the gap between those who can reliably automate their work and those who cannot will widen. This course has presented a comprehensive framework for closing that gap. The framework's power lies in its alignment with fundamental observations about human expertise. We know more than we can tell. And the most effective way to encode that tacit knowledge into AI systems is through collaborative practice rather than abstract planning. By performing tasks alongside AI, observing and correcting in real time, and then systematically encoding those corrections into reusable skills, you can build automation assets that genuinely deliver value. Remember the key principles. Build small and modular. One task per skill. Avoid context rot. Use the perform-first methodology for knowledge work. Keep skill.md files lean. Route connectors and research through sub-agents. Implement self-improvement rules. Test functionality immediately after building. Save examples of good output. And above all, commit to the iteration loop. Use each skill at least five times before judging its value. After each use, consciously observe failures and successes, and update the skill accordingly. The path to reliable automation is not a one-time build but a continuous loop of development, testing, use, and refinement. Those who embrace this methodology will find themselves with a growing library of automation assets that compound in value, freeing time for the higher-order thinking and creative work that remains uniquely human. Start with one skill. Pick one repetitive task that drains your time. Work through it collaboratively with Claude. Build the skill from that process. Test it. Use it. Refine it. And then do it again with the next task. That's how you build Claude skills like a pro. Not through magic. Not through shortcuts. Through methodology, iteration, and the willingness to invest in your own automation infrastructure.

Frequently Asked Questions

Frequently Asked Questions

This FAQ section covers the questions that come up most often when professionals start building Claude Skills for actual business work. The answers here draw from hundreds of skill-building projects across marketing, sales, and operations teams. You'll find practical guidance on the fundamentals of what skills are, the building process, structural best practices, testing methods, and ongoing optimization. Each answer is designed to be immediately actionable, whether you're building your first skill or refining an existing one.

Section 1: Fundamentals

1. What exactly is a Claude Skill?

A Claude Skill is a structured instruction set that tells an AI agent how to complete a specific task. At its core, a skill consists of two primary components:

skill.md: A text file containing the step-by-step instructions the agent reads to accomplish the task. This file defines the trigger conditions, the sequence of actions, and routing to any supplementary materials.
Reference files: Additional files that provide context, examples, or data to help the agent execute the task better. For example, a LinkedIn writer skill might include a voice personality guide, sample posts, and hook templates as reference files.

Skills function as the agent's "memory" for how to perform tasks, eliminating the need to re-explain processes each time. They can also be shared with others, enabling knowledge transfer across individuals and teams.

2. What are the two main categories of Claude Skills?

There are two distinct categories:

General Skills: These act as universal helper tools applicable across many tasks, users, and use cases. Examples include fact-checker skills, humanizer skills, and skill-builder tools. General skills are typically available for download from the internet and can be adopted with minimal modification.

Work Skills: These are specialized skills designed to automate specific day-to-day workflows unique to an individual or organization. A LinkedIn writer skill or a call preparation skill are examples. Work skills require building by the person or team that will use them, as they encode specific business processes, qualification criteria, and content standards that are unique to each context.

Work skills further divide into two subtypes: autonomous skills that run without human involvement (e.g., an email triage skill that runs on a schedule) and assistant-type skills that require human-in-the-loop guidance (e.g., a content writing skill where the user steers direction at key decision points).

3. When should I build a skill?

There are four clear signals that indicate a skill is worth building:

Repetitive tasks: Any task you perform regularly on a consistent basis is a candidate for skill automation. If you're doing the same thing weekly, the payoff from automation compounds quickly.
Repeated corrections: If you find yourself giving the AI the same corrections repeatedly, that pattern signals a skill opportunity. The correction should be encoded permanently rather than re-applied each time.
Repeated context injection: When you consistently provide the same background context to get better outputs, encode it into a skill so the agent has it automatically.
Process handoff: When you want to delegate a process to someone else, a skill allows you to transfer your embedded knowledge and expertise directly, without needing to sit down and explain everything verbally.

4. Why do most skills fail to actually automate anything?

The most common reasons skills fail include:

Unrealistic expectations: People expect skills to work perfectly on the first try, and when they don't, they abandon the skill or conclude the technology isn't ready. Skills require iterative refinement,thinking of them like onboarding an intern or developing software is far more accurate.

Over-scoping: Attempting to automate an entire end-to-end workflow within a single skill leads to unreliable performance. AI models experience "context rot," gradually forgetting initial instructions as chat sessions progress through many steps.

Lack of iterative optimization: Skills only deliver value after being used, observed, and continuously improved. This requires conscious effort and a willingness to iterate multiple times.

5. What is context rot and how does it affect skill performance?

Context rot is the phenomenon where an AI model progressively forgets initial instructions as a conversation grows longer. The further into a chat session you go, the less reliably the model remembers the skill instructions it read at the beginning, and overall AI performance degrades.

This has direct implications for skill design. If a skill has twenty steps, the AI will likely execute the first few steps well but perform poorly on the later ones because it has partially forgotten the instructions. The solution is to build small, modular skills with fewer steps, so the model can reliably execute each phase while instructions are still fresh.

Context rot is also why progressive disclosure matters,loading reference files at the start that aren't needed until later steps means the model will likely have forgotten them by the time they're actually required.

Section 2: The Building Process

6. What is the recommended framework for building effective skills?

A five-step framework addresses the complete skill lifecycle:

1. Mindset: Know when to build skills, what to automate, and keep realistic expectations about iteration. Skills are not one-and-done; they improve through use.
2. Building: Choose the right construction method based on your task type. Some methods work better for new processes; others work better for existing workflows.
3. Structuring: Apply best practices to skill.md and reference file organization. This includes progressive disclosure, proper triggers, and token management.
4. Testing: Run functional evaluations to verify the skill works as intended. Test step order, reference file loading, and connector behavior.
5. Optimizing: Continuously improve through real usage and observation. Save good outputs, capture corrections, and refine rules.

This framework applies both to creating new skills and to refining existing ones.

7. What are the three main approaches to building a skill, and which should I use?

There are three primary methods, plus a bonus fourth:

Method 1: One-shot prompting,Simply asking Claude to create a skill with a single prompt. This produces poor results because AI needs substantial context to build a good skill. Avoid this for serious work.

Method 2: Planning together with AI,Using plan mode or a process interviewer skill where Claude asks detailed questions before building. This works well for entirely new processes, software, features, or products where you need to think through what the deliverable should look like.

Method 3: Doing the task first, then building the skill,Performing the actual task once alongside Claude in a chat, then asking Claude to create a skill from that process. This is the best approach for knowledge work because most people cannot fully articulate the processes they use daily,a phenomenon known as Polanyi's Paradox.

Method 4 (bonus): Using someone else's skill,Starting with a marketplace skill can be efficient, but these require adaptation to your specific workflows and connectors.

8. What is Polanyi's Paradox and why does it matter for skill building?

Polanyi's Paradox, articulated by scientist Michael Polanyi, observes that the better you become at something, the more automatic it becomes,and the more tacit knowledge you possess that you cannot articulate in words. As Polanyi stated, "We know more than we can tell."

This paradox explains why planning-based skill building fails for existing workflows. When answering questions about your process, you naturally omit edge cases and informal rules that you've internalized but never consciously express. By contrast, performing the task once with Claude surfaces these elements naturally through corrections and observed behaviors, capturing tacit knowledge that question-based approaches miss.

In practice, this means the task-first approach is almost always superior for knowledge work. You demonstrate the process through action rather than description, and the AI captures the nuances you would never have thought to mention.

9. Should I automate an entire workflow in one skill or break it into smaller skills?

Break it down. The MVP (Minimum Viable Product) approach is essential for skill reliability. AI models forget instructions as they progress through many steps, so the more steps a skill contains, the less reliably it executes later instructions.

Consider a process: research → LinkedIn post → newsletter → image creation. You should not bundle all of these into a single skill. Instead:

1. Identify the smallest component that delivers value on its own (e.g., just the research step).
2. Build that component and verify it works well.
3. Build additional skills for subsequent process steps as separate skills.

You can use multiple skills sequentially within the same chat session. For example, a YouTube workflow might be broken into separate ideation, title generation, packaging, and outline skills. Each step in the process reads fresh instructions when the new skill loads, maximizing performance at every stage.

10. What is the one-shot prompting approach and why is it discouraged?

One-shot prompting means simply asking Claude to create a skill with a single prompt, like "Build me a LinkedIn writer skill." While quick and easy, this method rarely produces good skills.

The problem is that AI needs substantial context to build a good skill. Without knowing your voice, your audience, your content strategy, or your specific requirements, the skill will be generic and ineffective. Skills built this way typically require endless optimization and often never become genuinely useful.

Think about it: if you asked someone to write a detailed standard operating procedure for a job they've never done, the result would be shallow and inaccurate. The same applies here. The AI needs to either see the process in action or have a detailed conversation about it before it can encode a reliable skill.

Use case: Essentially none for serious work. If you're building a skill that matters, invest the time in one of the more thorough approaches.

11. How does the process planning approach work in detail?

The process planning approach uses AI-assisted questioning to build a shared understanding before any skill file is created. Standard plan mode often moves too quickly,the AI draws conclusions and creates the skill without fully grasping your actual goals and requirements.

A better variation is using a dedicated process interviewer skill that goes far more in-depth. This skill asks extensive questions to establish a shared understanding between you and the AI before any skill file is created. It might ask about your workflow, your expected outputs, your edge cases, your preferences, and your constraints.

Use case: This method shines when you're building something new into existence,a new software feature, a new product, or an entirely new process that doesn't exist yet. There's no existing workflow to demonstrate, so you need to think through requirements collaboratively.

The key limitation is that it relies on your ability to articulate your needs, which is exactly where Polanyi's Paradox undermines accuracy. Use this method for new processes, and use the task-first method for existing ones.

12. How do I adapt someone else's skill to my workflow?

Skills sourced from marketplaces, communities, or other professionals can be a great starting point, but they will not fit your specific workflow, connectors, or context out of the box. Adaptation is mandatory, not optional.

There are two main adaptation paths:

Use plan mode to customize: Walk through the skill with Claude and ask it to modify the skill to match your specific requirements. Provide your context, examples, and constraints, and let the AI adjust the skill accordingly.

Use the skill yourself and correct it: Run the skill on real tasks, note where it falls short, and apply corrections. This surfaces the gaps between the skill's assumptions and your actual needs. Each correction becomes a rule or reference example that transforms the generic skill into your own.

Expect to invest meaningful time in this process. A downloaded skill is a starting point, not a finished product.

Section 3: Best Practices for Skill Structure

13. How should I structure my skill.md file?

The skill.md should be simple, clean, and direct. Its only purposes are:

Defining the trigger,how the skill is activated
Listing the process steps,what the agent should do, in order
Routing to context/reference files,which files to load at which step

Everything else should either be removed or moved into reference files. Adding examples, extra context, or detailed prompts directly in skill.md bloats the file and reduces reliability.

Avoid three common mistakes:

Over-scoping: Include one task per skill, not an end-to-end workflow.
Inline context: Store output examples, extra context, and prompts as reference files, with skill.md routing to them at the appropriate steps.
Filler content: When AI writes skills, it often produces verbose, bloated instructions. Include an explicit instruction like: "Keep the steps short and direct, write each step as a plain instruction."