Skills 이해
Skill은 특정 작업의 단계별 절차입니다.
/skill-name으로 명시적으로 호출할 때만 적용됩니다 — "on-demand".

Skill 해부

Skill은 skills/<카테고리>/<id>/SKILL.md 경로에 저장됩니다. 폴더 내에 추가 파일(예: 템플릿, 설정 파일)을 함께 포함할 수 있습니다.

---
name: are-we-done
description: Answers "are we done?" before a PR exists.
  Spawns an independent reviewer subagent that checks the
  work against the original plan/requirements.
---
# are-we-done

The last check before a change leaves your hands...

## When to run
- Right before generate-pr-summary / opening a PR.
- After an autonomous implementation loop.

## Steps
1. Gather the intent (plan/requirements)
2. Run git diff to capture the change
3. Run tests and capture output
4. Spawn independent reviewer subagent
5. Report SHIP / FIX-FIRST verdict
frontmatter 필드의미
nameTUI와 CLAUDE.md에 표시되는 이름. 보통 파일 경로의 id와 동일
description언제 이 skill을 쓰는지 한두 문장. Claude가 skill 선택 판단에 사용
disable-model-invocationtrue이면 Claude가 본문을 참조 자료로만 읽고 절차로 실행하지 않음. marketplace에서 rule→skill 변환 시 자동 추가됨

일반 Skill vs Scaffolder (-init) 패턴

📋 일반 Skill — 절차가 고정됨

예: auth/azure-ad-sso-flask

  • 항상 같은 절차를 따름
  • 프로젝트별 스캔 없음
  • Flask + Azure AD SSO를 추가하는 정해진 단계
  • 호출: /azure-ad-sso-flask

🔧 Scaffolder — 프로젝트를 스캔해 맞춤 버전 생성

예: api-integration/sync-api-contracts-init

  • 프로젝트에서 OpenAPI spec 위치를 스캔
  • 사용자에게 output 경로 질문
  • 프로젝트 전용 sync-api-contracts/SKILL.md 생성
  • 이후에는 프로젝트 전용 skill 사용
ℹ️ -init 패턴: sync-api-contracts-init을 한 번 실행하면 .agents/skills/api-integration/sync-api-contracts/SKILL.md가 생성됩니다. 이후에는 /sync-api-contracts를 사용합니다. 처음 실행하는 설정 스킬 vs 반복 사용하는 작업 스킬의 분리입니다.

Scaffolder가 필요한 이유

같은 "API 계약 동기화" 작업이라도 프로젝트마다 OpenAPI 파일 위치, 출력 경로, 사용 툴체인이 다릅니다. Scaffolder는 한 번 프로젝트를 스캔해서 "이 프로젝트에 최적화된" 스킬을 생성합니다. 이후에는 그 스킬이 이미 모든 경로를 알고 있습니다.

disable-model-invocation 이란

marketplace에서 rule → skill 변환 시 자동으로 추가되는 플래그입니다.

상태Claude의 동작언제 사용
없음 (기본)skill 본문을 절차로 실행실행 가능한 how-to skill
disable-model-invocation: true참조 자료로만 읽음, 절차 실행 안 함marketplace에서 변환된 rule 기반 skill
✅ marketplace build 동작: Rule을 marketplace에 포함시키면 Claude Code가 읽을 수 있는 skill 형태로 변환되지만, rule은 항상 constraint이므로 disable-model-invocation: true를 추가해 절차 실행을 막습니다. Claude는 rule 내용을 참조만 합니다.

Skill 카테고리 일람

monorepo
nx-best-practices
design-system
gsr-design-tokens, gsr-design-philosophy, gsr-shared-ui
git
conventional-commits, pre-stage-secret-scan, bitbucket-server
ui-domain-context
scaffold-domain-ui, scaffold-ui-isolation, validate-routing-rules, audit-design-system, update-context
api-integration
sync-api-contracts-init, scaffold-msw-handlers-init, openapi-first-flask-init, scaffold-flask-resource
auth
azure-ad-sso-nextjs, azure-ad-sso-flask
persistence
setup-local-datastore, provision-dynamodb-aws
deployment
deploy-flask-aws
debugging
root-cause
documentation
api-docs
code-review
are-we-done, pr-review, pr-review-be, security-review
qa-devops-collab
generate-unit-tests, generate-pytest-tests, scaffold-e2e-flow, check-deployment-readiness, check-flask-deploy-readiness, generate-pr-summary, address-pr-feedback, scrape-runtime-errors, audit-security-baseline, consolidate-tech-debt
edu-content
kiro-day-style

