Claude / agent skills — what belongs on this shelf

tl;dr: a skill is a folder with SKILL.md (+ optional references/ and scripts). The agent loads the YAML always, the body only when the task matches. That is a repeatable method, not MCP and not “whatever Anthropic published as an example.” Listing only anthropics/skills is the wrong shelf.

What we actually catalog

Kind	Example	Why it belongs
Authored / book-grounded	Refactoring UI Audit — Wathan/Schoger method as an eight-pass UI audit	Teaches a named craft. This is the product.
House / product playbooks	Vercel vercel-labs/agent-skills, Microsoft microsoft/skills, obra/superpowers	Same format, real workflows
Indexes (follow the link)	skills.sh, ui-skills.com, Composio/VoltAgent awesome-lists	Discovery. Write a page only when you can fetch the SKILL.md.
Anthropic demo + document skills	19 folders in anthropics/skills (175,409 stars this session)	Format + PDF/DOCX/PPTX/XLSX. Necessary, not sufficient.

Drop a .skill zip (it’s a zip) into ~/.claude/skills/ or .claude/skills/, or upload it on claude.ai. No marketplace id required.

How Skills load — three-level progressive disclosure

From the Agent Skills overview. The whole point is cheaper context: only the metadata is always-loaded; instructions load on trigger; scripts and references load on demand.

