Skills

이 문서에서는 Skills capability를 소개해요. Agent Skills를 사용해 모든 지침을 초기 프롬프트에 넣지 않고 에이전트에 특화된 지침을 제공해요. 하나 이상의 스킬 라이브러리를 가리키면, 모델은 먼저 각 스킬의 이름과 설명을 보고 유용한 스킬에 대해 load_capability 도구를 호출해 그 지침을 받을 수 있어요.

출처: 문서

본문

Agent Skills를 사용해 모든 지침을 초기 프롬프트에 넣지 않고 에이전트에 특화된 지침을 제공해요.

Skills를 하나 이상의 스킬 라이브러리에 지정하세요. 모델은 먼저 각 스킬의 이름과 설명을 봐요. 스킬이 유용하면 모델이 Pydantic AI의 load_capability 도구를 호출해 해당 스킬의 지침을 받을 수 있어요.

소스

Pydantic AI Harness가 0.x 릴리스인 동안에는 minor 릴리스 사이에 API가 바뀔 수 있어요. 그럴 때는 deprecation 경고와 릴리스 노트 마이그레이션 안내가 (당신이나 당신의 에이전트에게) 정확히 업그레이드 방법을 알려줘요. 버전 정책을 참고하세요.

Installation

YAML frontmatter 지원을 위해 skills extra를 설치하세요:

Terminal

pip install "pydantic-ai-harness[skills]"

Terminal

uv add "pydantic-ai-harness[skills]"

Quick start

스킬 라이브러리를 만드세요:

.agents/skills/
  code-review/
    SKILL.md

스킬의 설명과 지침을 추가하세요:

---
name: code-review
description: Review a change for correctness and repository conventions.
---

Inspect the change and report findings by severity.

그 다음 라이브러리를 에이전트에 추가하세요:

from pydantic_ai import Agent
from pydantic_ai_harness import Skills

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    capabilities=[Skills('.agents/skills')],
)

Skills는 .agents, .claude, 또는 홈 디렉터리를 자동으로 검색하지 않아요. 로드하려는 각 라이브러리를 전달하세요.

Note

Skills는 SKILL.md에서 지침을 로드해요. 번들 리소스는 로드하지 않으며 스크립트도 실행하지 않아요.

How it works

Skills(...)가 구성되면 다음을 해요:

구성된 각 라이브러리의 직접 자식 디렉터리를 스캔.
선택된 SKILL.md 파일을 검증.
선택된 각 스킬에 대해 하나의 deferred Pydantic AI capability를 생성.

모델은 처음에 스킬 이름과 설명만 봐요. 스킬을 로드하면 # Skill: <name> 머리말로 시작하는 지침과 그 Markdown 본문이 다른 on-demand capabilities와 같은 load_capability 흐름으로 실행에 추가돼요.

발견은 구성 시 한 번 일어나요. 카탈로그와 파싱된 지침은 스냅샷이에요. 라이브러리를 다시 스캔하려면 새 Skills 인스턴스를 구성하세요.

Choose which skills to expose

기본적으로 발견된 모든 스킬이 포함돼요. 특정 에이전트의 카탈로그를 바꾸려면 include 또는 exclude를 사용하세요:

from pydantic_ai_harness import Skills

review_skills = Skills(
    '.agents/skills',
    include=['code-review'],
)

release_skills = Skills(
    '.agents/skills',
    exclude=['code-review'],
)

Configuration

Catalog에 들어있는 skills

둘 다 없음

발견된 모든 스킬

include=['a', 'b']

a와 b만

include=[]

스킬 없음

exclude=['a', 'b']

a와 b 제외한 전부

exclude=[]

발견된 모든 스킬

include와 exclude는 함께 사용할 수 없어요. 생성자 오버로드가 타입이 지정된 코드에서 이를 잡고, 런타임 검증이 agent spec과 타입 없는 호출자를 다뤄요. 알 수 없는 이름도 구성 중에 실패해요.

선택은 frontmatter가 파싱되기 전에 일어나요. 선택되지 않은 스킬은 해당 Skills 인스턴스에 지침이나 frontmatter 검증 오류를 추가하지 않아요.

