Anthropic Official Agent Skills Tutorial: Complete Notes on the 6-Lesson Course

Anthropic has finally released an official Agent Skills tutorial video, consisting of 6 lessons with a total duration of 22 minutes. It covers the entire lifecycle of Skills, from what they are to how to create, configure multi-file setups, distinguish them from other features, share them, and troubleshoot.

The greatest value of this tutorial isn't just teaching you how to write a Skill, but explaining the design philosophy and underlying mechanisms of Skills. Many problems people encounter when using Skills stem from an insufficient understanding of these mechanisms.

What Problems Do Skills Solve?

Every time you explain your team's coding standards to Claude, you are repeating yourself. Every PR review, you have to re-describe how you want feedback organized. Every commit message, you have to remind Claude of your preferred format.

Skills are designed to eliminate this repetition. A Skill is a Markdown file that teaches Claude how to do something once, and Claude automatically applies that knowledge in relevant situations.

More accurately, an Agent Skill is a folder containing instructions, scripts, and resources. Claude can automatically discover and utilize these to complete work more accurately and efficiently.

The core mechanism is the description field. When Claude starts, it loads the names and descriptions of all Skills. When you make a request, Claude performs semantic matching between your request and the descriptions of all available Skills to find and activate the matching one. Only upon activation is the full Skill content loaded into the context window.

This is fundamentally different from claude.md. The content of claude.md is loaded in every conversation, regardless of what you are doing. A Skill is only loaded when needed; your PR review checklist doesn't need to be in the context while debugging, appearing only when you actually request a review.

When should you use a Skill? If you find yourself repeatedly explaining the same thing to Claude, that's a Skill waiting to be developed.

Creating Your First Skill from Scratch

Creating a Skill requires only two steps: creating a directory and writing a file.

Step one: Create a directory named after the Skill under ~/.claude/skills/. Placing it here means it's a personal-level Skill, available across all projects.

Step two: Create a SKILL.md file in the directory. The file is divided into two parts, separated by three dashes. The top part is YAML metadata containing name and description. The bottom part contains the specific instructions for Claude to follow.

When Claude Code starts, it scans four locations for Skills: enterprise paths, personal Skills directory, project Skills directory, and installed plugins. It only loads the name and description of each Skill, not the full content.

When you send a request, Claude compares the request with all Skill descriptions. If the intent matches, it will first ask you to confirm whether to load the Skill. Only after confirmation does it read the full file and execute the instructions. This confirmation step keeps you aware of what context Claude is using.

If Skills with the same name exist, the priority from high to low is: Enterprise level (managed-settings.json), Personal level (~/.claude/skills), Project level (project/.claude/skills), and Plugin level (project/.claude-plugins/skills).

This means a company can enforce standards through enterprise-level Skills while allowing individuals to customize via Skills with different names. If your company has an enterprise code review Skill, you can create a personal Skill called front-end-pr-review to supplement rather than overwrite it.

Advanced Configuration: Metadata Fields and Progressive Disclosure

Basic Skills only need name and description, but several advanced configurations can make Skills more powerful.

The allowed-tools field can limit which tools Claude can use when the Skill is active. For example, if you have a read-only analysis Skill, you can prohibit editing, writing, and Bash commands. If this field is omitted, the Skill imposes no restrictions, and Claude uses the normal permission model.

The model field can specify which version of the Claude model to use.

The way the description is written directly determines whether a Skill can be correctly triggered. A good description should answer two questions: What does this Skill do? When should Claude use it? If a Skill doesn't trigger, add more keywords that match the phrasing of your requests.

The most important advanced concept is progressive disclosure. Skills share the context window with your conversation. If you cram everything into a 20,000-line SKILL.md, it will consume massive context space.

The correct approach is: put essential instructions in SKILL.md and detailed reference materials in separate files, which Claude reads only when needed. The recommended directory structure for open standards is: a scripts folder for executable code, references for reference documents, and resources for data files like images and templates. Use links in SKILL.md to reference these files.

