로컬 스킬 라이브러리를 에이전트용 문서로 전환하기

대부분의 에이전트 설정은 유용한 로컬 스킬 (local skills) 더미에서 시작됩니다.

그 더미는 보통 그것을 만든 사람에게는 말이 됩니다. GitHub용 스킬, 글쓰기용 스킬, 알림용 스킬, 개인정보 필터링 (privacy filtering)용 스킬, 다이어그램 생성용 스킬, 세션 로그 확인용 스킬, 캔버스 (canvases) 작업용 스킬, 새로운 스킬 생성용 스킬 등이 있는 식입니다.

문제는 나중에 미래의 에이전트가 무엇을 해야 할지 결정해야 할 때 발생합니다.

로컬 스킬 라이브러리는 "이 환경이 무엇을 할 수 있는가?"라는 질문에 답합니다.

AGENTS.md 파일은 다른 질문에 답해야 합니다:

에이전트가 각 기능 (capability)을 언제 사용해야 하는지, 무엇을 먼저 읽어야 하는지, 어떤 도구 (tools)를 호출하는 것이 안전한지, 그리고 어떤 경계 (boundaries)를 준수해야 하는지에 대한 답입니다.

그 차이는 중요합니다. 스킬로 가득 찬 디렉토리는 인벤토리 (inventory)입니다. 에이전트용 문서 (agent-ready documentation)는 운영 지도 (operating map)입니다.

이 튜토리얼은 OpenClaw 스타일의 스킬 라이브러리를 예시로 사용하지만, 동일한 패턴이 모든 로컬 에이전트 설정에 적용됩니다.

파일이 아닌 기능(capabilities)부터 시작하세요

흔히 하는 실수는 파일 시스템 순서대로 스킬을 문서화하는 것입니다.

그러면 다음과 같은 결과가 나옵니다:

- github
- writing-style-skill
- privacy-filter
...

이 목록은 기술적으로는 맞지만, 에이전트가 결정을 내리는 데 도움을 주지 못합니다.

더 나은 첫 단계는 스킬을 그것이 가능하게 하는 작업별로 그룹화하는 것입니다:

## Capability map

### Development workflows
...

이렇게 하면 라이브러리가 결정 표면 (decision surface)으로 변합니다. 에이전트는 더 이상 writing-style-skill이 에세이 초안과 관련이 있다거나, privacy-filter를 텍스트를 외부로 공유하기 전에 고려해야 한다는 점을 추론할 필요가 없습니다. 지도가 그것을 말해주기 때문입니다.

트리거 (triggers) 추가하기

각 섹션에 트리거 (triggers)가 포함되면 기능 지도 (capability map)는 훨씬 더 유용해집니다.

트리거는 에이전트가 스킬을 로드하도록 유도해야 하는 사용자 의도 (user intent)에 대한 짧은 설명입니다.

예를 들어:

## Writing and publishing

사용자가 다음과 같이 요청할 때 `writing-style-skill`을 로드합니다:
...

마지막 줄이 중요합니다. 어떤 스킬은 로컬 컨텍스트(local context)만 생성하지만, 다른 스킬은 외부 액션(external action)을 수행합니다. blog-drafter는 퍼블리싱 시스템(publishing system)에 초안을 생성하기 때문에 그 경계를 넘나듭니다. 에이전트는 이러한 작업이 무심코 일어나서는 안 된다는 점을 인지해야 합니다.

좋은 트리거(trigger)는 구체적입니다. 나쁜 트리거는 모호합니다.

나쁜 예:

콘텐츠용으로 이것을 사용하세요.

더 나은 예:

긴 글을 초안 작성하거나 수정할 때, 특히 톤(tone)과 구조(structure)가 중요할 때 이것을 사용하세요.

가장 좋은 예:

가장 좋은 버전은 사용자가 실제로 무엇이라고 말할지를 에이전트에게 알려줍니다.

가장 먼저 읽어야 할 파일을 문서화하기

많은 로컬 스킬들은 자체적인 SKILL.md를 가지고 있습니다. 에이전트는 스킬 이름만 보고 추측해서는 안 됩니다. 루트(root)에 있는 AGENTS.md는 어떤 파일이 권위 있는(authoritative) 파일인지 에이전트에게 알려주어야 합니다.

예시:

## 스킬 로딩 규칙

작업이 스킬과 일치할 때, 액션을 취하기 전에 해당 스킬의 `SKILL.md`를 읽으세요.
...