이 옵션들은 카탈로그 노출을 제어해요. 파일시스템 권한이나 접근 제어 경계가 아니에요.

Skills는 프로세스 파일시스템을 통해 구성된 경로를 읽어요. 상대 경로는 프로세스 작업 디렉터리에서 해석돼요. 디렉터리 경로는 발견이 시작되는 위치를 선택할 뿐, containment 경계를 만들지 않으며, 일반 파일시스템 심볼릭 링크 해석이 적용돼요. 파일시스템 containment가 필요하다면 에이전트를 적절히 제한된 환경에서 실행하세요.

선택된 SKILL.md 본문은 모델 지침이 돼요. 신뢰하는 소스에서만 라이브러리를 로드하고, 노출하기 전에 저장소 제공 스킬을 검토하세요.

Skill format

SKILL.md를 포함한 각 직접 자식 디렉터리는 스킬이에요:

.agents/skills/
  code-review/
    SKILL.md
  release-notes/
    SKILL.md

로더는 SKILL.md의 다음 부분들을 사용해요:

Part

Requirement

name

선택적. 기본값은 부모 디렉터리 이름. 제공된다면 유니코드 정규화 후 디렉터리와 일치해야 해요.

description

필수이며 비어 있지 않아야 해요. Agent Skills 한도는 1,024자이며, 더 긴 설명은 경고와 함께 로드돼요. 이는 초기 카탈로그에 나타나요.

Markdown body

선택적. 생성된 # Skill: <name> 머리말 아래에 로드돼요.

스킬 이름과 include 또는 exclude 값은 매칭 전 유니코드 NFKC로 정규화돼요. 정규화된 이름은 단일 하이픈으로 구분된 최대 64개의 소문자 유니코드 문자 또는 숫자를 포함할 수 있어요. 하이픈으로 시작하거나 끝날 수 없어요.

직접 자식만 발견돼요. 예를 들어 code-review/references/SKILL.md는 또 다른 스킬을 만들지 않아요. 일반 파일과 SKILL.md가 없는 자식 디렉터리는 무시돼요.

여러 라이브러리를 전달할 수 있어요:

from pydantic_ai_harness import Skills

skills = Skills([
    '.agents/skills',
    'company/skills',
])

선택된 스킬 이름은 그 라이브러리들에 걸쳐 유일해야 해요. 같은 해석된 라이브러리에 대한 반복 참조는 한 번 스캔돼요.

Bundled files are not loaded

Agent Skill 패키지에는 references/, assets/, scripts/ 같은 디렉터리가 포함될 수 있어요. Skills는 그러한 파일을 열거, 읽기, 실행하지 않아요.

${CLAUDE_SKILL_DIR} 같은 상대 경로와 자리 표시자는 로드된 지침에서 그대로 남아요. Skills는 이를 해석하는 모델이 보는 경로를 제공하지 않아요.

Skills는 또한 모델이 보는 FileSystem 또는 Shell capability에서 접근을 추론하지 않아요. 어느 capability를 추가하든 Skills가 읽는 파일은 바뀌지 않아요.

Compatibility with existing skill libraries

이식 가능한 name, description, Markdown 지침이 지원돼요. name은 생략하고 디렉터리에서 파생할 수 있어요.

다음 동작 필드는 호환성을 위해 받아들여지지만, 그 동작은 구현되지 않아요:

agent, allowed-tools, argument-hint, arguments, context, dependencies,
disable-model-invocation, disallowed-tools, effort, hooks, model, paths, shell,
tools, user-invocable, when_to_use

선택된 스킬이 이 필드 중 하나를 사용하면 구성이 하나의 통합 UserWarning을 발생시켜요. license, compatibility, metadata 같은 필드는 런타임 동작을 바꾸지 않고 받아들여져요. 다른 알 수 없는 비동작 필드도 받아들여져요.

Use an agent spec

Skills는 Pydantic AI의 YAML 및 JSON agent spec과 함께 동작해요:

model: anthropic:claude-sonnet-4-6
capabilities:
  - Skills:
      directories: .agents/skills
      include:
        - code-review
        - release-notes

spec을 로드할 때 Skills를 등록하세요:

from pydantic_ai import Agent
from pydantic_ai_harness import Skills

