Skills

Skill이란?

Skill은 프론트매터가 있는 마크다운 파일로, 런타임에 에이전트의 동작을 확장합니다. Skill이 할 수 있는 것:

• 시스템 프롬프트에 지시사항 추가
• 에이전트가 사용할 수 있는 도구 제한
• LLM 모델 오버라이드
• RAG 버킷을 도구로 자동 등록
• 정책 적용 (허용/차단 도구, 제약 조건)

Skill 파일 형식

YAML 프론트매터가 있는 마크다운 파일입니다:

---
name: customer-support
description: Handle customer support inquiries using the knowledge base
model: gpt-4o-mini
allowed-tools:
  - rag_search
  - web_search
blocked-tools:
  - send_email
rag: support-docs
---

You are a customer support agent. Always be polite and helpful.
Search the knowledge base before answering questions.

프론트매터 필드

필드	타입	필수	설명
name	string	Yes	kebab-case 식별자 (1-64자)
description	string	Yes	스킬 설명 (1-1024자)
model	string	No	LLM 모델 오버라이드
allowed-tools	string[]	No	이 도구들만 사용 가능
blocked-tools	string[]	No	이 도구들은 차단
procedures	string[]	No	프로시저 이름 (정책 적용)
constraints	string[]	No	제약 조건 설명 (정책 적용)
rag	string	No	버킷 이름 — RAG 도구로 자동 등록

Skill 로딩

SkillLoader로 디렉토리에서 스킬을 로딩합니다:

import { Agent, loadSkills } from "@schift-io/sdk";

const loader = await loadSkills("./skills");

const agent = new Agent({
  name: "Support Bot",
  instructions: "You are a helpful assistant.",
  skills: {
    loader,
    autoResolve: true, // 쿼리별 최적 스킬 자동 선택
  },
  transport: schift.transport,
});

자동 해결

autoResolve가 true(기본값)이면, 에이전트가 스킬 이름/설명과의 키워드 매칭으로 각 사용자 쿼리에 가장 적합한 스킬을 자동 선택합니다.

스킬이 선택되면:

1. 마크다운 본문이 에이전트 지시사항에 추가됨
2. 도구 세트가 allowed-tools / blocked-tools로 필터링됨
3. 스킬이 모델을 지정하면 LLM 모델이 오버라이드됨
4. rag 필드가 있고 transport가 가용하면 RAG 도구가 자동 등록됨

수동 스킬 접근

import { SkillLoader } from "@schift-io/sdk";

const loader = new SkillLoader("./skills");
const summaries = await loader.loadAll();
// [{ name: "customer-support", description: "..." }, ...]

const skill = await loader.get("customer-support");
console.log(skill.meta);  // SkillFrontmatter
console.log(skill.body);  // 마크다운 본문

정책 엔진

스킬이 활성화되면 PolicyEngine이 도구 제한을 적용합니다:

• 도구 호출 전: allowed-tools에 없거나 blocked-tools에 있는 도구 차단
• 도구 호출 후: 도구 결과 검증 가능 (확장 가능)

정책 위반은 policy_violation 이벤트로 발행됩니다:

agent.on("policy_violation", (event) => {
  console.warn(`차단됨: ${event.reason} (스킬: ${event.skillName})`);
});

디렉토리 구조

skills/
  customer-support.md
  legal-qa.md
  research/
    deep-research.md

로더가 재귀적으로 모든 .md 파일을 찾습니다. 파일 간 스킬 이름이 중복되면 에러가 발생합니다.