지난주 저는 검증 게이트 뒤에서 스스로 도구를 작성하는 데스크톱 AI 에이전트인 AMA-teras에 대해 글을 썼습니다. 이번 주에 이 에이전트는 에이전트 스킬을 위한 오픈 표준인 SKILL.md를 양방향으로 말하는 법을 배웠습니다. 이것이 무엇을 의미하는지, 왜 이것이 단일 기능보다 더 중요하다고 생각하는지, 그리고 저를 놀라게 했던 구현 세부 사항에 대해 설명하겠습니다.

30초 요약 (The 30-second context)

SKILL.md는 내부 형식으로 시작하여 현재 Claude Code, Codex CLI, Cursor, Gemini CLI 등 30개 이상의 코딩 에이전트가 지원하는 오픈 표준이 되었습니다. 스킬은 단순히 폴더일 뿐입니다:

my-skill/
 SKILL.md # 프론트매터 (frontmatter) (이름, 설명) + 지침 (instructions)
 templates/… # 선택적 리소스 (optional resources)

영리한 부분은 _점진적 공개 (progressive disclosure)_입니다. 에이전트는 작업에 실제로 해당 스킬이 필요할 때까지 한 줄짜리 설명만 읽고, 그 후에 전체 지침을 로드합니다. 여러분의 컨텍스트 윈도우 (context window)는 깨끗하게 유지되며, 에이전트는 여전히 라이브러리 카드를 가지고 있는 것과 같습니다.

현재 1,000개 이상의 스킬이 포함된 커뮤니티 컬렉션이 존재합니다. 이는 이번 주 전까지 제 에이전트가 손댈 수 없었던 방대한 패키지화된 전문 지식입니다.

소비하기: 두 개의 도구, 약 150줄

소비(consuming) 측면은 거의 부끄러울 정도로 작았습니다. 두 개의 도구뿐입니다:

• skill_list — 스킬 디렉토리를 탐색하고, 프론트매터 (frontmatter)를 파싱하여 name: description 라인만 반환합니다.
• skill_use {name} — 하나의 스킬에 대한 전체 SKILL.md 본문을 반환합니다.

우선순위 순서에 따른 디렉토리: 앱에 번들로 포함된 스킬, 그다음 사용자가 생태계의 무엇이든 넣어두는 userData/skills/입니다. 이름이 같은 충돌이 발생한다면? 번들된 것이 승리합니다. 이는 우리의 플러그인 로더 (plugin loader)가 이미 작동하는 방식을 반영합니다. 사용자가 설치한 아티팩트 (artifact)가 내장된 것을 조용히 대체해서는 안 됩니다. 이는 실제 공격을 차단하는 작은 규칙입니다:

const NAME_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/i;

스킬 이름은 사용자가 제어할 수 있는 유일한 경로 세그먼트(path segment)이며, .., /, 또는 \를 포함할 수 없습니다. fs (File System)를 건드리기 전에 그 _형태 (shape)_를 검증하는 것이 사후에 경로를 정규화 (normalizing)하는 것보다 더 간단하고 엄격합니다.

2. 도구 설명 (tool description)이 진정한 UX입니다. 에이전트는 skill_list의 출력값을 읽음으로써 skill_use를 호출할지 여부를 결정합니다. 따라서 이 리스트는 의도적으로 이름과 한 줄 요약만을 반환합니다. 만약 전체 본문을 반환했다면, 단 하나의 스킬을 사용하기 위해 모든 스킬의 컨텍스트 비용 (context cost)을 지불해야 했을 것입니다. 표준의 점진적 공개 (progressive-disclosure) 개념은 도구가 이를 준수할 때만 유효합니다.

생성 (Producing): 반대 방향이 흥미로워지는 지점입니다

AMA-teras는 이미 자기 진화 파이프라인 (self-evolution pipeline)을 갖추고 있었습니다. 에이전트에게 능력이 부족할 때, 에이전트는 자신을 위한 새로운 도구를 작성하며, 이 도구는 로드되기 전에 반드시 타입 체크 (typecheck) → 단위 테스트 (unit tests) → 실제 스모크 테스트 (smoke run) → 인간의 승인 (human approval) 과정을 통과해야 합니다. (제 에이전트가 작동하지 않는 작업에 대해 성공했다고 주장하는 것을 본 후, 왜 그래야 하는지에 대해 글을 쓴 적이 있습니다.)

