CLAWPOD ENGINEERING
Capability description, 사용자의 말로 쓰는 선택 안내서
사람은 더 쉽게 요청하고 에이전트는 더 정확히 선택하도록, Capability 설명을 작성하고 경계·조합·실제 지원 범위를 검증하는 방법을 소개합니다.
Capability 이름을 몰라도 괜찮아요
사용자는 보통 “어떤 Capability를 실행해 줘”보다 “Jira 이슈에 댓글을 달아 줘” 또는 “이 조사 결과를 출처가 있는 브리프로 만들어 줘”라고 말해요. 좋은 description은 이런 자연스러운 요청과 적절한 도구 사이를 이어 줍니다.
여기서 Capability는 특정 종류의 요청을 처리하도록 묶은 능력 단위, description은 그 능력을 언제 선택할지 알려 주는 짧은 설명입니다. 설명이 모호하면 사용자는 기능 이름을 외워야 하고, 에이전트는 비슷한 도구 사이에서 추측해야 해요. 경계가 분명하면 사용자는 원하는 결과에 집중할 수 있고, 작성자와 검토자는 잘못된 선택을 재현 가능한 테스트로 고칠 수 있습니다.
먼저 짧은 예시로 비교해 볼까요?
수정 전
문서 관련 작업을 빠르고 강력하게 자동화합니다.수정 후
내부 사양을 릴리즈 노트 초안으로 바꾸려는 요청에 사용합니다.
사양 파일을 읽고 정해진 형식의 초안을 만들 수 있습니다.
기존 문서를 찾기만 할 때는 docs-search를 사용하고,
편집 승인을 받은 뒤 게시할 때는 release-publisher로 넘깁니다.두 번째 설명은 화려하지 않지만 훨씬 친절해요. 사람에게는 “내 요청이 여기에 해당하는지”를 알려 주고, 에이전트에게는 선택·비선택·인계 기준을 줍니다. 이런 description은 라우팅 계약, 즉 요청을 어느 Capability로 보낼지 합의한 선택 기준이 됩니다.
네 줄이면 선택, 범위, 경계, 인계가 보여요
먼저 네 요소를 각각 한 줄로 써 보세요.
WHEN: 언제 선택하나요?
사용자가 이루려는 결과, 작업 대상, 선택을 바꾸는 조건을 사용자의 언어로 적습니다.
- “문서 작업에 사용”보다 “기존 Confluence 페이지를 찾아 수정하려는 요청에 사용”
- “이미지 도구”보다 “단독 이미지를 생성하거나 편집·비교하려는 요청에 사용”
CAN: 실제로 어디까지 할 수 있는가
구현하고 검증한 작업만 구체적인 동사로 적습니다. Action surface는 Capability가 실제로 외부에 제공하는 명령이나 API 작업의 범위를 뜻합니다.
- “Atlassian을 관리합니다”보다 “Jira 이슈를 읽고, 만들고, 수정하고, 댓글을 답니다”
- 실제 action이 없다면 “삭제합니다”, “배포합니다” 같은 동사를 넣지 않습니다.
위험한 쓰기 작업이 있다는 사실과 실행 승인은 별개입니다. 설명은 지원 범위를 정확히 말하고, 실제 실행의 승인과 안전 통제는 해당 런타임 절차에서 다룹니다.
BOUNDARY: 언제 다른 것을 선택하나요?
가장 가까운 대안을 이름으로 지목하고 갈림길을 적습니다. “관련 없는 작업에는 사용하지 않습니다”는 아무런 판단도 돕지 못합니다.
Jira 이슈가 아니라 저장소의 이슈, Pull Request, Actions를 다룰 때는 GitHub를 사용합니다.이 문장은 대상이 어디에 있느냐가 선택 기준임을 바로 보여 줍니다.
COMPOSITION: 다음 단계에 무엇과 함께 쓰나요?
Composition은 여러 Capability를 한 작업 흐름으로 조합하는 방법입니다. 단순히 관련 도구를 나열하지 말고 언제 무엇을 넘기는지 적어 주세요.
Jira와 Confluence에서 모은 근거를 출처가 있는 브리프로 만들 때는 Verified Research와 결합합니다.후속 단계가 없다면 억지로 조합을 만들 필요는 없습니다. 대신 이 Capability만으로 끝나는 범위를 분명히 해 주세요.
이제 설명을 실제 요청으로 검증할 차례입니다. 지원 범위를 먼저 확인하고, 사용자 요청으로 초안을 만든 뒤, 이웃 Capability와의 충돌과 모든 동사를 시험합니다.
flowchart TD
A[실제 지원 범위 확인] --> B[사용자 요청 수집]
B --> C[WHEN·CAN·BOUNDARY 작성]
C --> D[이웃과 충돌 시험]
D --> E{동사 검증?}
E -->|아니요| C
E -->|예| F[표면 동기화·fresh-agent test]사람인 작성자를 위한 5단계 작성법
1. 실제 계약을 먼저 확인해요
설명을 상상해서 쓰기 전에 실제 명령, 입력과 출력, 읽기·쓰기 범위, 인증과 복구 흐름, 검증된 성공·실패 경로를 살펴봅니다. 가까운 이웃 Capability도 함께 확인합니다.
목표는 “할 수 있을 것 같은 일”이 아니라 “지금 확인할 수 있는 일”을 모으는 데 있습니다.
2. 사용자 요청 문장을 모아요
최소한 다음 사례를 적어 보세요.
- 반드시 선택되어야 하는 요청 3개
- 비슷하지만 선택되면 안 되는 요청 2개
- 이웃 Capability와 충돌하기 쉬운 요청 1개
- 여러 Capability가 필요한 요청 1개
예를 들어 “Confluence 페이지를 수정해 줘”, “GitHub 이슈를 닫아 줘”, “Confluence 근거로 브리프를 써 줘”처럼 사용자가 실제로 말할 법한 문장을 써 보세요. 요청을 먼저 모으면 설명이 API 이름이나 내부 구조로 흐르는 것을 막을 수 있습니다.
3. 네 줄 초안을 만들어요
WHEN: [이런 의도·대상·조건의 요청에 사용합니다]
CAN: [검증된 작업을 수행할 수 있습니다]
BOUNDARY: [이 조건이면 이웃 Capability를 사용합니다]
COMPOSITION: [이 후속 목적에는 무엇과 결합하거나 어디로 넘깁니다]처음부터 멋진 한 문장을 만들려고 애쓰지 않아도 됩니다. 네 줄에서 빈칸과 충돌을 먼저 찾은 뒤 중복을 줄여 보세요.
4. 사용자의 말로 다시 써요
“OAuth 2.0, MCP, Gateway digest, REST v3을 사용합니다”라는 구현 설명만으로는 사용자가 언제 선택해야 할지 알기 어렵습니다. OAuth 같은 내부 용어가 선택에 꼭 필요하지 않다면 Skill 본문, Harness 명세, 온보딩 또는 안전 절차로 옮겨 주세요.
다음처럼 결과와 대상을 앞으로 보내면 훨씬 선명해집니다.
| 내부 중심 표현 | 사용자 중심 표현 |
|---|---|
issue.transition action 지원 |
Jira 이슈의 상태를 바꿀 수 있습니다. |
| provider SDK로 image job 실행 | 단독 이미지를 생성하고 결과를 확인할 수 있습니다. |
| citation bundle 생성 | 여러 공개 출처를 대조해 인용 가능한 근거 묶음을 만듭니다. |
실제 description에는 대상 Capability에서 확인한 action만 넣어야 합니다.
5. 모든 동사를 action surface와 맞춰 봐요
설명에 쓴 동사를 하나씩 뽑아 실제 명령이나 API와 연결해 보세요.
| 설명 동사 | 실제 작업 | 성공 검증 | 실패·권한 검증 | 결정 |
|---|---|---|---|---|
| 생성 | issue.create |
있음 | 있음 | 유지 |
| 수정 | issue.update |
있음 | 있음 | 유지 |
| 삭제 | 없음 | 없음 | 없음 | 설명에서 제거 |
근거 없는 동사는 구현하고 검증하거나 description에서 빼야 합니다.
AgentSkill과 CLI Harness는 같은 선택 의미를 맞춰야 해요
AgentSkill은 에이전트가 의도와 절차를 판단하고 적절한 명령을 고르는 지침이며, CLI Harness는 그 판단을 명령행에서 결정적으로 실행하고 구조화된 결과로 돌려주는 연결 계층을 뜻합니다. 이 구분은 앞선 글인 「AgentSkill과 CLI Harness를 왜 분리해서 생각하는가」에서 다룬 설계 관점과 맞닿아 있습니다. 여기서는 구조를 반복하기보다 두 표면의 description을 어떻게 맞출지에 집중해 보겠습니다.
연결된 Skill과 Harness는 하나의 Capability를 서로 다르게 소개해서는 안 됩니다.
- canonical Capability 이름과 사용자에게 보이는 제목을 맞춥니다.
- WHEN·CAN·BOUNDARY·COMPOSITION의 의미를 같게 유지합니다.
- Skill은 의도·판단·절차·명령 선택을, Harness는 실행·검증·구조화된 출력을 설명합니다.
- 둘이 같은 description 필드를 공유하는 구조라면 문자열까지 완전히 같게 맞춥니다.
- 별도 필드가 필요해도 서로 다른 지원 범위나 경계를 암시하지 않습니다.
에이전트와 검토자는 설명을 선택 실험으로 읽어요
문장이 자연스러운지만 보지 말고 실제 요청을 넣어 보세요.
필수 라우팅 테스트
- 긍정 트리거: 대표 요청 3개 이상에서 올바르게 선택되나요?
- 가까운 부정 트리거: 비슷한 요청 2개 이상에서 선택되지 않나요?
- 이웃 충돌: 가장 가까운 Capability와 같은 요청을 차지하지 않나요?
- 조합 흐름: 복합 요청에서 필요한 Capability와 올바른 순서로 연결되나요?
- 지원 범위: description의 모든 동사가 실제 action에 존재하고 검증됐나요?
테스트가 실패하면 요청 문구를 억지로 바꾸지 마세요. WHEN이 너무 넓은지, BOUNDARY가 실제 갈림길을 말하는지, CAN이 과장됐는지 먼저 고쳐 주세요.
문구가 머무는 곳도 함께 확인해요
Canonical은 여러 복사본이 따라야 하는 기준 원본을 뜻합니다. 같은 description이 여러 곳에 노출된다면 다음 동기화 지점을 확인해 주세요.
- Registry의 description
- canonical Skill frontmatter의 description
- 설치된 Skill frontmatter의 description
- Harness description과 선택 계약 필드
- 매 턴 에이전트에게 주입되는 capability catalog의 description
해당 프로젝트에 실제로 존재하는 표면만 검사하되, 검사 범위를 기록합니다. 같은 필드를 공유하도록 설계했다면 의미가 비슷한 수준이 아니라 문자열이 완전히 같아야 합니다. Drift는 이런 복사본의 문구가 서로 어긋난 상태입니다. 한 곳만 수정하면 오래된 복사본이 계속 잘못된 선택을 만들 수 있어요.
새 에이전트에게 마지막으로 물어봐요
Fresh-agent test는 기존 프로젝트 대화나 작성자의 보충 설명이 없는 새 에이전트에게 description만 주고 선택을 확인하는 시험입니다.
- 대표 요청에서 올바른 Capability를 고르나요?
- 가까운 다른 요청에서는 고르지 않나요?
- 이웃과 충돌하지 않나요?
- 복합 요청에서 필요한 조합을 만드나요?
- 설명만 보고 지원하지 않는 작업을 기대하지 않나요?
작성자가 옆에서 해설해야 통과한다면 아직 독립적인 라우팅 계약이라고 보기 어렵습니다.
피해야 할 설명 패턴
| 패턴 | 예시 | 문제 |
|---|---|---|
| 기능 자랑형 | “강력한 엔터프라이즈 통합입니다.” | 선택 시점을 알 수 없습니다. |
| 구현 내부형 | “OAuth, MCP, REST v3을 사용합니다.” | 사용자 의도보다 구현이 앞섭니다. |
| 무제한 범위형 | “모든 Workspace 작업을 관리합니다.” | 지원하지 않는 기능까지 암시합니다. |
| 경계 부재형 | “문서와 협업에 사용합니다.” | 어느 서비스나 Capability를 고를지 알 수 없습니다. |
| 모호한 부정형 | “관련 없거나 지원하지 않는 작업에는 쓰지 않습니다.” | 실제 대안과 판별 조건이 없습니다. |
| 조직 문맥 의존형 | “Forge가 우리 Capability를 배포할 때 씁니다.” | 처음 보는 사용자와 에이전트가 로컬 문맥을 알 수 없습니다. |
예시는 모두 설명 품질을 비교하기 위한 가상 문장입니다.
변경 후 리뷰 체크리스트
사용자와 작성자 관점
- 첫 문장에 사용자의 의도·대상·조건이 보입니다.
- 내부 용어를 썼다면 처음에 쉬운 말로 설명했습니다.
- 지원하는 작업과 지원하지 않는 작업을 과장 없이 구분했습니다.
- 가장 가까운 대안과 실제 갈림길을 적었습니다.
- 후속 Capability가 필요하면 인계 대상과 넘길 것을 적었습니다.
에이전트와 검토자 관점
- 긍정 요청 3개와 가까운 부정 요청 2개 이상을 통과했습니다.
- 이웃 Capability와 충돌하지 않습니다.
- 복합 요청에서 올바른 조합을 만듭니다.
- CAN의 모든 동사를 action surface에서 확인했습니다.
- Registry, canonical, installed, Harness, injected 설명 중 존재하는 표면을 동기화했습니다.
- 문맥 없는 새 에이전트가 설명만으로 선택과 비선택을 재현했습니다.
- 최종 수정본을 기준으로 검사를 다시 실행했습니다.
Description 변경을 버전이나 릴리즈에 어떻게 반영할지는 각 공개 프로젝트의 정책을 따릅니다. 다만 문구가 라우팅을 바꾼다면 단순한 카피 수정으로 넘기지 말고, 적용 대상과 최종 후보를 다시 검증하는 편이 안전합니다.
복사해서 시작하는 최종 템플릿
[사용자가 원하는 결과·대상·중요 조건]일 때 사용합니다.
[검증된 핵심 작업]을 할 수 있습니다.
[가까운 다른 조건]일 때는 [이웃 Capability]를 사용합니다.
[후속 목적]에는 [동반 Capability]와 결합해 [넘길 결과 또는 인계 지점]으로 이어 갑니다.조합이 필요 없다면 마지막 줄 대신 “이 범위까지 단독으로 완료합니다”라고 적어 주세요. 좋은 description의 목표는 모든 기능을 자랑하는 데 있지 않습니다. 사용자는 Capability 이름을 몰라도 원하는 결과를 말할 수 있고, 에이전트는 그 말만으로 올바르게 선택하고 멈추고 이어 갈 수 있어야 합니다.
