subagent-creator

Claude Code subagent 정의 파일을 설계해 쓰고 형식을 검증하는 Agent Skill.

subagent 는 Claude Code 가 작업을 위임하는 독립 에이전트다. 정의 파일(.claude/agents/<name>.md) 하나로 만들어지지만, 유효한 파일과 실제로 위임되는 파일은 다르다. description 이 "무엇을 하는지"만 적혀 있으면 파일은 통과해도 영원히 호출되지 않는다.

이 스킬은 그 간극을 메운다.

단계	무엇을 고정하는가
의도	단일 책임, 위임 시점, 출력 계약
frontmatter	위임 트리거가 되는 description, 최소 권한 tools, 난이도에 맞는 model
본문	역할·절차·출력 형식·경계를 담은 시스템 프롬프트
검증	frontmatter 를 실제 필드·도구 이름과 대조

이 저장소는 subagent-creator 스킬의 소스 저장소다. 설치용 카탈로그는 pubcyberry/skills 이고, 여기 skills/subagent-creator/ 가 그쪽으로 자동 동기화된다.

설치

카탈로그를 통해 설치한다.

npx skills add pubcyberry/skills --skill subagent-creator --agent claude-code

이 저장소에서 직접 설치할 수도 있다.

npx skills add pubcyberry/subagent-creator

검증기 단독 사용

스킬 없이 검증기만 쓸 수도 있다. 호스트 환경에 아무것도 설치하지 않는다.

uv run --with pyyaml --python 3.11 \
  skills/subagent-creator/scripts/validate_subagent.py .claude/agents/code-reviewer.md

잡아내는 것: frontmatter 누락과 YAML 파싱 실패, 알 수 없는 키, 파일명과 어긋난 name, 존재하지 않는 도구 이름, enum 밖의 effort/permissionMode/memory/color, 빈 시스템 프롬프트.

저장소 구조

.
├── skills/
│   └── subagent-creator/
│       ├── SKILL.md                    # 진입점 — frontmatter + 생성 절차
│       ├── skill-card.md               # 소유자·라이선스·위험·출력 거버넌스 카드
│       ├── evals/evals.json            # 발동 정확도 태스크셋 (positive/negative)
│       ├── references/agent-format.md  # 필드·도구·경로 상세. 필요할 때만 읽는다
│       ├── scripts/                    # agent 정의 검증기 (Python + PyYAML)
│       └── tests/smoke.sh              # 검증기 동작 + 문서·검증기 일치 자가 검증
├── .pre-commit-config.yaml   # prek 훅. shellcheck, shfmt, ruff, actionlint, zizmor
├── .editorconfig             # 편집기와 shfmt 의 형식 기준
└── .github/
    ├── scripts/validate-skills.sh   # 필수 산출물 + frontmatter 검증
    └── workflows/validate.yml       # PR 마다 lint, audit, 검증, 스모크 테스트

skills/ 를 저장소 루트에 두는 것은 Agent Skills 권장 배치를 따른 것이다. 에이전트별 경로(.claude/skills/, .codex/skills/)에 원본을 두면 중복이 생긴다.

스킬 하나가 갖춰야 하는 산출물

파일	필수	역할
SKILL.md	✅	에이전트가 읽는 진입점. frontmatter 의 name, description 이 발동을 결정한다
skill-card.md	✅	소유자, 라이선스, 유스케이스, 알려진 위험과 완화, 출력 형식
evals/evals.json	✅	발동 정확도 태스크셋. negative 케이스가 최소 1개 있어야 한다
references/		길어지는 내용. SKILL.md 는 짧게 두고 여기로 민다
tests/		스크립트를 배포하는 스킬이면 스모크 테스트

CI 가 위 필수 항목을 검사한다. 누락되면 카탈로그 동기화 단계에서 스킬이 드롭된다.

로컬 검증

bash .github/scripts/validate-skills.sh          # frontmatter + 필수 산출물
bash skills/subagent-creator/tests/smoke.sh      # 검증기 동작 + 문서·검증기 일치
prek run --all-files                             # shellcheck, shfmt, ruff, actionlint, zizmor

의존: bash, git, yq, jq, uv. 훅과 린트는 아래를 추가로 요구한다.

uv tool install prek
for t in shellcheck-py shfmt-py actionlint-py zizmor ruff; do uv tool install "$t"; done
prek install

shfmt 의 형식 기준은 .editorconfig 다. 명령줄에 형식 플래그를 주면 .editorconfig 가 무시되므로 훅에서도 CI 에서도 플래그 없이 부른다.

기여

CONTRIBUTING.md 를 본다. 보안 신고는 SECURITY.md.

라이선스

MIT. LICENSE 참고.