Understanding Anthropic Agent Skills: What They Are and How to Build One

In the rapidly evolving AI landscape, terms like Function Calling, Tool Use, MCP, Agent, and Agentic AI often feel like hype, making it hard to discern genuine technical breakthroughs. In mid‑October, Anthropic quietly launched Agent Skills (referred to as Skills), sparking debate about whether this is another marketing concept or a useful addition to the AI toolbox.

Why Skills?

Skills aim to solve a simple problem: reuse of prompt engineering. When you repeatedly write technical articles, you constantly need to remind the AI of certain instructions (tone, length, code examples, etc.). Currently, you must re‑enter these prompts each session, which is cumbersome and error‑prone.

Anthropic’s solution packages prompts, resources, and scripts into a zip file that can be loaded on demand, similar to Tool Use. This reduces the need to repeat prompts and streamlines workflows for repetitive, standardized tasks.

Skills vs. MCP

While both aim to extend AI capabilities, their goals differ. MCP (described as a "USB Hub") focuses on connecting the model to external data sources and outputs, whereas Skills act like a "Swiss‑army knife" that encapsulates domain‑specific knowledge and workflows for internal execution. They can complement each other rather than replace one another.

Skills vs. Projects

Projects (available in Claude and ChatGPT) create a workspace that retains context across sessions, useful for multi‑step tasks. Skills, on the other hand, package a method or standard workflow that can be shared and reused across teams, without retaining project‑specific state.

What Is a Skill?

A Skill is a zip archive with a required SKILL.md file and optional resource files. The structure looks like:

my-skill.zip
 └── my-skill/
     ├── SKILL.md   # required metadata and instructions
     └── resources/ # optional additional files

The SKILL.md contains a YAML header with name and description, followed by Markdown sections for instructions and examples. The header metadata is loaded as system prompt metadata (Level 1), while the instruction body is loaded when the Skill is invoked (Level 2). Resource files are loaded only if the Skill’s code accesses them (Level 3).

Practical Example: Image‑Upload Helper Skill

The author builds a Skill that uploads local images referenced in a Markdown article to an image‑hosting service, then replaces the local links with the hosted URLs. The directory layout is:

article-publisher/
 ├── SKILL.md          # definition and workflow
 └── scripts/
     └── upload_images.py  # script that performs conversion, upload, and link replacement

The SKILL.md explicitly defines trigger phrases ("上传图床" / "upload images") and provides a concise command line invocation, while a long list of Do NOT rules constrains the model to avoid unwanted behaviors.

The Python script handles:

Supported image formats and conversion of unsupported formats to PNG.

Extraction of local image paths from Markdown using a regular expression.

Uploading each image via a configurable HTTP API (placeholder https://xxx.com/upload).

Replacing the original Markdown links with the returned URLs.

Cleaning up temporary converted files.

Key functions include convert_image_format, upload_file, extract_local_images, replace_image_links, and a main entry point that orchestrates scanning, uploading, and updating the Markdown file.

Testing and Results

After moving the Skill folder to ~/.claude/skills, the author tests it with Claude Code, showing screenshots of successful uploads and link replacements. The final Markdown file contains only the hosted image URLs, confirming the Skill works as intended.

Takeaways and Advice

Start with simple, single‑function Skills before attempting complex multi‑step workflows.

Provide detailed description fields to guide the model, even if this deviates from official recommendations.

Use English prompts for more stable and faster model responses.

Keep expectations modest; Skills are still experimental and may be unstable for intricate tasks.

Overall, Skills offer a promising way to encapsulate repeatable AI workflows, but they are not a silver bullet for all agent platforms. Users should iterate gradually and tailor Skills to well‑defined, repeatable tasks.

References

Claude Agent Skills documentation: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview

Anthropic blog on Agent Skills: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

How to create custom Skills: https://support.claude.com/en/articles/12512198-how-to-create-custom-skills

YouTube explanations of Claude Skills: https://www.youtube.com/watch?v=m-5DjcgFmfQ and https://www.youtube.com/watch?v=KBslHtyHRaU