Key rule: SKILL.md should not exceed 500 lines. If it does, it should be split. Scripts can be executed directly without loading their content into the context; only the output consumes tokens. So, tell Claude to run the script rather than read it. This is particularly useful for environment validation and data transformation, as tested script code is more reliable than on-the-fly generation.

Differences Between Skills and Other Claude Code Features

Skills vs. claude.md: claude.md is always loaded into every conversation for project standards and rules that always apply, such as "This project uses TypeScript strict mode." Skills are loaded on demand, activated only when Claude matches a request.

Skills vs. Sub Agents: Skills add knowledge to the current conversation; once activated, instructions are added to the existing context. Sub Agents run in an independent context, completing tasks and submitting results separately, completely isolated from the main conversation.

Skills vs. Hooks: Hooks are event-driven, triggering when specific events occur, such as Claude running a Linter every time a file is saved. Skills are request-driven, activating based on the questions you ask.

Skills vs. MCP: MCP provides external tool connections, allowing Claude to call services like Gmail or Notion. Skills provide knowledge and workflows, telling Claude how to use those tools to complete specific tasks.

Summary in one sentence: claude.md holds always-on instructions, Skills hold auto-matched expertise, Sub Agents run delegated tasks in isolated contexts, Hooks respond to events, and MCP connects to external tools. They can be used in combination.

Sharing Skills: From Individuals to Teams to Organizations

The value of Skills lies in sharing. A PR review Skill used only by yourself is helpful, but a team-shared Skill can standardize code reviews and provide a consistent experience.

Three ways to share:

First is the project directory. Commit the Skill to the .claude/skills directory of the code repository. Anyone who clones the repo automatically gets these Skills without extra installation. Updates are received in the next pull. This is suitable for team coding standards and project-specific workflows.

Second is plugins. Think of plugins as a way to distribute Skills across projects. Once uploaded to an app store, other users can download and install them. If your Skill is generic and not project-specific, this is the best choice for community members.

Third is enterprise deployment. Administrators push Skills to the entire organization via managed settings. Enterprise-level Skills have the highest priority and will overwrite personal and project Skills with the same name. This is used for mandatory standards, security requirements, and compliance workflows.

An important note: Sub Agents do not automatically inherit your Skills. When you delegate a task to a sub-agent, it starts with a fresh context. Built-in agents (Explorer, Plan, Verify) cannot access Skills at all; only custom sub-agents you define can use them, and they must be explicitly listed in agent.md.

To create a custom sub-agent with Skills, create an agent.md file in the .claude/agents directory and add a skills field listing the required Skill names. Only list Skills that are always relevant to the sub-agent's goal, as these Skills will be loaded when the sub-agent starts.

Troubleshooting Guide: Six Reasons Skills Fail and Their Solutions

Skill issues usually fall into six categories:

1. Skill not triggering: The reason is almost always a poorly written description. Claude uses semantic matching; your request needs to align with the meaning of the description. If there isn't enough overlap, it won't match. Solution: Compare the description with your request phrasing and add trigger phrases users actually say, like "help me analyze," "why is this slow," or "speed it up."

1. Skill failing to load: Check paths and filenames. SKILL.md must be inside a named directory, not directly in the skills root. The filename must be exactly SKILL.md in all caps. Run claude --debug to view loading errors.

1. Claude using the wrong Skill: This means you have multiple Skills with descriptions that are too similar, making it impossible for Claude to distinguish them. Solution: Make each description as specific as possible to help Claude decide when to use which.

1. Personal Skill being ignored: A higher-priority Skill (like an enterprise one) with the same name might be overwriting it. Check the four priority levels. Solution: Rename your Skill to something more unique.

1. Plugin installed but Skill not visible: Clear the cache with rm ~/.claude/plugins/cache, restart Claude Code, and reinstall. If it still doesn't work, the plugin's directory structure might be wrong; use the validation tool skills-ref validate to check.

1. Skill loaded but failing during execution: If the Skill uses external packages, ensure they are installed. Add dependency information to the Skill's description.

Anthropic also provides a validation tool called skills-ref to check if the Skill's file structure and YAML syntax are correct. It is recommended to install it via uv for the fastest method.