agent-skills를 팀 단위로 운영하면 저장소 안의 SKILL.md, 급히 만든 Python 브리지, 사내 패키지로 배포한 정식 스킬이 동시에 필요해진다. Microsoft Agent Framework의 Python API는 서로 다른 스킬 원천(source)을 SkillsProvider 하나로 합쳐, 에이전트 코드가 스킬 출처를 구분하지 않게 만든다.

세 가지 스킬 형태

1. 파일 기반 스킬을 연결한다

SKILL.md와 보조 스크립트가 있는 디렉터리는 SkillsProvider.from_paths()로 읽는다. 스킬이 스크립트를 실행한다면 실행기에서 시간 제한, 로그, 입력 검증을 반드시 적용한다.

from pathlib import Path
from agent_framework import SkillsProvider

skills_provider = SkillsProvider.from_paths(
    skill_paths=Path(__file__).parent / "skills",
    script_runner=my_sandboxed_runner,
)

단순 subprocess.run() 예제는 학습에는 충분하지만, 운영 환경의 임의 코드 실행 경계로 사용해서는 안 된다.

2. 재사용 클래스 스킬을 만든다

사내 공통 기능은 ClassSkill 하위 클래스로 묶을 수 있다. metadata와 instruction뿐 아니라 읽을 리소스와 실행할 스크립트도 데코레이터로 선언한다.

from agent_framework import ClassSkill, SkillFrontmatter

class BenefitsEnrollmentSkill(ClassSkill):
    def __init__(self):
        super().__init__(frontmatter=SkillFrontmatter(
            name="benefits-enrollment",
            description="복지 플랜 등록 요청을 처리한다.",
        ))

    @ClassSkill.script(description="직원을 선택한 플랜에 등록한다.")
    def enroll(self, employee_id: str, plan_code: str) -> str:
        return hr_client.enroll(employee_id, plan_code)

이 방식은 기능과 문서를 패키지 버전에 함께 묶을 수 있어, 여러 에이전트 서비스가 같은 스킬 구현을 사용해야 할 때 적합하다.

3. 원천을 하나의 provider로 조합한다

AggregatingSkillsSource가 여러 원천을 합치고, DeduplicatingSkillsSource가 같은 이름의 스킬 충돌을 처리한다. 먼저 넣은 원천이 우선권을 가지므로, 저장소 로컬 스킬로 배포 패키지를 임시 override할 수도 있다.

from agent_framework import (
    AggregatingSkillsSource,
    DeduplicatingSkillsSource,
    FileSkillsSource,
    InMemorySkillsSource,
    SkillsProvider,
)

provider = SkillsProvider(
    DeduplicatingSkillsSource(
        AggregatingSkillsSource([
            FileSkillsSource(Path("skills"), script_runner=my_sandboxed_runner),
            InMemorySkillsSource([BenefitsEnrollmentSkill(), time_off_bridge]),
        ])
    )
)

운영 체크리스트

• 스킬 이름 충돌 시 어떤 원천이 우선하는지 테스트로 고정한다.
• 임시 인라인 스킬에는 교체할 패키지와 제거 조건을 기록한다.
• 스크립트 실행은 승인, 샌드박스, 시간 제한, 감사 로그를 적용한다.
• 배포 전에 “사용해야 하는 요청”과 “사용하면 안 되는 요청” 모두로 라우팅을 평가한다.

파일 스킬은 팀의 절차를 버전 관리하기 좋고, 클래스 스킬은 제품 기능을 배포하기 좋다. 둘을 조합하면 에이전트의 행동 규칙과 실제 실행 기능을 같은 provider 아래에서 단계적으로 확장할 수 있다.

참고 자료

• Agent Skills for Python: File, Code, and Class – Composed in One Provider – Microsoft Agent Framework Blog (2026-05)