make-skill — 스킬을 만들고, 개조하고, 배포하는 검증된 방법
작업 중인 레포지토리(보통 ~/DATA/<name>)에서 복사하세요: ssheleg/super-ux
(다중 스킬 모음, Cursor 규칙) 또는 ssheleg/task-pipeline (단일 스킬
오케스트레이터, 릴리스 자동화). make-skill 자체도 이 규범에 따라 제작되었습니다.
참고 자료 — 필요 시 로드
| 읽을 파일 | 시점 |
|---|---|
references/agent-skills-spec.md | 모든 SKILL.md 작성 또는 감사 시 — 두 권위 기관의 하드 제한, 선택 필드, 예산, 거부 조건 |
references/authoring.md | 본문/설명 작성 또는 튜닝 시 — 이름 지정, 3인칭, 자유도, 스크립트 규칙, 평가 루프 |
references/surfaces.md | Claude Code 외부에 배포 시 — Skills API 업로드/버전/요청당 8개, claude.ai zip, 네트워크 없는 환경의 제한 |
references/enterprise.md | 다른 사람의 스킬 설치 또는 플릿 관리 시 — 위험 등급, 검토 체크리스트, 승인 게이트, 라이프사이클 |
references/retrofit.md | 기존 스킬/레포지토리 감사 시 — 14개 항목 체크리스트, 증거 규칙, 개인 스킬 단축 양식 |
references/host-capabilities.md | 훅, 서브에이전트, 명령어, 스크립트 또는 MCP 의존성 배포 시 — 각각의 장점과 비용, 훅 이벤트 및 종료 코드, 저하 조항 |
references/claude-code-plugin.md | Claude Code 플러그인/마켓플레이스로 배포 시 — 매니페스트 스키마, 컴포넌트 레이아웃, 경로 변수, validate 실패 |
references/distribution.md | 레포지토리 레이아웃, 릴리스 및 5개 채널 — 플러그인, skills CLI, npx, Cursor, umbrella 패밀리 레포 |
references/mcp.md, references/mcp-ship.md | 스킬 vs MCP 서버, 하나를 래핑한 후 배포: 마운팅, 404, server.json, 레지스트리 |
references/a2a.md | 스킬이 두 자율 에이전트(A2A)에 걸쳐 있을 때: Agent Card, 태스크 라이프사이클, 위임 |
이 복사본에 없는 파일은? 원본 대체 경로:
raw.githubusercontent.com/ssheleg/make-skill/main/plugins/make-skill/skills/make-skill/references/<file>
워크플로우 선택
요청과 $ARGUMENTS의 경로를 감지하여 선택을 알립니다.
| 상황 | 워크플로우 |
|---|---|
| 새 스킬, 이 사용자의 에이전트 전용 | 생성 (개인) |
| 새 스킬, 다른 사람/에이전트가 설치 가능 | 생성 (배포 가능) |
| 기존 스킬 또는 이 표준 미만의 레포지토리, "이게 스펙에 맞나요?" | 개조 (Retrofit) |
| 개인 스킬을 배포 가능하게 전환 | 승격 (Promote) |
인자가 없으면 묻지 말고 감지: 현재 디렉토리에 SKILL.md, .claude-plugin/
또는 plugins/*/skills/*/가 있다면 → 개조 감사 실행 후 갭 테이블과
하나의 다음 액션을 보고합니다. 감지되는 것이 없으면 한 줄로 무엇을 만들지 묻습니다.
배포 가능한 작업은 실제 프로젝트입니다: 코드보다 먼저 스펙(docs/superpowers/specs/)이 있고,
스펙은 대상 프로젝트 파일 계약을 먼저 고정합니다 — 스킬은 그 계약을 기준으로 작성되며,
임시로 작성되지 않습니다.
작성 규칙 (모든 워크플로우)
먼저 스펙 기준 충족 — 오픈 표준
과 Anthropic의 플랫폼 규칙
은 모두 협상 불가입니다; 이 규범은 그 위에 추가될 뿐입니다. 필드 테이블, 차이점 및 체크리스트: references/agent-skills-spec.md.
name:references/agent-skills-spec.md의 문자 규칙을 따르며, 디렉토리 이름과 동일합니다. 함정:anthropic또는claude를 절대 포함하지 마세요 — Claude Code는 문제없이 로드하지만 Skills API가 업로드를 거부하는 예약된 부분 문자열이므로, 다른 사람의 머신에서 실패하게 됩니다.description: ≤1024자 (이 필드만의 제한이며 전체 프론트매터 블록이 아님), 꺾쇠괄호 없음, 3인칭 — 시스템 프롬프트에 주입되므로 "제가 도와드리겠습니다…"는 선택을 저하시킵니다. 무엇을 하는지와 언제 사용할지를 명시하세요.- 이식 가능한 선택 세트는
license,compatibility,metadata및allowed-tools입니다 — 제한 및 유형은references/agent-skills-spec.md참조. license는 선택 사항이지만 그래도 선언하세요, 프론트매터와marketplace.json플러그인 항목 모두에: 루트의LICENSE파일은 플러그인 목록이나 설치된 스킬에 도달하지 않으며, 오류도 발생하지 않으므로 갭이 그대로 남습니다 (여기 있는 6개 레포지토리, 2026-07-30 기준).- 호스트 확장은 합법적이지만, 핵심 기능이 되어서는 안 됩니다. Claude Code는 추가 호스트 전용
세트(
references/claude-code-plugin.md)를 읽습니다; 다른 에이전트는 무시하므로, 이에 의존하는 스킬은 다른 곳에서 깨집니다. 스펙 ∪ 호스트 외부 = 오타. - 본문 < 500줄 및 < 5000토큰, 5% 여유 유지 — 99% 예산의 본문은 다음 수정 시
검증기와 싸우게 만듭니다. 더 무거운 내용은 스킬 디렉토리 내부의
references/,scripts/,assets/에 한 단계 깊이 배치하고, 각각 명시된 로드 트리거("Y일 때 X 읽기")로 본문에서 링크하세요 — 절대 "see references/"라고만 하지 마세요. 100줄이 넘는 참고 파일은## 목차목록으로 시작합니다: 에이전트가 부분적인head읽기를 얻는 방식입니다. - 함정은
SKILL.md에 남깁니다: 에이전트는 존재하는지도 모르는 함정에 대한 파일을 열 수 없습니다. - 주장하는 가장 약한 표면에 맞게 작성하세요 (
references/surfaces.md): Claude API 컨테이너는 네트워크와 패키지 설치가 모두 없고, claude.ai는 다양하며, 둘 다 있는 것은 Claude Code뿐입니다.pip install하거나 curl하는 스크립트는 Claude Code 스킬입니다 —compatibility에 명시하거나 제거하세요. 표면 간에 동기화되는 것은 없습니다; git이 진실의 원천입니다.
스펙에 추가된 사항:
- 본문은 영어; 리터럴은 입력된 언어 그대로 유지합니다. 키릴 문자는 문자열 자체가 중요한
네 곳에서만 살아남습니다: 트리거 구문, 거절 구문 (운영자가 둘 다 입력 — 번역하면
실제로 말한 것과 일치하지 않음), 고유명사, 언어 예시 (
«вы»/«ты»). 스타일 규칙보다 예산 규칙이 우선: 러시아어는 영어의 5.0자/토큰(cl100k) 대비 1.9–2.3자/토큰으로 인코딩되며, 8개의 ssheleg 라우터를 영어로 다시 작성하면 의미 손실 없이 3408 → 1885 토큰으로 줄었습니다. description은 "다음과 같은 경우 사용 …"으로 시작하고 구체적인 트리거 구문을 나열합니다 — 영어 및 러시아어 (사용자가 두 언어로 작업). 아무도 트리거하지 않는 스킬은 사족입니다. 여기서도 5% 여유 유지 (≤970/1024): 근접한 이웃 항목이 "다음의 경우는 사용하지 마세요…" 조항을 강제하며, 98% 용량의 설명에는 넣을 곳이 없습니다.- 하나의 명명 패턴, 가급적 동명사 (
processing-pdfs); 절대helper,utils,tools,data는 사용하지 마세요 — 모호한 이름은 모든 선택에서 손해입니다. - 하나의 스킬 = 하나의 작업. 여러 관심사 → 여러 스킬 + 공유 계약 파일.
계약을 스킬 디렉토리 내부에 배치하세요 (
references/…): skills CLI는 스킬 자체의 디렉토리만 배송하므로, 형제skills/references/는 Claude Code 플러그인으로 작동하지만 다른 모든 에이전트에서는 깨진 상태로 도착합니다. 스킬 간 공유 → 스킬 디렉토리별로 복제, 검증기로 동일 여부 확인. - 본문: 명령형, 절차적, 산문보다 체크리스트; 비협상 사항은 그렇게 명시.
취약성에 따라 규정의 정도를 조정 — 파괴적이거나 순서 의존적인 작업에는 정확한 명령어,
컨텍스트가 결정하는 경우에는 방향만 제시 (
references/authoring.md). - 산문 전에 평가: 대상 태스크를 스킬 없이 실행하고, 실패를 기록한 후, 이에 대한 ≥3개의 평가를 작성한 다음, 통과하는 최소한의 내용을 작성하세요; 기준 없이 만든 스킬은 상상된 문제를 문서화합니다. 기존 패밀리에 추가하는 경우 → 설치된 세트에 대한 공존을 측정하고, 추측하지 마세요: 당신이 지목할 이웃은 보통 가장 가까운 것이 아닙니다.
- 하나의 명령어 진입점을 제공하세요: 멱등성 — 상태 검사 → 누락된 부분 수리 → 상태 보고 →
정확히 하나의 제안된 다음 액션. 감지 모드, 절대 묻지 않음. 스킬이 바로 그 명령어입니다;
호출은 채널에 따라 다릅니다 (skills 디렉토리에서
/<skill>, 플러그인에서/<plugin>:<skill>) — 하나를 약속하기보다 README에 둘 다 작성하세요. - 사용자 데이터를 절대 덮어쓰지 마세요: 없을 때만 시드;
--force뒤에서만 덮어쓰기.
저하 계약 (호스트 기능을 사용하는 모든 스킬)
훅, 서브에이전트, /commands, 플러그인 경로 변수 및 MCP 서버는 Claude Code 내부에만
존재합니다 — 스킬이 실행되는 환경의 소수입니다. 각각은 문서화된 폴백이 있는 가속기이며,
스킬은 없어도 작업을 더 느리게 완료합니다. 본문에 에이전트의 말로, 필요할 시점에
세 가지 경우를 작성하세요 (형태: references/host-capabilities.md):
- Claude Code 아님 (Cursor, Codex, skills CLI, API): 훅, 서브에이전트,
/command없음. 인라인 절차 이름을 지정; 번들된scripts/는 여전히 이동하므로 채널별 경로 제공. - 권장 플러그인/스킬 없음: 한 번 저하되었다고 말하고, 수동 경로로 계속. 선택적 동반자가 없어 시작을 거부하는 단계는 엄격함이 아니라 고장입니다.
- 도구, 인터프리터 또는 MCP 서버 없음: 한 번 명시하고, 수동 절차로 폴백, 절대 루프로 재시도하지 마세요. 대화형 인증은 사람의 단계입니다.
알고 있지만 작성하지 않은 폴백은 폴백이 아닙니다.
이 스킬이 제공하는 작업 예제 — 기억에 의존하지 말고 복사하세요
scripts/audit_skill.py는 모든 스킬 디렉토리를 감사합니다 (표준 라이브러리; Retrofit의 기계적 절반),
Claude Code를 위해 bin/make-skill-audit로 래핑되었습니다. 함께 제공: hooks/ (PostToolUse,
SKILL.md가 작성된 경우에만 조용히 작동), commands/skill-audit.md (의도적으로 스킬 이름과
다름), agents/skill-auditor.md, 그리고 6개의 스켈레톤: assets/SKILL.template.md,
assets/plugin.template.json, assets/marketplace.template.json,
assets/hooks.template.json, assets/agent.template.md, assets/command.template.md.
생성 (개인)
~/.claude/skills/<name>/SKILL.md를 작성 규칙에 따라 생성 — 끝. 레포지토리 없음,
버전 관리 없음; 다음 세션에 로드됩니다. 승격(Promote)을 업그레이드 경로로 언급하세요.
훅, 에이전트 또는 MCP 서버가 필요하지만 여전히 레포지토리가 없나요? 같은 폴더에
.claude-plugin/plugin.json을 추가하세요 — 다음 세션에 Claude Code가 <name>@skills-dir로 로드합니다.
생성 (배포 가능)
레포지토리 트리, 퍼블릭 레포지토리 기준, claude plugin validate … --strict 실행과
하우스 검증기 스펙 모두 references/distribution.md → 배포 가능한 레포지토리 레이아웃에
있습니다. 첫 파일을 작성하기 전에 여세요. 관계없이 적용되는 사항:
.claude-plugin/marketplace.json은 레포지토리 루트에; 플러그인은plugins/<name>/아래에 자체.claude-plugin/plugin.json과 함께; 스킬은plugins/<name>/skills/<skill>/에references/,scripts/,assets/를 내부에 배치. 매니페스트만.claude-plugin/에 살고 — 거기에 묻힌 컴포넌트는 아무것도 로드되지 않지만 플러그인은 여전히 작동하는 것처럼 보입니다.- 버전 동기화 (하드 규칙): marketplace.json, plugin.json, package.json 및 최상위
CHANGELOG 항목은 동일한 semver를 가지며, 함께 증가됩니다 (+
SKILL.md가metadata.version을 가지고 있으면 5번째 포인트 추가). --strict실행은 둘 다 통과해야 하며, CI에서 자체 작업으로 — 매니페스트만 읽으므로, 프론트매터 규칙은 자체test/validate.py에 있으며, 이는 부정 자체 테스트가 필요합니다: 실패할 수 없는 검증기는 장식입니다.plugin.json과 마켓플레이스 항목에$schema와displayName을 제공하세요 (마켓플레이스 루트는 둘 다 받지 않습니다).- 퍼블릭 레포지토리는 독자에게 영어 우선 README, 변경 사항을 확인하는 오프라인 명령어가 있는
CONTRIBUTING.md, 비공개 채널과 설치 프로그램이 접촉하는 대상을 명시하는SECURITY.md를 제공해야 합니다.
첫 게시 — 종단 간, 동일 세션
완전히 진행하세요, 반쯤 완료된 핸드오프 없이. 첫 게시만 사람이 필요합니다 (npm 2FA);
CI 게시 준비는 배송의 일부이므로, 두 번째는 필요하지 않습니다. 11단계 시퀀스는
references/distribution.md → 첫 게시에 있습니다. 완료 = 다섯 가지 확인된 사실:
레포 + CI 통과, npx로 npm 확인 가능, 플러그인 설치됨, skills-CLI 검색 작동, 다음 태그 게시가
사람 없이 작동.
개조 (기존 스킬/레포지토리를 표준에 맞게 업그레이드)
먼저 감사, 그 다음 수정, 동일 세션에. 항목별 판정: PASS / GAP / NOT-RUN, 증거 포함
— file:line 또는 실제 실행한 명령어의 출력. "괜찮아 보임"은 판정이 아니며, 실행되지 않고
추론된 검사의 PASS도 아닙니다; 도구가 없는 검사는 이유와 함께 NOT-RUN이며, 절대 PASS가
아닙니다.
번들 감사기를 먼저 실행하세요 — 결정론적으로 기계적 절반을 수행하며, 설정되지 않은 변수에 절대 의존하지 않습니다:
make-skill-audit <skill-dir> --house # Claude Code: 플러그인의 bin/이 PATH에 있음
다른 곳에서는 방금 읽은 make-skill 디렉토리에서 scripts/audit_skill.py를 실행하세요.
그런 다음 references/retrofit.md의 14개 항목 체크리스트를 작업하세요 — 스펙 기준,
플러그인 기준, 표면, 하나의 작업, 진입점, 레이아웃 및 버전 동기화, 검증기 및 CI, 평가,
README, 배포, 레포 메타데이터, 함정, 프로토콜, 호스트 기능. 개인 스킬의 경우 세 항목만
적용됩니다; 해당 파일에 명시되어 있습니다.
그런 다음: 갭 테이블을 보고, 지금 수정 가능한 모든 것을 수정하고, 부/패치 버전을 올리고, 릴리스 체크리스트를 실행하세요.
승격 (개인 → 배포 가능)
레이아웃에 따라 레포지토리를 생성하고, 스킬을 plugins/<name>/skills/<skill>/로 이동하고,
계약을 references/로 추출한 후, 첫 게시를 종단 간 실행하세요. 플러그인 설치가 확인된 후에야
이전 ~/.claude/skills/<skill> 복사본을 삭제하세요.
다른 사람의 스킬 설치
스킬은 에이전트가 실행하는 지침과 읽지 않고 실행하는 코드입니다 — 설치하는 것은 소프트웨어를
설치하는 것입니다. 직접 작성하지 않은 것은 references/enterprise.md의 검토 체크리스트를
먼저 받으세요. 가장 위험한 형태: URL에서 지침을 가져오는 스킬 — 승인한 검토 후에 내용이 변경됩니다.
프로토콜 연결 스킬 (MCP / A2A)
스킬은 지침입니다; 기능을 부여할 수 없습니다. 에이전트에게 방법을 가르치는 것은 스킬입니다.
실시간 시스템에 대한 새로운 기능은 MCP 서버입니다 (mcp.md, 그 다음 마운트 및 게시를 위해
mcp-ship.md). 다른 자율 에이전트에 결과를 위임하는 것은 A2A입니다 (a2a.md).
두 레퍼런스 모두 와이어 수준 규칙을 포함합니다 — 호스트별 도구 이름 검색, Agent Card,
사람 단계로서의 대화형 인증.