Custom Agent Skills로 온보딩 표준화

Custom Agent Skills로 온보딩 표준화 (Standardize Onboarding with Custom Agent Skills)

프로젝트별 온보딩·거버넌스 지침을 Claude Code, Codex, Cursor 등 코딩 에이전트에 Confident AI에서 제공하는 방법을 설명하는 문서예요. 이 문서에서는 커스텀 스킬 생성, 조직 설정, 거버넌스 스킬 정의, 설치와 검증, 그리고 인증·라우팅 작동 방식을 다뤄요.

출처: 문서

본문

개요 (Overview)

이 가이드는 제품 팀을 Claude Code, Codex, Cursor, Windsurf 등 Agent Skills 표준을 지원하는 AI 코딩 도구로 온보딩할 표준화된 방법이 필요한 플랫폼·거버넌스 팀을 위한 문서예요.

모든 팀이 로컬 지침 파일을 손으로 복사하게 하는 대신, Confident AI가 git smart-HTTP로 /skills.git에서 각 프로젝트에 맞는 Custom Agent Skills를 제공할 수 있어요. 제품 팀이 프로젝트 API 키로 스킬을 한 번 설치하면, 엔드포인트가 그 프로젝트에 맞춰진 읽기 전용 저장소를 반환해요.

이 가이드에서 여러분은:

Organization Settings에서 프로젝트별 라우팅과 함께 온보딩 지침을 게시해요.
프로젝트에 할당된 거버넌스 폴리시에서 거버넌스 지침을 한 번 정의해요.
Skills CLI로 코딩 에이전트에 프로젝트별 스킬을 설치해요.
생성된 저장소에 예상한 SKILL.md 파일이 있는지 검증해요.

결국 각 제품 팀은 같은 URL 패턴을 설치하면서도, 그들의 프로젝트와 폴리시 요구사항에 맞는 지침을 받아요.

구축하기 (Build It)

커스텀 스킬 만들기

제품 팀이 Confident AI에서 설치할 때 받을 Custom Agent Skills를 만드세요.

Organization Settings에서 관리되는 온보딩 스킬을 프로젝트 설정 지침에 사용해요. 예:

필수 패키지 매니저와 설정 명령
저장소 컨벤션
테스트, 평가, 린터 실행 방법
트레이스를 계측하고 결과를 Confident AI로 보내는 방법
팀별 코딩 워크플로 기대치

거버넌스 폴리시에 한 번 정의된 거버넌스 스킬을 폴리시 요구사항에 사용해요. 예:

병합 전 필수 평가 게이트
트레이스, 알림, 위험 평가 요구사항
승인된 모델, 데이터 처리, 릴리스 관행
AI 동작을 바꾸기 전에 코딩 에이전트가 확인해야 할 것

생성된 각 스킬은 저장된 스킬 description을 SKILL.md 프론트매터 설명으로, 저장된 스킬 body를 마크다운 본문으로 사용해요.

Organization Settings에서 온보딩 구성

Confident AI는 onboarding 스킬을 다음 순서로 해석해요:

프로젝트에 온보딩 스킬이 있으면 그 스킬을 사용해요.
그렇지 않으면 조직의 온보딩 스킬로 폴백해요.

조직 수준 온보딩 스킬은 Organization Settings에서 구성해요. 이렇게 하면 플랫폼 팀이 기본 온보딩 스킬을 한 번 정의하고, 특별한 요구사항이 있는 프로젝트에만 재정의할 수 있어요.

조직 온보딩은 넓고 안정적으로 유지하세요. 팀별 설정, 서비스 소유자, 로컬 명령, 저장소 제약은 프로젝트 온보딩 스킬에 넣어요.

폴리시에 거버넌스를 한 번 정의

Confident AI는 프로젝트에 할당된 거버넌스 폴리시에서 governance 스킬을 해석해요.

폴리시에 거버넌스 스킬을 한 번 정의하고 프로젝트를 그 폴리시에 할당해요. 폴리시가 거버넌스하는 모든 프로젝트는 프로젝트 API 키를 사용할 때 같은 skills/governance/SKILL.md 콘텐츠를 받아요.