이제 이러한 관문들을 통과한 모든 도구는 다음과 같이 내보내기 (export) 될 수 있습니다:

exported-tool/
 SKILL.md # 설명 + 실행 방법 + 검증 증거
 run.mjs # esbuild로 번들링된, 독립 실행형 러너 (self-contained runner)
...

node run.mjs '{"numbers":[1,2,39]}'는 AMA-teras 없이도 Node가 설치된 어떤 머신에서든 작동합니다. SKILL.md에는 코드가 어떤 관문을 언제 통과했는지가 정직하게 기록됩니다. 만약 증거가 없다면, 대신 그렇게 명시합니다.

이 기능에 대한 테스트는 그 어떤 것도 모킹 (mock)하지 않습니다. 실제 플러그인을 번들링하고, 실제 Node 바이너리로 run.mjs를 실행하며, 표준 출력 (stdout)을 통해 검증합니다. 만약 내보내기 형식이 부패한다면 CI (지속적 통합)가 이를 잡아낼 것입니다. 왜냐하면 "이식 가능한 (portable)" 형식에 있어 최악의 결과는 작성자의 머신에서만 작동하는 번들을 배포하는 것이기 때문입니다.

왜 굳이 표준을 따르려 하는가?

그 대안은 제가 이 프로젝트를 만든 이유인, 바로 그 상황이기 때문입니다.

모든 주요 벤더(Vendor)는 에이전트 SDK를 출시하며, 모든 SDK는 사용자의 도구(Tools), 메모리(Memory), 워크플로(Workflows)가 자신들의 런타임(Runtime) 내에 존재한다고 조용히 가정합니다. '폴더로서의 스킬(Skills-as-folders)' 방식은 그 반대의 도박입니다. 전문 지식을 무엇이든 읽을 수 있는 일반 파일로 만들고, 그것을 작성한 사람이 소유하도록 하는 것입니다. 이제 제 에이전트는 Claude Code를 위해 작성된 스킬을 사용할 수 있으며, 제 에이전트 내부에서 탄생한 도구는 Codex를 사용하는 사람에게 서비스를 제공할 수 있습니다. 어느 쪽도 벤더에게 허락을 구하지 않았습니다.

개인 오픈 소스 프로젝트로서 표준을 채택하는 것은 더 이기적인 이유로 새로운 표준을 발명하는 것보다 낫습니다. 저는 생태계의 성장을 공짜로 얻고, 생태계는 표준을 정직하게 유지해 줄 독립적인 구현체를 하나 더 얻게 되기 때문입니다.

출시된 기능

• 20개의 번들 스킬(TDD 규율, 보안 리뷰, 프론트엔드 디자인, Playwright E2E, pdf/docx/xlsx/pptx 처리 등)이 포함된 skill_list / skill_use — 모두 독창적인 작성물입니다.
• 게이트 검증(Gate-verified)된 도구들을 SKILL.md + 실행 가능한 번들 + 증거(Evidence) 형태로 내보내기 기능
• 영어 UI(단계적 출시) 및 실험적인 Mac/Linux 빌드 — 앱 자체가 Windows 및 일본어 전용이라면 벤더 독립성이라는 주장이 공허하게 들릴 것이기 때문입니다.

이 프로젝트는 AGPL 라이선스이며, 사용자의 기기에서 실행됩니다. 또한 설정 변경만으로 Anthropic / OpenAI / 오픈 웨이트(Open-weight) 모델 간을 전환할 수 있습니다: github.com/moriwo-dev-ai/ama-teras

만약 여러분이 어떤 에이전트를 위해 스킬을 유지 관리하고 있다면 — 그 스킬들을 다른 런타임에 넣었을 때 무엇이 망가지는지 진심으로 알고 싶습니다. 그러한 상호 운용성 마찰(Interop friction)이야말로 가장 유용한 버그 리포트입니다.