스킬 추가하기

스킬에는 두 종류가 있습니다. 내장 스킬은 이 저장소에서 작성해 바이너리에 컴파일하는 SKILL.md 패키지입니다. 외부 스킬은 명령이나 프롬프트로 설치하는 서드파티 패키지로, 코드 변경이 필요 없습니다. 이 페이지에서는 둘 다 다룹니다.

내장 스킬 추가하기

내장 스킬은 apps/agent/src/skills/builtin/<id>/ 아래의 SKILL.md 패키지입니다. 로더(loadBuiltinPackageSkills)가 자동으로 발견하고 requires_env로 게이팅하며, 턴마다 agent에 제공합니다. index.ts를 편집할 필요는 없습니다. 발견은 builtin/의 바로 아래 하위 디렉터리만 훑기 때문에, 패키지는 한 단계 아래에 두어야 합니다(더 깊이 중첩된 패키지는 조용히 건너뜁니다).

최소 예시

apps/agent/src/skills/builtin/my-new-skill/SKILL.md를 만듭니다.

---
name: my-new-skill
description: "Pull research data from My Provider. Use when the user asks about X, Y, or Z."
metadata:
  minara:
    id: research.my_provider
    priority: 50
    tool_names: [my_provider_search, my_provider_detail]
    requires_env: [MY_PROVIDER_API_KEY]
    routing:
      keywords: ["my provider", X, Y]
---

You are the My Provider research skill. When the user asks about X, Y, or Z,
call `my_provider_search` and summarize the results.

Prefer fresh data over cached. Cite source URLs.

로더는 부팅 시 이 frontmatter를 DomainSkill로 파싱합니다. 최상위 name + description은 skill-creator 표준을 따르고, Minara 고유 항목은 모두 metadata.minara.* 아래에 둡니다. 깊은 내용은 references/<area>.md로 나누고(모델이 필요할 때 읽습니다), frontmatter로 깔끔하게 표현하기 어려운 구조화 필드는 SKILL.config.json 사이드카에 넣습니다.

관례

본문: 소프트 상한 약 5000자. 긴 안내는 references/<area>.md로 나누고 패키지 본문을 부풀리지 마세요.
description: 내장 스킬은 200자까지. "무엇을 하는지"와 "언제 쓰는지"를 충실히 담은 문장을, 강하고 충돌하지 않는 키워드와 함께 써서 라우터가 드러낼 수 있게 합니다.
tool_names: 도구 레지스트리에서 해석되어야 합니다. 활성화 화이트리스트를 구성하므로 목록을 최소로 유지하세요.
requires_env: 나열된 변수 중 하나라도 없으면 레지스트리가 그 스킬을 숨깁니다. 덕분에 모든 키를 설정하지 않고도 agent를 실행할 수 있습니다.
위험: 스킬 자체는 위험 등급을 갖지 않습니다. 각 도구가 자신의 PermissionTier를 선언하고, 등급 게이트가 도구 호출 계층에서 확인을 강제합니다.
카탈로그 가드: 같은 커밋에서 새 id를 builtin-catalog-guard.test.ts의 EXPECTED_IDS에 추가합니다.

참고 예시

minara-perps/ (도구 중심)
deep-research/ (프롬프트 중심)
analysis/ (방법론 렌즈를 references/로 분할)

인라인 TS 예외

내장 스킬 하나는 SKILL.md 패키지가 아니라 인라인 TypeScript로 제공됩니다. automation이며, 그 프롬프트는 실행 시 실시간 Custom Agents 카탈로그를 렌더링합니다. apps/agent/src/skills/builtin/index.ts의 BUILTIN_SKILLS로 등록합니다. 내용이 정말로 실행 시 동적일 때만 인라인 TS를 쓰고, 프롬프트가 짧다는 이유로는 쓰지 마세요.

외부 스킬 추가하기

외부 스킬은 apps/agent/src/skills/external/* 아래에 있으며 .minara-skill.json 매니페스트를 가진 벤더 제공 SKILL.md 패키지입니다. 작성하는 것이 아니라 설치합니다.

minara skills add <git-url> [--subpath <dir>] [--id <id>]

설치는 패키지를 클론하고 라이선스를 감지해 .minara-skill.json에 기록하며, 독점 라이선스 콘텐츠는 거부합니다. 이후 buildExternalDomainSkills()가 부팅 시 SKILL.md frontmatter에서 DomainSkill을 구성하므로, 외부 스킬은 내장과 동일한 레지스트리와 등급 게이트를 거칩니다.

채팅에서 프롬프트로 설치하는 것을 포함한 사용자 대상 전체 흐름은 스킬 설치를 참고하세요.

상류가 유지하는 서드파티 패키지(coingecko, hyperliquid 등), 비 TypeScript 참고 구현(shell, Python), 또는 agent 바이너리와 독립적으로 업데이트되는 콘텐츠가 필요할 때 외부 스킬을 씁니다. 같은 기능이 두 형태로 모두 있을 때는 내장을 우선합니다.

기여 검증하기

패키지 로딩, 선언한 ID, 라우팅 문구, 참조한 모든 도구 이름을 테스트합니다. 프롬프트 중심 스킬에는 언제 활성화되고 어떤 근거를 요구하는지 증명하는 집중 동작 테스트나 Eval도 추가하세요.

pnpm --filter @minara/agent exec vitest run tests/unit/skills/builtin-catalog-guard.test.ts
pnpm --filter @minara/agent typecheck
pnpm --filter @minara/agent build

스킬이 공개 사용자 흐름을 추가한다면 관련 기능 또는 사용 문서를 네 언어로 수정합니다.