이 페이지는 영어 문서의 번역입니다. 명령, 식별자, 예제는 그대로입니다. 런타임 7.24.4 · SDK 2.6.7. 영어 원문

스킬과 플러그인 카탈로그

상태: 활성 범위: 공개, 현재 상태 최종 검토: 2026-08-12 담당: AX Code 런타임

내장 스킬을 찾는 레지스트리와 프로젝트 스킬을 추가하는 방법입니다.

기본 / 메뉴는 제어 평면입니다(/plan, /review, /debug, /status, /model). 더 오래된 내장 스킬은 에이전트 전용으로 남습니다(스킬 도구). 백엔드 신뢰성 팩도 슬래시 명령으로 나열됩니다.

내장 스킬(`packages/ax-code/skills/` 아래에 제공)

스킬	목적	슬래시
`debug-n-fix`	검증과 함께 디버그한 다음 수정	`/debug` 사용
`debug-only`	코드를 바꾸지 않는 조사	에이전트 전용
`improve-overall`	넓은 품질 개선	에이전트 전용
`improve-security`	보안에 초점을 둔 개선	에이전트 전용
`mcp`	MCP 설정 안내	`/mcp` 사용
`run`	앱을 실행하고 관찰	에이전트 전용
`simplify`	최근에 바뀐 코드를 조임	에이전트 전용
`verify`	런타임 검증 보고서	에이전트 전용
`verified-change`	실패 신호가 있은 뒤에만 편집하고, 같은 검사를 다시 실행	`/verified-change`
`safe-db-migration`	롤백 메모와 함께 스키마 변경을 확장/채움/축소	`/safe-db-migration`
`api-contract`	추가를 우선하는 공개 API / 스키마 진화	`/api-contract`
`incident-observability`	패치 전에 증거를 우선하는 장애 진단	`/incident-observability`
`auth-boundaries`	인증/인가, 테넌트 격리, 부정 시험	`/auth-boundaries`
`queue-worker`	멱등한 대기열/워커 변경과 중복 전달	`/queue-worker`
`ruby-on-rails`	Rails 프로세스를 부팅하지 않는 Rails 관례	에이전트 전용

스킬은 SKILL.md을 사용하며, YAML 프론트매터는 name, description, 선택적 paths, allowed-tools입니다.

프로젝트 스킬

다음 중 어디에든 스킬을 둡니다.

.ax-code/skill/<name>/SKILL.md 또는 .ax-code/skills/<name>/SKILL.md
.agents/skills/<name>/SKILL.md (Agents / Codex 호환)
.claude/skills/<name>/SKILL.md (Claude Code 호환)
.opencode/skills/<name>/SKILL.md

나열하고 검증합니다.

ax-code            # TUI skill dialog
# or use the skill tool from a session

호출 제어

AX Code는 스킬을 발견할 때 이 선택적 제어를 읽습니다.

위치	필드	효과
`SKILL.md` 프론트매터	`disable-model-invocation: true`	명시적인 `/skill-name` 명령은 유지하지만, 모델 발견과 직접적인 모델 도구 적재에서는 스킬을 제외합니다.
`SKILL.md` 프론트매터	`user-invocable: false`	슬래시 명령에서 스킬을 뺍니다. 따로 끄지 않으면 모델 호출은 계속 사용할 수 있습니다.
형제 `agents/openai.yaml`	`policy.allow_implicit_invocation: false`	`.agents/skills`을 통해 가져온 스킬을 포함해, 명시적인 슬래시 호출을 요구합니다.

YAML 불리언 true과 false를 사용합니다. 제어가 없으면 기본값이 유지됩니다. 여러 출처가 다르면 더 제한적인 선언이 이깁니다. 잘못된 제어 유형이나 잘못된 사이드카 정책은 두 호출 모드를 모두 끄고, 스킬 목록과 런타임 로그에 호출 진단을 냅니다. 스킬을 쓰기 전에 메타데이터를 고칩니다. 선택적 사이드카는 64 KiB보다 작아야 합니다. 거기서는 YAML 문서 구분자와 별칭을 지원하지 않습니다.

이 제어는 기존 에이전트 권한과 독립적으로 스킬 호출을 다스립니다. 수동 전용 스킬을 자연어로 언급해도 모델이 그것을 불러올 권한은 생기지 않습니다. 슬래시 명령을 호출합니다. 선언된 allowed-tools은 워크플로 지시로 남으며 권한을 부여하지 않습니다.

제한된 발견

