AI 코딩 에이전트와 통합하기
k-ID는 k-ID가 지원하는 모든 관할 구역 요건에 대해 AI 코딩 에이전트에게 k-ID를 올바르게 통합하는 방법을 알려주는, 작고 조합 가능한 공식 Agent Skills 번들을 제공합니다. COPPA(미국), GDPR-Kids(EU), 영국 AADC, 영국 온라인 안전법(Online Safety Act), 브라질 ECA Digital, 호주 온라인 안전법 / 소셜 미디어 최소 연령 등 지역별 요건을 다룹니다. Claude Code, Cursor, OpenAI Codex, GitHub Copilot, Gemini CLI를 비롯해 오픈 Agent Skills 사양을 따르는 35개 이상의 AI 도구에서 동작합니다.
스킬은 github.com/kidentify/skills 에 있습니다.
두 가지 통합 형태
이 스킬은 k-ID의 두 가지 통합 형태를 모두 지원합니다. 라우터 스킬은 사용자 요청에서 해당하는 형태를 감지하고 그 형태에 필요한 스킬만 로드합니다.
- 형태 A — 완전 세션 통합. 연령 게이트 → 세션 → (동의 | 연령 확인 | 임계값) → 권한. 영속적인 사용자별 상태와 여러 게이트된 기능을 가진 게임, 소셜 플랫폼, 멀티 기능 앱에 적합. 5~7개의 스킬을 사용합니다.
- 형태 B — 독립 AgeKit+.
/age-verification/perform-access-age-verification에 대한 한 번의 호출, 사용자가 연령 확인을 완료하기 위한 iframe, 그리고 웹훅 또는 폴링을 통한 결과. 연령 게이트 없음, 세션 없음, 권한 없음. 18+ 사이트(영국 OSA), 연령 제한 다운로드, 호주 소셜 미디어 최소 연령 확인 또는 단일 연령 증명 결정에 적합. 2~3개의 스킬을 사용합니다.
커스텀 통합의 두 가지 UI 접근 방식
형태 A 안에서 k-ID는 연령 게이트와 부모 동의 흐름을 렌더링하는 두 가지 방법을 지원하며, 스킬은 둘 다 다룹니다. 정식 비교는 통합 방식 선택을 참조하세요. 요지는 다음과 같습니다.
- 커스텀 UX 워크플로우(기본값) — 연령 게이트와 동의 UI를 직접 구축하고
/age-gate/check,/challenge/send-email등을 직접 호출합니다. 가장 완성도 높고 브랜드와 가장 잘 어우러지는 경험을 제공하며, iframe을 사용하지 않고 인라인으로 렌더링되고, k-ID가 지원하는 모든 플랫폼(웹, Unity WebGL, 콘솔, 네이티브 데스크톱)에서 동작합니다. 프로덕션 통합에 권장되는 방식입니다. - 위젯(빠른 대체 경로) — 연령 게이트, 엔드투엔드 흐름(연령 게이트 + 부모 동의 + 데이터 고지 + 권한 + 부모 설정), 권한 관리, 데이터 고지를 위해 k-ID가 공개한 사전 제작 iframe입니다. 관할권에 맞는 연령 수집 방식을 처리하고, 필요 시 부모 동의 챌린지를 자동으로 시작합니다. 통합을 작고 단순하며 가능한 한 빠르게 출시해야 할 때(PoC, 내부 도구, 초기 단계의 게임 등) 선택하세요.
k-id-age-gate와 k-id-consent-and-challenges 두 스킬 모두 커스텀 경로(패턴 A)와 위젯 경로(패턴 B)를 문서화합니다. 에이전트에게 원하는 바를 말하면 알맞은 경로를 선택합니다.
스킬이 제공하는 것
함께 조합되는 초점이 명확한 8개의 스킬:
| 스킬 | 에이전트에 가르치는 내용 | 형태 |
|---|---|---|
k-id-integration | 라우터 — 형태를 감지하고 적절한 형제 스킬을 선택 | 둘 다 |
k-id-age-gate | /age-gate/check를 호출하는 완전 커스텀 슬라이더(패턴 A — 기본값, 외관 및 브랜드 통합 최상) 또는 k-ID의 연령 게이트 위젯(패턴 B — 작고 단순하며 빠르게 출시해야 할 때의 대체 경로)으로 연령 게이트를 구축 — 형태 A의 진입점 | A |
k-id-consent-and-challenges | GUARDIAN이 관리하는 미성년자 부모 동의 — QR + OTP + 이메일 + 직접 링크가 있는 커스텀 동의 화면과 모달 외부의 앱 최상위에서 수행하는 폴링(패턴 A — 기본값), 또는 엔드투엔드/권한 관리 위젯(패턴 B — 대체 경로) | A |
k-id-age-verification | 연령 확인 및 연령 보증 — 독립 AgeKit+(패턴 1), 세션 내 미확인 성인(패턴 2), 권한별 verifiedAgeThreshold 흐름(패턴 3, 영국 OSA 18+, 브라질 ECA Digital, 호주 소셜 미디어 최소 연령 등) | 둘 다 |
k-id-sessions-and-permissions | 세션 처리, 권한 게이팅된 UI 컨트롤, /session/upgrade 형태, verifiedAgeThreshold 처리 | A |
k-id-webhooks | 원시 본문에 대한 HMAC-SHA256 서명 검증, 멱등성, 이벤트 핸들러 | 둘 다 |
k-id-server-trust-boundary | API 키 배치, 서버 프록시, 사전 점검 | 둘 다 |
k-id-mobile-native | iOS / Android / Unity 플랫폼 연령 신호와 인앱 브라우징 | A(일반적으로) |
에이전트가 k-id-integration을 활성화하면 사용자의 작업을 읽고 올바른 기능 스킬과 횡단 스킬의 조합을 끌어옵니다 — 개별적으로 설치할 필요가 없습니다.
설치 전에
- Compliance Studio에 API 키와 웹훅 시크릿이 포함된 프로덕트가 필요합니다. API 인증 가이드를 참조하세요.
- 스킬은 이 문서 사이트의 API 형식을 참조합니다. AI 에이전트의 아웃바운드 네트워크 접근을 차단했다면
docs.k-id.com을 허용하세요.
도구별 설치
아래 모든 설치 경로는 동일한 8개 스킬을 에이전트 컨텍스트에 적재합니다. 사용 중인 도구에 해당하는 행을 선택하세요.
Claude Code(가장 빠름)
Claude Code 내부에서 실행:
/plugin marketplace add github.com/kidentify/skills
/plugin install k-id-skills@kidentify
이 플러그인은 8개의 스킬을 한 번에 등록합니다. /plugin list로 확인하세요. 마켓플레이스는 git 형식(github.com/... 또는 https://github.com/...)으로 추가하세요. plugins[].source 스키마 오류가 나면 스킬 저장소의 .claude-plugin/marketplace.json에서 각 플러그인 source가 ./로 시작하는 상대 경로인지 확인하세요(Claude Code 플러그인 marketplaces).
Cursor
저장소의 skills/를 프로젝트의 .agents/skills/(또는 .cursor/skills/)에 둡니다. 프로젝트 스킬은 이 경로에서 자동으로 발견되고, 사용자 전역은 ~/.agents/skills/ 또는 ~/.cursor/skills/입니다. Cursor Agent Skills를 참조하세요.
mkdir -p .agents/skills
git clone --depth 1 https://github.com/kidentify/skills.git /tmp/k-id-skills
cp -R /tmp/k-id-skills/skills/* .agents/skills/
rm -rf /tmp/k-id-skills
Cursor를 다시 로드하고 채팅을 열어 스킬이 에이전트의 사용 가능한 도구에 나타나는지 확인합니다. 대부분의 경우 Cursor는 재시작 없이 새 스킬을 인식합니다.
OpenAI Codex / Codex CLI
Codex는 현재 작업 디렉터리에서 저장소 루트까지의 .agents/skills/와 사용자 전역 ~/.agents/skills/에서 스킬을 찾습니다(OpenAI Codex CLI·IDE 확장 공식 문서). ~/.codex/skills/는 하위 호환으로 읽힐 수 있으나 주 경로가 아닙니다. 프로젝트는 위 Cursor와 동일한 방법을 쓰고, 전역은 다음과 같습니다.
mkdir -p ~/.agents/skills
git clone --depth 1 https://github.com/kidentify/skills.git /tmp/k-id-skills
cp -R /tmp/k-id-skills/skills/* ~/.agents/skills/
rm -rf /tmp/k-id-skills
Codex Agent Skills를 참조하세요.
GitHub Copilot / Visual Studio Code
Visual Studio Code의 GitHub Copilot은 프로젝트 스킬을 .github/skills/, .claude/skills/, 또는 .agents/skills/에서 읽습니다(Visual Studio Code에서 Agent Skills 사용). 개인 스킬은 ~/.copilot/skills/, ~/.claude/skills/, 또는 ~/.agents/skills/입니다. 저장소의 skills/ 트리를 원하는 경로에 복사하세요. GitHub 문서와 맞추려면 .github/skills/가 무난합니다.
mkdir -p .github/skills
git clone --depth 1 https://github.com/kidentify/skills.git /tmp/k-id-skills
cp -R /tmp/k-id-skills/skills/* .github/skills/
rm -rf /tmp/k-id-skills
Chat에서 /skills로 표시를 확인하세요. 다른 루트는 chat.agentSkillsLocations로 추가할 수 있습니다.
Gemini CLI
Gemini CLI는 사용자 스킬을 ~/.gemini/skills/ 또는 ~/.agents/skills/에, 워크스페이스 스킬을 .gemini/skills/ 또는 .agents/skills/에 둡니다(같은 계층에서는 .agents/skills/가 우선). Gemini CLI Agent Skills 참조. 전역 예:
mkdir -p ~/.gemini/skills
git clone --depth 1 https://github.com/kidentify/skills.git /tmp/k-id-skills
cp -R /tmp/k-id-skills/skills/* ~/.gemini/skills/
rm -rf /tmp/k-id-skills
팀 공유용 저장소 내 설치는 Cursor와 같이 .agents/skills/ 또는 .gemini/skills/에 두면 됩니다. gemini skills install https://github.com/kidentify/skills.git도 사용할 수 있습니다(CLI 스킬 관리 참조).
기타 도구 및 에어갭 환경
Agent Skills 사양을 따르는 모든 AI 에이전트는 이 스킬을 사용할 수 있습니다. Agent Skills 클라이언트 쇼케이스에는 35개 이상의 호환 도구가 나열되어 있습니다. 각 도구는 스킬을 어디에서 읽어오는지 문서화하고 있습니다 — 디렉터리만 알면 복사 레시피는 동일합니다.
아웃바운드 접속이 차단된 환경이라면 GitHub의 녹색 "Code" 버튼으로 ZIP을 내려받아 환경으로 옮긴 뒤 skills/ 디렉터리를 에이전트용 도구 스킬 경로에 추출하세요.
이 설치 경로는 Cursor, OpenAI Codex, Visual Studio Code의 GitHub Copilot, Gemini CLI 문서와 대조했습니다(2026년 5월 15일 기준). 경로가 바뀌면 각 제품 문서와 Agent Skills 클라이언트 쇼케이스를 따르세요.
스킬 사용 방법
설치 후에는 자연어로 에이전트에게 작업을 설명하기만 하면 됩니다:
- "Next.js 앱에 k-ID를 통합해 줘."
- "QR, OTP, 이메일로 부모 동의 화면을 추가해 줘."
- "Compliance Studio의 Test 이벤트로 웹훅 핸들러를 검증해 줘."
- "iOS에서 선언된 연령 범위를 연령 게이트 이전에 읽어 줘."
라우터 스킬(k-id-integration)이 가장 먼저 활성화되어 요청을 읽고 올바른 전문 스킬에 인계합니다. 스킬 이름을 외울 필요가 없습니다.
스킬이 인코딩하는 패턴에 대한 더 깊은 질문은 관련 개념 페이지를 참조하세요:
스킬 설계 원칙
- 문서 우선. API 요청 및 응답 형식은 이 문서 사이트에서 가져옵니다. 스킬은 통합 패턴과 알려진 함정만 인코딩하므로 k-ID 쪽의 형식 변경이 스킬을 낙후시키지 않습니다.
- 불변 조건은 인라인. 각
SKILL.md에는 실제로 발생했던 버그를 방지하는 규칙을 "Gotchas" 섹션으로 인라인으로 포함하며, 각 규칙에는 한 줄의 "이유"가 함께 제공됩니다. - 필요한 부분만 엄격히 규정. 깨지기 쉬운 작업(API 본문 형식, 서명 검증)은 정확히 지정합니다. UI 조정과 프레임워크 선택은 사용자가 결정합니다.
- 마지막에 검증. 모든 기능 스킬은 검증 체크리스트로 끝나, 에이전트가 완료를 선언하기 전에 통합이 실제로 동작함을 확인합니다.
관련
- Agent Skills 사양
- Agent Skills 클라이언트 쇼케이스 — 35개 이상의 호환 AI 도구
github.com/kidentify/skills— 저장소- API 인증
- 테스트 가이드