로컬 OpenClaw 스킬 세트의 경우, 스킬마다 운영 형태(operational shapes)가 다르기 때문에 이 방식이 특히 유용합니다.

작성(writing) 스킬은 주로 톤(tone) 규칙과 예시를 포함할 수 있습니다.

GitHub 스킬은 선호되는 gh 명령어와 리뷰 동작을 지정할 수 있습니다.

홈 오토메이션(home automation) 스킬은 장치별 제약 사항을 포함할 수 있습니다.

개인정보 보호(privacy) 스킬은 공유하기 전에 어떤 데이터를 필터링해야 하는지 정의할 수 있습니다.

루트 파일이 이 모든 내용을 중복해서 작성할 필요는 없습니다. 스킬 로딩을 의무적이고 예측 가능하게 만드는 것이 핵심입니다.

내부 작업과 외부 액션의 분리

에이전트 문서화는 한 가지 차이점을 매우 명확하게 구분해야 합니다:

읽기(reading), 초안 작성(drafting), 검색(searching), 정리(organizing)는 내부 액션(internal actions)입니다.

전송(sending), 게시(posting), 퍼블리싱(publishing), 삭제(deleting), 구매(buying), 메시징(messaging), 또는 실제 세계의 시스템을 변경하는 것은 외부 액션(external actions)입니다.

이 경계는 AGENTS.md의 상단 근처에 위치해야 합니다.

예시:

## 외부 액션 경계

에이전트는 자유롭게 다음을 수행할 수 있습니다:
...

OpenClaw 스타일의 환경에서, 이러한 경계(boundary)는 강력한 스킬들이 무모하게 사용되지 않으면서도 유용하게 유지될 수 있도록 합니다. 이슈(issue)를 읽는 github 스킬은 풀 리퀘스트(pull request)를 여는 스킬과는 다릅니다. 로컬에서 초안을 작성하는 blog 스킬은 외부 서비스에서 초안을 생성하는 스킬과는 다릅니다. govee나 homeconnect 스킬은 물리적 환경에 영향을 줄 수 있습니다.

이러한 차이점들을 기록하세요.

에이전트는 막연한 느낌(vibes)으로부터 사용자의 위험 모델(risk model)을 재구성할 필요가 없을 때 훨씬 더 뛰어난 성능을 발휘합니다.

각 기능(capability) 내부에 도구 경계 캡처하기

기능 맵(capability map)은 단순히 스킬이 무엇을 하는지만 말해서는 안 됩니다. 에이전트가 무엇을 하지 말아야 하는지도 말해야 합니다.

예를 들어:

## 개인정보 보호 및 비식별화 (Privacy and redaction)

사용자가 제공한 텍스트에 다음 내용이 포함될 수 있는 경우, 로컬 워크스페이스 외부로 공유하기 전에 `privacy-filter`를 사용하십시오:
...

또는 GitHub의 경우:

## GitHub 작업 (GitHub work)

저장소(repository), 이슈(issue), 풀 리퀘스트(pull request), 그리고 CI 작업에는 `github`를 사용하십시오.
...

이 부분이 많은 로컬 문서들이 놓치는 지점입니다. 그들은 도구를 어떻게 사용하는지는 기록하지만, 언제 멈춰야 하는지는 기록하지 않습니다.

시퀀싱 규칙(sequencing rules) 포함하기

어떤 스킬들은 다른 스킬들보다 먼저 실행되어야 합니다.

OpenClaw 세트에서는 writing-style-skill이 초안 작성(drafting) 전에 로드되어야 합니다. privacy-filter는 민감한 텍스트를 외부로 공유하기 전에 실행되어야 합니다. skill-creator는 스킬 파일을 변경하기 전에 로드되어야 합니다. github는 GitHub 상태에 따라 행동하기 전에 로드되어야 합니다.

이는 간단한 시퀀싱 규칙(sequencing rules)으로 표현될 수 있습니다:

## 시퀀싱 규칙 (Sequencing rules)

공개 글의 초안을 작성하기 전에, `writing-style-skill`을 로드하십시오.
...

이러한 규칙들은 에이전트가 잘못된 순서로 작업을 수행하는 것을 방지합니다.

훌륭한 AGENTS.md가 가능한 모든 경로를 다 다룰 필요는 없습니다. 순서가 중요한 경로들을 다루면 됩니다.

에이전트에게 올바른 라우팅(routing) 예시 제공하기