모델은 처음에 전체 지시가 아니라 스킬 요약을 받습니다. 시스템 프롬프트와 도구 설명의 각 스킬 메타데이터 블록에는 8,000자 예산이 있습니다. 항목을 빼기 전에 설명을 줄입니다. 목록이 여전히 예산을 넘으면 파일과 일치하는 추천이 우선합니다. 생략 알림은 요약을 더 가져오는 방법을 설명합니다. 이것은 문자 한도이지, 토큰 수나 성능 보장이 아닙니다.

skill 도구에는 서로 배타적인 두 모드가 있습니다.

{"name":"api-contract"}는 기존 권한 검사를 통해 스킬을 불러옵니다.
{"query":"database"}은 스킬 본문을 불러오지 않고 자격이 있는 이름과 설명을 검색합니다.
{"query":"","offset":20}는 이전 결과의 정확한 nextOffset를 사용해 목록을 이어갑니다.

검색은 리터럴이고 대소문자를 구분하지 않습니다. 빈 질의는 자격이 있는 스킬을 나열합니다. 없을 때까지 nextOffset을 따릅니다. 수동 전용 스킬과 권한이 거부된 스킬은 모델 발견에서 제외됩니다. 너무 큰 개별 메타데이터 항목은 알림과 함께 건너뜁니다. 이름과 소스 우선순위는 바뀌지 않습니다.

플러그인

ax-code.json에서 플러그인을 구성합니다.

{
  "plugin": ["file:///absolute/path/to/plugin.js"]
}

플러그인은 @ax-code/plugin 훅(tool.execute.before, tool.execute.after, shell.env, 인증 등)을 구현합니다.

콜백 수명

플러그인 팩토리는 입력에서 선택적 lifecycle를 받습니다. 인스턴스가 폐기되거나 플러그인이 퇴역하면 lifecycle.signal이 중단됩니다. 타이머, 감시자, 구독은 lifecycle.onDispose(cleanup)로 등록합니다. 반환된 함수는 그 정리를 등록 해제합니다. 등록은 최대 한 번 실행됩니다. 폐기 뒤에 등록하면 정리가 즉시 시작됩니다. 정리 콜백은 등록의 역순으로 시작하며, 각각 1초 예산이 있고 동시에 끝날 수 있습니다.

변환 훅은 선택적 세 번째 인수 { signal }를 받습니다. 구성과 이벤트 훅은 그것을 두 번째 인수로 받습니다. 이 신호는 콜백이 대기 중인 동안 작업을 취소합니다. 콜백 하나를 넘는, 플러그인이 소유한 작업에는 lifecycle.signal을 사용합니다. 중단 가능한 연산에 신호를 전달합니다. 초기화, 구성, 이벤트, 변환 콜백에는 15초 기한이 있습니다. 시간 초과는 그 인스턴스의 플러그인을 퇴역시키고 수명을 중단합니다. 기존 팩토리와 인수 두 개의 변환 훅은 계속 동작합니다. 사용자 정의 도구 실행과 대화형 인증은 기존 실행 계약을 유지합니다.

변환 입력은 일반 데이터의 읽기 전용 관찰입니다. 출력 초안을 바꾸고 반환하기 전에 모든 변경을 기다립니다. 성공한 출력 변경은 등록 순서대로 보이게 됩니다. 실패하거나 늦은 변경은 버려집니다. 이벤트 페이로드 변경은 게시되지 않습니다. 권한 거부는 거부로 남고, 실패하거나 퇴역한 권한 훅은 거부가 이미 있지 않으면 묻기를 요구합니다.

배열과 일반 객체는 런타임 상태에서 분리됩니다. 스키마, 함수, 클래스 인스턴스는 신원을 유지하며 읽기 전용으로 취급해야 합니다. 플러그인은 런타임 프로세스에서 실행되는 신뢰된 JavaScript로 남습니다. 취소는 협력적이며 동기적인 무한 루프를 멈추거나 외부 효과를 되돌릴 수 없습니다.

훅 팩

훅에서 다섯 개의 공식 수명 주기 팩(format-after-edit, block-force-push, require-tests-on-stop, protect-env-files, log-bash-commands)을 보십시오.

평가 하네스

에이전트 런타임 게이트 스위트와 다중 모드 앙상블 정책 스위트를 실행합니다.

cd packages/ax-code
pnpm exec vitest run test/harness/agentic-runtime-eval.test.ts
pnpm exec vitest run test/harness/multi-mode-ensemble-eval.test.ts

로컬/클라우드/하이브리드/council/arena는 실행 모드도 보십시오.