대표 Skill 4가지 분석

일반 are-we-done code-review/are-we-done
PR 열기 전 최후 관문. PR을 연 후에는 너무 늦기 때문에, 개발자가 코드를 완성했다고 생각할 때 실행합니다.

핵심 아이디어: "작성자는 자신의 코드를 가장 잘못 판단하는 사람" — 내가 만든 코드는 내가 왜 그렇게 했는지 이미 알기 때문에 갭을 못 봅니다. 그래서 신선한 컨텍스트를 가진 서브에이전트를 별도로 생성해 독립적으로 리뷰하게 합니다.

  • 요구사항 수집 (계획/티켓/원래 요청)
  • git diff로 변경사항 수집
  • 테스트 실행 출력 캡처
  • 독립 리뷰어 서브에이전트 생성 (완전히 새로운 컨텍스트)
  • SHIP / FIX-FIRST 판정 반환
⚡ 호출: /are-we-done 또는 "이거 다 됐어?", "리뷰해줘", "PR 열어도 돼?"
일반 root-cause debugging/root-cause
버그/테스트 실패/크래시를 수정하기 전에 근본 원인을 먼저 파악합니다.

핵심 원칙: 증상만 보고 코드를 수정하면 같은 버그가 다른 형태로 재발합니다. 먼저 신뢰할 수 있는 재현 경로를 만들고, 가설을 세우고, 검증한 후에 수정합니다.

  • "이 버그가 왜 일어나는가"를 먼저 파악
  • 재현 가능한 테스트 케이스 작성
  • 원인 검증 후 수정
  • 수정 후 회귀 테스트 추가
⚡ 트리거: "왜 이게 안 되지?", "이거 예전엔 됐는데", 간헐적 오류, 원인 모를 실패
scaffolder openapi-first-flask-init api-integration/openapi-first-flask-init
contract-first Flask/Connexion 서비스를 위한 one-time 설정. Scaffolder 패턴의 대표 예시.

실행 흐름:

  1. 프로젝트에서 OpenAPI spec 위치 스캔
  2. 출력 경로, 툴체인 선택 사용자에게 질문
  3. 프로젝트 전용 generate-flask-from-openapi/SKILL.md 생성
  4. 이후에는 /generate-flask-from-openapi로 반복 사용
⚡ 한 번만 실행 (프로젝트 설정), 이후엔 생성된 project-specific skill 사용
일반 kiro-day-style edu-content/kiro-day-style
교육 콘텐츠를 Kiro Day for GSR 사이트 스타일로 작성합니다. 이 문서 자체가 이 스킬을 사용해 작성됐습니다.
  • 페이지 구조 (hero, TOC, 섹션 순서)
  • 콜아웃 패턴 (ℹ️/✅/⚠️)
  • 생활 비유 글쓰기 ("마치 도서관처럼…")
  • 테이블 유형 선택 기준
  • 이모지 규칙 (의미 있을 때만)
⚡ 교육 문서 작성 시 자동 로드. 전체 스타일 레퍼런스는 design.md

Skills vs Rules — 언제 뭘 쓰는가

상황선택이유
"항상 TypeScript any를 쓰지 마"Rule모든 파일에 항상 적용되는 제약
"PR 열기 전에 독립 리뷰를 돌려"Skill특정 시점에 명시적으로 호출하는 절차
"커밋 메시지는 Conventional Commits로"Rule (+ skill로 참조)항상 적용, 세부 형식은 skill에서 조회
"Nx 모노레포 폴더 구조 어떻게 해?"Skill가이드 참조. 매번 강제하면 비효율
"Azure AD SSO 추가해줘"Skill특정 작업의 단계별 절차
"에러 났을 때 3번까지 자율 수정해"Rule자동 동작 정책 — 항상 적용