Level	When loaded	Token cost	What’s read
1. Metadata	Always at startup	~100 tokens per skill	name + description from YAML frontmatter
2. Instructions	When the description matches your request	<5k tokens	Body of SKILL.md (Claude reads it via bash)
3. Resources / scripts	When instructions reference them	0 until accessed	FORMS.md, scripts/*.py, schema files, etc. Scripts run via bash — only their output enters context.

That is why a skill can ship a 200-line references/ folder and cost nothing until you actually need it. Also why the description field is the only thing the trigger logic reads — vague descriptions kill discovery.

Skills vs MCP vs custom instructions

From Anthropic’s Help Center (What are skills?):

	What it is
Skill	Repeatable procedure. Loads when relevant.
MCP	Connection to an external service. Use both: MCP for access, skill for how.
Custom instructions	Always on. Skills are task-specific.
Projects	Static background for chats in that project. Skills work across Claude.

Agent Skills is not covered by ZDR (same overview page). Skills API operations show in audit logging.

Help Center: available on Free, Pro, Max, Team, Enterprise if code execution is on. Claude Code: custom skills as folders; pre-built pptx/xlsx/docx/pdf Skills are not in Claude Code (API + claude.ai). Open-source claude-api skill is bundled with Claude Code.

Install — by surface

This is what the docs actually say, fetched 2026-09-10. Sources at the bottom of the page.

Claude Code (filesystem)

Claude Code does not load Anthropic’s pre-built document Skills (pptx/xlsx/docx/pdf). It does load the open-source claude-api skill out of the box. For everything else, you create Skills as SKILL.md folders on disk and Claude discovers them automatically:

# personal — across all projects on this machine
mkdir -p ~/.claude/skills/my-skill
# project — shared via source control
mkdir -p .claude/skills/my-skill

Then write the YAML frontmatter (name + description) and instructions, drop references and scripts in the same folder, restart Claude Code.

For Anthropic’s sample set, install as a Claude Code plugin marketplace:

# inside a Claude Code session
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

Or browse: Browse and install plugins → anthropic-agent-skills → document-skills / example-skills. Best docs: Use Skills in Claude Code.

Claude API + claude.ai + AWS + Microsoft Foundry

• Pre-built Agent Skills (pptx, xlsx, docx, pdf) are available on the Claude API, Claude Platform on AWS, Microsoft Foundry, and claude.ai. Microsoft Foundry requires a Hosted on Anthropic deployment — Azure-hosted Claude does not get Skills.
• Custom Skills upload via the Skills API (/v1/skills) on the Claude API. Workspace-wide once uploaded. Skills uploaded to the API are not visible on claude.ai and vice-versa — surfaces do not sync.
• API Skills require the code execution tool (container.skills). No network access in the sandbox; no runtime package install. Pre-configured dependencies only — check the code execution tool docs for the package list.

claude.ai (paid plans with code execution enabled)

• Pre-built Skills are on by default.
• Custom Skills upload as .skill zips under Settings → Features. Per user only — Team/Enterprise admins cannot centrally provision custom Skills. Enterprise tier can turn on Skill content scanning for uploads.

Runtime constraints (per surface)

This is the table that decides whether your skill will actually run:

Surface	Network	Runtime packages	Sharing
Claude API	No external network	Pre-installed only — no pip install at runtime	Workspace-wide
claude.ai	Varies by admin/user setting	Managed by Anthropic	Per user
Claude Code	Full network — same as the user’s shell	Discouraged global install; install locally	Personal ~/.claude/skills/ or project .claude/skills/; also via Claude Code Plugins
Claude Platform on AWS	Same as Claude API	Same as Claude API	Workspace-wide
Microsoft Foundry	Same as Claude API	Same as Claude API; requires Hosted-on-Anthropic	Workspace-wide

If your skill needs pip install or curl at runtime, it runs on Claude Code only. If it needs network calls to a private API, it runs on Claude Code or claude.ai (when network is on). It will not run on the API.

Security (the part Anthropic bold-warns)

From the overview page:

If you must use a Skill from an untrusted or unknown source, exercise extreme caution and thoroughly audit it before use. Depending on what access Claude has when executing the Skill, malicious Skills could lead to data exfiltration, unauthorized system access, or other security risks.

A skill is a folder with SKILL.md plus optional scripts. Those scripts run with whatever the host gives them. On Claude Code that means bash on your machine. Treat untrusted skills like running curl | sh. Audit:

• The SKILL.md body for hidden instructions or base64 blobs
• Every file under scripts/ — that’s the executable surface
• Every URL in references/ — fetched content can carry prompt injection
• Frontmatter name / description for typosquatted siblings (e.g. pdf- vs pdf)

Catalog work follows config/skill-safety.md here: read SKILL.md as text, static-scan via scripts/lib/skill-scan.ts, never npx skills add, never unzip-and-run. sandbox_test.verdict stays untested unless we ran it.

Anthropic’s sample set (anthropics/skills, 19 folders this fetch)

GitHub contents API on anthropics/skills / skills/ — 19 directories. README: document four (docx, pdf, pptx, xlsx) are source-available, not Apache; many others are Apache 2.0. Read each folder’s LICENSE.txt.

Document (source-available; also API pre-built)

Skill	Job	On this site
pdf	Read/merge/split/forms/OCR PDFs	PDF skill
docx	Create/edit Word (docx-js + XML unzip path)	not a dedicated page yet
pptx	Decks, .pptx / .potx	not a dedicated page yet
xlsx	Spreadsheets; openpyxl + mandatory LibreOffice recalc	not a dedicated page yet

docx SKILL.md: do not npm install first — docx is preinstalled in their environment; page size defaults to A4. xlsx SKILL.md: never ship while recalc.py reports formula errors; no XLOOKUP/FILTER because their LibreOffice path cannot evaluate them.

Example / technical / creative (repo README: demonstration)

Folder	From name + SKILL.md where we opened it
mcp-builder	Write Python (FastMCP) or TS MCP servers; eval XML at the end
claude-api	API/SDK reference skill (also bundled in Claude Code)
skill-creator	How to author a skill
webapp-testing	Test web apps
web-artifacts-builder	Artifacts
frontend-design	Frontend design
algorithmic-art	Creative
canvas-design	Creative
theme-factory	Theming
slack-gif-creator	GIFs for Slack
brand-guidelines	Brand application
internal-comms	Internal comms templates
doc-coauthoring	Co-authoring
academy-guide	Academy
discernment-nudge	Discernment

There is no bash SKILL.md in this tree. Shell is a Claude Code native tool. Catalog note: Bash (not in anthropics/skills).

README disclaimer: implementations in Claude may differ from these folders. Treat them as patterns. Only install skills you trust — docs are explicit that a malicious skill can drive bash/tools.

Partner directory

Help Center: Skills Directory includes partner skills (Notion, Figma, Atlassian, …) meant to pair with their MCP connectors. Repo README highlights Notion Skills for Claude. We did not fetch the full directory UI this session.

Related

• Refactoring UI Audit — authored skill; what this shelf is for
• PDF (Anthropic)
• Frontend design
• UI Skills catalog
• Best MCP servers — tools, not procedures
• MCP servers explained
• CLAUDE.md guide — memory files, the other side of context