거버넌스 스킬은 폴리시 기반이라, 코딩 에이전트는 그 폴리시가 거버넌스하는 다른 모든 프로젝트와 같은 지침을 받아요.

코딩 에이전트에 스킬 설치

제품 팀에 프로젝트 API 키와 Confident AI 호스트를 주세요. 그들은 --skill로 스킬 이름을 지정해 Skills CLI로 한 번에 하나씩 설치해야 해요:

npx skills add "https://apikey:PROJEC...git" --skill onboarding
npx skills add "https://apikey:PROJEC...git" --skill governance

온보딩 스킬에는 --skill onboarding, 거버넌스 스킬에는 --skill governance를 사용해요.

HTTP Basic auth의 사용자 이름은 무시돼요. 비밀번호 필드가 프로젝트 API 키를 담으므로, URL은 관례적 자리 표시자 사용자 이름으로 apikey만 사용해요.

로컬 git 검증을 위해 같은 엔드포인트를 직접 클론할 수도 있어요:

git clone https://apikey:PROJEC....git

프로젝트 API 키는 비밀처럼 취급하세요. 실제 키가 들어간 설치 명령을 소스 컨트롤, 셸 히스토리 스니펫, 티켓, 공유 문서에 커밋하지 마세요.

생성된 저장소 검증

클론이나 설치 후, 저장소가 그 프로젝트에 대해 해석된 스킬을 포함하는지 확인해요:

skills/
  onboarding/
    SKILL.md
  governance/
    SKILL.md

각 SKILL.md를 열어 다음을 확인해요:

온보딩 스킬이 Organization Settings에서 구성된 콘텐츠나 프로젝트별 재정의와 일치하는지
거버넌스 스킬이 프로젝트에 할당된 거버넌스 폴리시와 일치하는지
마크다운이 코딩 에이전트에게 구체적인 명령, 검사, 프로젝트 기대치를 주는지

코딩 에이전트가 작업을 시작하면 이 스킬들을 읽고, 제품 팀 전반에 같은 온보딩·거버넌스 지침을 적용할 수 있어요.

인증과 라우팅 작동 방식

/skills.git 엔드포인트는 읽기 전용이고 git smart-HTTP로 제공돼요. 인증은 HTTP Basic auth를 사용해요:

사용자 이름은 무시돼요
비밀번호는 프로젝트 API 키여야 해요
키는 공개 API가 쓰는 것과 같은 캐시·데이터베이스 조회로 해석돼요
해석된 키가 저장소 구축에 사용되는 프로젝트와 조직을 결정해요

인증되면 Confident AI는 Skill 테이블에서 스킬을 해석해요:

onboarding은 프로젝트 스킬을 먼저 사용하고, 그다음 조직 스킬로 폴백해요.
governance는 프로젝트에 할당된 거버넌스 폴리시에 정의된 스킬을 사용해요.

서버는 해석된 각 스킬에 대해 skills/<name>/SKILL.md 파일 하나를 쓰고, git upload-pack --stateless-rpc로 임시 저장소를 제공하며, 응답이 끝나면 임시 저장소를 삭제해요.

롤아웃 패턴 (Rollout Pattern)

큰 조직이라면 Organization Settings의 조직 수준 온보딩 스킬 하나와 거버넌스 폴리시별 거버넌스 스킬 하나로 시작해요. 그런 다음 특별한 설정이 필요한 몇 개 팀으로 프로젝트 수준 온보딩 재정의를 파일럿해요.

콘텐츠가 안정되면 제품 팀은 모든 프로젝트에 같은 설치 패턴을 쓸 수 있어요:

npx skills add "https://apikey:PROJEC...git" --skill onboarding
npx skills add "https://apikey:PROJEC...git" --skill governance

프로젝트 API 키가 라우터예요. 팀은 지침이 어느 저장소, 브랜치, 파일 경로에 있는지 기억할 필요가 없어요. Confident AI가 키 뒤에 있는 프로젝트에 맞는 올바른 스킬 콘텐츠를 제공해 줘요.

Custom Agent Skills로 온보딩 표준화