Equipping agents for the real world with Agent Skills

생각 덩어리

모델은 강력하지만 실전 일에는 절차적 지식이 필요하다

Claude is powerful, but real work requires procedural knowledge and organizational context.

as these agents become more powerful, we need more composable, scalable, and portable ways to equip them with domain-specific expertise.

This led us to create Agent Skills: organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks.

신입 온보딩 가이드 비유 — 커스텀 에이전트 대신 지식 패키징

Building a skill for an agent is like putting together an onboarding guide for a new hire.

Instead of building fragmented, custom-designed agents for each use case, anyone can now specialize their agents with composable capabilities by capturing and sharing their procedural knowledge.

스킬의 해부 — SKILL.md 하나가 최소 단위

At its simplest, a skill is a directory that contains a SKILL.md file. This file must start with YAML frontmatter that contains some required metadata: name and description. At startup, the agent pre-loads the name and description of every installed skill into its system prompt.

Claude already knows a lot about understanding PDFs, but is limited in its ability to manipulate them directly (e.g. to fill out a form). This PDF skill lets us give Claude these new abilities.

Progressive disclosure — 목차, 챕터, 부록의 3단계

This metadata is the first level of progressive disclosure: it provides just enough information for Claude to know when each skill should be used without loading all of it into context. ... If Claude thinks the skill is relevant to the current task, it will load the skill by reading its full SKILL.md into context.

Like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix, skills let Claude load information only as needed

By moving the form-filling instructions to a separate file (forms.md), the skill author is able to keep the core of the skill lean, trusting that Claude will read forms.md only when filling out a form.

the amount of context that can be bundled into a skill is effectively unbounded.

컨텍스트 윈도우에서 벌어지는 일 — 트리거 시퀀스

To start, the context window has the core system prompt and the metadata for each of the installed skills, along with the user’s initial message

Claude triggers the PDF skill by invoking a Bash tool to read the contents of pdf/SKILL.md

Finally, Claude proceeds with the user’s task now that it has loaded relevant instructions from the PDF skill.

코드 실행 결합 — 토큰 생성보다 결정론적 스크립트

Large language models excel at many tasks, but certain operations are better suited for traditional code execution. For example, sorting a list via token generation is far more expensive than simply running a sorting algorithm. Beyond efficiency concerns, many applications require the deterministic reliability that only code can provide.

Claude can run this script without loading either the script or the PDF into context. And because code is deterministic, this workflow is consistent and repeatable.

스킬 개발 사이클 — 평가에서 시작해 Claude와 함께 반복

Start with evaluation: Identify specific gaps in your agents’ capabilities by running them on representative tasks and observing where they struggle or require additional context. Then build skills incrementally to address these shortcomings.

When the SKILL.md file becomes unwieldy, split its content into separate files and reference them. If certain contexts are mutually exclusive or rarely used together, keeping the paths separate will reduce the token usage.

Pay special attention to the name and description of your skill. Claude will use these when deciding whether to trigger the skill in response to its current task.

As you work on a task with Claude, ask Claude to capture its successful approaches and common mistakes into reusable context and code within a skill. ... This process will help you discover what context Claude actually needs, instead of trying to anticipate it upfront.

보안 — 스킬은 곧 새 권한, 출처를 의심하라

malicious skills may introduce vulnerabilities in the environment where they’re used or direct Claude to exfiltrate data and take unintended actions.

We recommend installing skills only from trusted sources. When installing a skill from a less-trusted source, thoroughly audit it before use.

pay attention to instructions or code within the skill that instruct Claude to connect to potentially untrusted external network sources.

미래 — 에이전트가 스스로 스킬을 만들고 다듬는다

We’ll also explore how Skills can complement Model Context Protocol (MCP) servers by teaching agents more complex workflows that involve external tools and software.

Looking further ahead, we hope to enable agents to create, edit, and evaluate Skills on their own, letting them codify their own patterns of behavior into reusable capabilities.

Skills are a simple concept with a correspondingly simple format. This simplicity makes it easier for organizations, developers, and end users to build customized agents and give them new capabilities.