DEV Community

Cover image for Anthropic Skills: Build Portable Agent Workflows with SKILL.md and Scripts
Sh Raj
Sh Raj

Posted on

Anthropic Skills: Build Portable Agent Workflows with SKILL.md and Scripts

#ai #agents #opensource #productivity

Why skills are becoming a reusable unit of agent engineering

A long system prompt is easy to write and difficult to maintain. It is always present, mixes unrelated instructions, and grows every time a team discovers another edge case.

Agent Skills take a modular approach: package a repeatable procedure as a folder containing an instruction file, optional scripts, and reference material. An agent can discover the skill from its metadata, load the full instructions only when relevant, and read supporting files when needed.

The Anthropic Skills repository is a collection of examples for Claude, covering creative work, development, enterprise workflows, and document creation. It was created in 2025, so it is not a new launch. The current signal is renewed attention: in the weekly GitHub Trending snapshot collected at 06:58 UTC on November 14, 2026, it ranked second with 6,169 stars gained during that week. The GitHub API also showed a push on November 14. No tagged GitHub release was listed, so treat it as an actively maintained collection rather than a versioned SDK.

Repository versus standard

There are two related things:

  • Anthropic's repository contains example implementations intended for Claude's skill system.
  • Agent Skills is the open format described at agentskills.io, originally developed by Anthropic and released as a cross-platform standard in December 2025.

The folder format is portable, but behavior still depends on the client. A skill that calls a Claude-specific tool, assumes a certain filesystem layout, or requires a particular script runtime may need adaptation in another agent.

How a skill is loaded

The format uses progressive disclosure:

  1. Discovery: the agent sees each skill's name and description.
  2. Activation: when a task matches, the agent reads the full SKILL.md instructions.
  3. Execution: the agent follows the instructions and loads referenced files or runs scripts as needed.

This keeps a large skill library from consuming the entire context window at the start of every session. The official specification recommends keeping the main SKILL.md under 500 lines and moving detailed reference material into separate files.

Anthropic's progressive disclosure model for Agent Skills

Image: progressive disclosure in Anthropic's engineering article. Source: Equipping agents for the real world with Agent Skills.

Anatomy of a skill

A minimal skill is a directory with one required file:

csv-audit/
├── SKILL.md
├── scripts/
│   └── check_csv.py
├── references/
│   └── expected-columns.md
└── assets/
    └── report-template.md
Enter fullscreen mode Exit fullscreen mode

Only SKILL.md is mandatory. The other directories are conventions for executable code, documentation, and static resources.

The required YAML frontmatter fields are name and description. The name must be lowercase, use letters, numbers, and hyphens, and match the parent directory. The description should explain what the skill does and when the agent should use it. The specification also defines optional fields such as license, compatibility, metadata, and allowed-tools. The allowed-tools field is experimental, so do not treat it as a security boundary.

Here is a small starting point:

---
name: csv-audit
description: "Inspect CSV exports for duplicate IDs, missing required fields, and invalid dates. Use when reviewing a CSV before importing it into an application."
---

# CSV audit

1. Read the input file without modifying it.
2. Check that required columns exist.
3. Report rows with missing IDs or invalid dates.
4. Identify duplicate IDs and include their row numbers.
5. Summarize findings before suggesting cleanup.

If the task requires a company-specific rule, read
references/expected-columns.md before reviewing the file.

Do not upload the CSV or send its contents to an external service.
Enter fullscreen mode Exit fullscreen mode

This example teaches a procedure. An optional Python script can handle deterministic checks such as duplicate IDs, while the instructions explain how the agent should interpret and report the results. Keeping those responsibilities separate is more reliable than asking a model to count duplicates by generating text.

Anatomy of a SKILL.md file

Image: the metadata and instruction structure described by Anthropic. Source: Anthropic engineering article.

Install the official examples in Claude Code

The repository documents a plugin marketplace flow. In Claude Code, register the marketplace:

/plugin marketplace add anthropics/skills
Enter fullscreen mode Exit fullscreen mode

Install the document skill set:

/plugin install document-skills@anthropic-agent-skills
Enter fullscreen mode Exit fullscreen mode

Or install the example collection:

/plugin install example-skills@anthropic-agent-skills
Enter fullscreen mode Exit fullscreen mode

After installation, ask Claude Code to use a specific skill for a task. The document-skills set includes PDF, DOCX, PPTX, and XLSX examples. Developers using the Claude API can follow the Skills API quick start.

The official video explains how skills differ from project instructions, MCP servers, and subagents:

Skills are not MCP servers

A useful mental model:

  • A skill provides procedural knowledge: how to perform a task, which edge cases matter, and how to validate the result.
  • MCP provides connectivity and tools: access to an API, database, repository, browser, or other external capability.
  • A subagent provides a separate execution context: useful for delegation or a different tool set.

A skill can teach an agent how to use an MCP server safely. It does not create the server, grant credentials, or guarantee that the client has the required tools. A project-level file such as AGENTS.md is better for repository-wide conventions; a skill is suited to a reusable procedure loaded on demand.

Security and licensing

Skills can contain executable scripts and instructions that influence how an agent uses files, network access, and tools. Anthropic warns that malicious skills can introduce vulnerabilities or direct an agent to exfiltrate data.

Before installing a third-party skill:

  1. Read every SKILL.md and referenced file.
  2. Inspect scripts, dependencies, shell commands, and network destinations.
  3. Check whether it assumes access to secrets or private repositories.
  4. Pin a reviewed commit and test it in a sandbox with sample data.

The repository README says many skills are Apache 2.0 and specifically identifies the document skills as Apache 2.0. That is not a blanket license statement for every folder or third-party asset. Check the license and notices inside the exact skill you plan to reuse.

When should you use the format?

Skills are useful when a task repeats, requires domain-specific procedure, or needs reference material that should not be loaded into every session. Examples include release preparation, data validation, accessibility review, incident triage, and document formatting.

They are less useful for one-line preferences, permissions, or capabilities the agent does not have. Keep descriptions narrow enough to avoid triggering on unrelated tasks. Evaluate a skill on representative inputs, including cases where it should not activate. A vague description can cause over-triggering; an overly specific one can prevent selection.

Start by turning one successful workflow into a small skill, adding a test set, and observing how the agent uses it. Split long references out of SKILL.md only when needed. A skill should be an executable playbook, not a documentation dump.

Sources and further reading:

Which recurring engineering workflow in your projects would benefit most from becoming a version-controlled skill?

Written by Shaswat. Find more work on GitHub, LinkedIn, and StackShade on YouTube.

Top comments (0)