예시는 규칙보다 유용할 때가 많습니다.

다음은 압축된 라우팅 테이블(routing table)입니다:

## 라우팅 예시 (Routing examples)

사용자 질문: "이것을 기술 블로그 포스트로 초안을 작성해줘."
...

핵심은 거대한 규칙 엔진(rules engine)을 만드는 것이 아닙니다. 핵심은 미래의 에이전트들이 다음 요청을 올바르게 라우팅할 수 있도록 충분한 예시를 제공하는 것입니다.

공유 스킬에서 로컬 노트 분리하기

재사용 가능한 스킬(reusable skill)은 일반적인 동작을 설명해야 합니다. 로컬 환경의 세부 사항은 다른 곳에 있어야 합니다.

OpenClaw 스타일의 워크스페이스(workspaces)의 경우, 다음과 같은 구성을 의미할 수 있습니다:

SKILL.md       -> 재사용 가능한 지침 (reusable instructions)
TOOLS.md       -> 로컬 장치 이름, 계정 별칭, 호스트 이름, 개인 설정 노트
AGENTS.md     -> 워크스페이스 수준의 운영 규칙
...

이러한 분리는 스킬의 휴대성(portability)을 유지해 줍니다.

weather 스킬은 날씨 조회(weather lookup)가 어떻게 작동하는지 설명할 수 있습니다. 로컬 노트에는 보통 어떤 도시가 관련이 있는지 적어둘 수 있습니다. canvas 스킬은 연결된 노드(nodes)에 HTML을 어떻게 표시하는지 설명할 수 있습니다. 로컬 노트에는 이 설정에 어떤 노드 이름이 존재하는지 적어둘 수 있습니다.

이러한 구분은 작지만, 스킬 라이브러리가 개인적인 설정 더미(config dump)로 변질되는 것을 막아줍니다.

안전 경계(safety boundaries)를 숨기지 말고 가시화하기

만약 스킬이 데이터를 전송(send), 게시(post), 삭제(delete), 제어(control), 지출(spend)하거나 개인 데이터를 노출(expose)할 수 있다면, 기능 맵(capability map)에 이를 명시하십시오.

실용적인 형식은 다음과 같습니다:

## 고위험 스킬 (High-risk skills)

이 스킬들은 외부 시스템에 영향을 미치거나 개인 데이터를 노출할 수 있습니다. 외부 동작을 위해 이들을 사용하기 전에 `SKILL.md`를 로드하고 의도를 확인하십시오.
...

이것이 스킬이 안전하지 않다는 의미는 아닙니다. 스킬이 강력하다는 의미입니다.

에이전트(Agents)는 명확한 라벨(labels)이 있을 때 더 잘 작동합니다.

루트 AGENTS.md를 운영 매뉴얼로 작성하기

유용한 AGENTS.md는 읽을 수 있을 만큼 충분히 짧아야 하며, 동작을 유도할 수 있을 만큼 강력해야 합니다.

좋은 구조는 다음과 같습니다:

# AGENTS.md

## 역할 (Role)
...

이것만으로도 쌓여 있는 로컬 스킬들을 작동 가능한 에이전트 인터페이스(agent interface)로 전환하기에 충분합니다.

AGENTS.md를 박물관이 아닌 지도로 취급하기

파일은 스킬 라이브러리가 변경됨에 따라 함께 변경되어야 합니다.

새로운 스킬을 추가할 때는 기능 맵(capability map)에도 추가하십시오. 도구(tool)가 외부 부작용(external side effects)을 갖게 되면 고위험(high-risk) 섹션으로 이동시키십시오. 에이전트가 라우팅(routing) 실수를 하면, 그 실수를 방지할 수 있었던 작은 예시를 추가하십시오.

최고의 AGENTS.md 파일은 긴 파일이 아니라, 최신 상태를 유지하는 파일입니다.

로컬 에이전트 (local agent) 시스템을 구축하는 개발자들에게 이것은 진정한 보상입니다. 즉, 여러분의 스킬 라이브러리 (skill library)가 오직 여러분만이 이해할 수 있는 무언가로 남는 것을 멈추게 됩니다. 그것은 미래의 에이전트들이 읽고, 추론하며, 올바르게 사용할 수 있는 문서화된 능력 계층 (capability layer)이 됩니다.

그것이 바로 에이전트 준비 완료된 문서화 (agent-ready documentation)가 존재하는 이유입니다.