agent = Agent.from_file('agent.yaml', custom_capability_types=[Skills])

skills extra는 PyYAML을 설치해요. 이 패키지는 SKILL.md frontmatter와 YAML agent spec을 파싱해요.

Define capabilities in Python

지침이나 도구가 SKILL.md 패키지 대신 Python으로 정의된다면 Pydantic AI의 core Capability를 사용하세요:

from pydantic_ai.capabilities import Capability

refunds = Capability(
    id='refunds',
    description='Use for refund policy questions.',
    instructions='Check the refund policy before answering.',
    defer_loading=True,
)

Skills는 이식 가능한 Agent Skill 패키지를 로드해요. 코드 정의 capability를 위한 core API를 대체하지 않아요.

Configuration

Skills(
    directories: str | Path | Sequence[str | Path],
    *,
    include: Collection[str] | None = None,
    exclude: Collection[str] | None = None,
)

directories는 하나의 라이브러리 경로 또는 경로 시퀀스를 받아요.
include는 명명된 스킬만 노출해요.
exclude는 카탈로그에서 명명된 스킬을 생략해요.

하나 이상의 라이브러리 디렉터리를 전달하세요. 개별 스킬 패키지 경로는 안 돼요. 잘못된 frontmatter, 유효하지 않거나 일치하지 않는 이름, 중복 선택 이름, 알 수 없는 선택, 누락된 라이브러리, 디렉터리가 아닌 라이브러리 경로는 구성 중에 실패해요.

선택된 모든 스킬은 deferred예요. 이는 Skills 동작의 일부이며 구성할 수 없어요.

API reference

Skills

Bases: AbstractCapability[AgentDepsT]

Agent Skill 지침을 deferred capabilities로 로드.

라이브러리는 구성 중에 한 번 스캔돼요. SKILL.md를 포함한 각 선택된 직접 자식은 스킬의 이름, 설명, Markdown 본문을 사용해 deferred capability가 돼요. 번들 파일은 로드되거나 실행되지 않아요. Agent Skills 한도보다 긴 설명은 보존되고 경고를 발생시켜요.

Attributes

directories

구성 중에 스캔되는 스킬 라이브러리 경로.

Type: tuple[str | Path, ...] Default: self._normalize_directories(directories)

include

노출할 정확한 스킬 이름, 또는 발견된 모든 스킬을 노출하려면 None.

Type: frozenset[str] | None Default: self._normalize_selection('include', include) if include is not None else None

exclude

deferred capability 카탈로그에서 생략할 정확한 스킬 이름.

Type: frozenset[str] Default: self._normalize_selection('exclude', exclude) if exclude is not None else frozenset()

Methods

init

def __init__(
    directories: str | Path | Sequence[str | Path],
    *,
    include: Collection[str],
    exclude: None = None,
) -> None
def __init__(
    directories: str | Path | Sequence[str | Path],
    *,
    include: None = None,
    exclude: Collection[str] | None = None,
) -> None

선택된 Agent Skills의 스냅샷을 만든다.

Returns

None

Parameters

directories : str | Path | Sequence[str | Path]

하나의 스킬 라이브러리 경로 또는 경로 시퀀스.

include : Collection[str] | None Default: None

노출할 정확한 이름. 생략하면 발견된 모든 스킬을 노출.

exclude : Collection[str] | None Default: None

생략할 정확한 이름. include와 결합할 수 없어요.

repr

def __repr__() -> str

호출자가 제어하는 Skills 구성만 표시.

Returns

str

apply

def apply(visitor: Callable[[AbstractCapability[AgentDepsT]], None]) -> None

선택된 각 스킬을 deferred leaf capability로 노출.

Returns

None

더 알아보기 (Learn more)

pydantic-ai-harness 문서

Skills

Skills

본문

Installation

Quick start

How it works

Choose which skills to expose

Skill format

Bundled files are not loaded

Compatibility with existing skill libraries

Use an agent spec

Define capabilities in Python

Configuration

Further reading

API reference

Skills

Attributes

directories

include

exclude

Methods

init

Returns

Parameters

repr

Returns

apply

Returns

더 알아보기 (Learn more)