Claude Agent Skills: Architecture, Installation, and First Skill¶

For / Key Points

For: Users, developers, and administrators who want Claude to reuse the same process or domain knowledge

Key Points:

A Skill packages instructions, metadata, and optional scripts or references as files
Progressive disclosure loads only the relevant Skill content when needed
claude.ai, the API, and Claude Code have different installation, sharing, and runtime models and do not synchronize automatically

Claude Agent Skills add reusable domain procedures to Claude. Unlike a one-off prompt, a Skill persists as a filesystem package and can be selected automatically for a relevant request.¹

Skills fit repeated work: an internal report format, PDF validation, a data transformation, or a brand review can include both instructions and deterministic checks.

What a Skill contains¶

The minimum package has a SKILL.md file with name and description fields in YAML frontmatter.

monthly-report/
├── SKILL.md
├── references/
│   └── metric-definitions.md
├── scripts/
│   └── validate_rows.py
└── assets/
    └── report-template.xlsx

Element	Purpose
`name`	Lowercase identifier using letters, numbers, and hyphens
`description`	What the Skill does and when Claude should invoke it
`SKILL.md` body	Workflow, decision rules, output contract, validation
`references/`	Specifications and examples read only when needed
`scripts/`	Deterministic code for repetitive work and checks
`assets/`	Templates, images, and output materials

The description is not marketing copy. It is the primary discovery mechanism Claude uses to match a request to the Skill. Include both the capability and its triggering situations.¹

Three levels of progressive disclosure¶

Metadata: name and description remain available for discovery
Instructions: Claude reads the SKILL.md body only after the Skill triggers
Resources and code: Claude reads referenced files or runs scripts only when required

This keeps unrelated Skill bodies out of each conversation's context.¹ Metadata still consumes context, so many overlapping Skills can create ambiguous triggering.

Where Skills run¶

Installing a Skill in one place does not make it available everywhere.

Surface	Installation	Sharing scope	Main constraint
claude.ai	Upload a zip through Settings > Features	Individual user	Pro, Max, Team, Enterprise with code execution enabled
Claude API	Upload through the Skills API and reference it in a container	API workspace	Code execution and beta header; no runtime network
Claude Code	Place it in `~/.claude/skills/` or `.claude/skills/`	Personal or project	Inherits the computer's permissions and network

A claude.ai upload does not appear in the API, an API Skill does not appear in claude.ai, and Claude Code uses separate local files.¹

Anthropic's prebuilt PowerPoint, Excel, Word, and PDF Skills are available on claude.ai, the API, Claude Platform on AWS, and Microsoft Foundry. Those prebuilt document Skills are not available in Claude Code, which supports custom Skills.¹

Build a first Skill¶

Choose one repeatable task¶

Start with a task whose input and success criteria are explicit.

Input: monthly usage CSV
Output: department summary and anomaly list
Success: source and aggregate row counts reconcile; missing values are listed

Define the trigger¶

Include relevant file types, situations, and deliverables in the description. If an adjacent Skill competes for similar requests, clarify boundaries in the body.

Write the workflow in execution order¶

Organize the body around input checks, execution, validation, and output. Use prose for judgment and scripts for fragile repetitive operations.²

Test positive and negative cases¶

Does a typical request trigger it?
Does it trigger without naming the Skill explicitly?
Does a similar but out-of-scope request avoid it?
Does missing or empty input stop safely?
Can the output be validated mechanically?

Deploy separately to each surface¶

Skills do not synchronize across surfaces. Decide where the Skill will run and maintain a distribution and update path for each target.

Security¶

A Skill is more than text. It can direct script execution, file access, and external tools, so review it like software.¹

Read every instruction, script, reference, and asset
Inspect external URLs, dependencies, shell commands, and write destinations
Reject network or file access that does not match the stated purpose
Use least privilege and isolation for production data
Review diffs and rerun tests after updates

The API Skill container has no network access and cannot install packages at runtime. Claude Code Skills have the same network conditions as other programs on the computer, so the design must match the target surface.¹

Agent Skills are not eligible for Zero Data Retention. Confirm retention requirements before adopting them for a ZDR-dependent API workload.¹

Summary¶

A Skill is a reusable file package containing procedures, resources, and code
Its description controls discovery; deeper content loads only when needed
claude.ai, the API, and Claude Code use separate deployment and sharing models
Audit a third-party Skill as software, including every bundled file

Do not start with a universal Skill. Pick one repeatable task, fix its success criteria, and make both triggering and output testable.