크로스 에이전트 SKILL.md 스킬 작성하기
스킬은 SKILL.md 파일이 포함된 폴더입니다. 파일은 YAML frontmatter 블록(이름 + 설명)으로 시작하며, 그 뒤에 에이전트가 요청 시 로드하는 Markdown 지침이 옵니다. Claude Code, DeepSeek Harness (dsh), Codex CLI, Gemini CLI, Copilot, Cursor 모두 이 동일한 형식을 읽기 때문에, 잘 작성된 하나의 스킬이 모든 에이전트에서 작동합니다.
구조
my-skill/
├── SKILL.md # 필수: frontmatter + 지침
├── references/ # 선택 사항: 모델이 필요 시 읽는 장문 문서
└── scripts/ # 선택 사항: 스킬이 실행할 수 있는 헬퍼 스크립트
---
name: my-skill
description: >-
한두 문장: 무엇을 하는지 AND 언제 사용하는지. 이것은 사용자 요청과 에이전트가 매칭하는 트리거입니다 — 라우팅 규칙처럼 작성하세요.
---
# My skill
단계별 지침. 유능한 엔지니어를 가정하고 구체적으로 작성하며 모호하지 않게 작성하세요.
스킬이 작동하는지 결정하는 규칙
name은 kebab-case여야 합니다 — 소문자, 숫자, 하이픈만 사용하며 최대 64자. 에이전트는 다른 형식을 거부하거나 변형시킵니다.aipx가 정규화해 주지만, 처음부터 올바르게 작성하세요.description은 문서가 아니라 트리거입니다. 나쁜 예: "작업을 위한 유틸리티". 좋은 예: "URL에서 YouTube/Bilibili 동영상 및 팟캐스트 요약. 사용자가 동영상 또는 오디오 링크를 붙여넣을 때 사용하세요."- SKILL.md를 약 500줄 이내로 유지하세요. 깊이가 필요한 내용은
references/*.md에 넣고 링크하세요("references/schema.md 참조"). 에이전트는 스킬이 트리거될 때만 본문을 로드하므로, 큰 본문은 컨텍스트를 낭비하고 동작을 약화시킵니다. - 중첩된 스킬은 허용되지 않습니다. 탐색은 스킬 루트의 직계 하위 항목만 검색합니다 —
skills/a/SKILL.md는 발견되지만skills/a/b/SKILL.md는 발견되지 않습니다. - 상대 링크는 상대 경로를 유지해야 합니다. SKILL.md가
scripts/x.py를 참조하면 전체 폴더가 함께 이동해야 합니다 — 스킬 디렉토리 외부로 링크하지 마세요.
스킬이 위치하는 곳 (사용자 루트)
| 루트 | 읽는 에이전트 |
|---|---|
~/.agents/skills/<name>/SKILL.md | DeepSeek Harness (dsh), Codex CLI |
~/.claude/skills/<name>/SKILL.md | Claude Code |
~/.gemini/skills/<name>/SKILL.md | Gemini CLI |
~/.copilot/skills/<name>/SKILL.md | GitHub Copilot CLI |
프로젝트 범위의 동등한 위치도 존재합니다(예: 저장소 내 .claude/skills/, .agents/skills/). 직접 복사하지 말고 aipx sync를 사용하여 하나의 복사본을 모든 에이전트 루트에 연결하세요.
게시 전 테스트
# 구문 분석과 검색이 되는지 확인
aipx install ./my-skill --dry-run
aipx install ./my-skill
aipx list
그런 다음 에이전트를 열고 스킬이 나타나는지 확인하세요(Claude Code: 스킬 목록에 표시됨; dsh: / 명령 팔레트 → Skills 그룹).
게시 체크리스트
- 저장소에 안정적인 경로에 스킬 폴더가 포함되어 있음 (예:
skills/my-skill/) -
description에 기능이 아닌 트리거 조건이 명시되어 있음 - 깨끗한 설치에서 작동함 (
aipx install owner/repo#path:/skills/my-skill) - 검색 가능하도록 GitHub 토픽 추가:
agent-skills,claude-code,dsh-plugin(dsh 번들도 함께 제공하는 경우),deepseek(DS 관련인 경우) - 선택 사항: 이중 대상 패키징 —
dsh-plugin-dev및claude-plugin-dev스킬 참조