# AI Skills 운영 가이드

## 1. AI Skill이란 무엇인가

AI Skill은 **반복적으로 수행되는 작업을 AI가 안정적으로 실행할 수 있도록 정의한 작업 모듈**이다.
단순한 프롬프트 저장이 아니라 **작업 절차, 실행 규칙, 검증 기준을 함께 정의한 자동화 프로토콜**이다.

Skill을 사용하면 AI가 동일한 작업을 수행할 때 다음이 보장된다.

* 작업 절차의 일관성
* 실행 규칙 준수
* 결과 검증 가능

즉, Skill은 **AI 사용을 개인 프롬프트 수준에서 팀 표준 작업 프로세스로 전환하는 방법**이다.

---

# 2. Skill의 구성 요소

Skill은 다음 세 가지 요소로 구성된다.

### 1) 작업 절차 (Workflow)

AI가 수행해야 하는 단계적 작업 순서이다.

예시

* PR 리뷰 목록 수집
* 리뷰 단위 코드 수정
* 리뷰별 커밋 생성
* 커밋 push
* 리뷰 reply 작성
* 다음 리뷰 처리

---

### 2) 실행 규칙

작업 수행 시 반드시 따라야 하는 규칙이다.

예시

* 리뷰 단위로 작업 처리
* 각 리뷰마다 별도 커밋 생성
* 커밋 push 이후 reply 작성
* 특정 CLI 명령 필수 사용

---

### 3) 승인 요건 (검증 기준)

AI가 작업을 올바르게 수행했는지 확인하기 위한 기준이다.

예시

* 모든 리뷰 코멘트에 답글 작성
* 각 리뷰마다 별도 커밋 생성
* 모든 커밋이 push 완료
* 린트 / 빌드 테스트 통과

검증 기준이 없는 Skill은 재사용 안정성이 낮다.

---

# 3. Skill이 필요한 이유

AI를 프롬프트 방식으로 사용할 경우 다음 문제가 발생한다.

* 같은 프롬프트 반복 입력
* 작업 순서 불일치
* 검증 기준 누락

Skill을 사용하면 다음 효과가 있다.

* 반복 작업 자동화
* 작업 절차 표준화
* 결과 검증 가능

즉, Skill은 **AI를 대화 도구에서 작업 자동화 도구로 전환하는 구조**이다.

---

# 4. 우리 팀 Skill 운영 원칙

## 1) Skill은 Repository에 포함한다

Skill은 개인 환경이 아니라 **프로젝트 저장소에 포함하여 팀 전체가 공유한다.**

예시 구조

```
.agents/skills/      (Codex용)
.claude/skills/      (Claude용)
```

Repository에 포함하면 팀원이 동일한 Skill을 사용할 수 있다.

---

## 2) 공통 Skill + 도구별 어댑터 구조 사용

하나의 Skill을 여러 AI 도구에서 사용할 수 있도록 **공통 규칙과 도구별 설정을 분리한다.**

권장 구조

```
/ai-skills
    /core
        pr-review-flow.md
    /codex
        SKILL.md
    /claude
        SKILL.md
```

구성 설명

* **core**
  작업 절차와 규칙의 원본 정의

* **codex / claude**
  각 AI 도구에서 실행하기 위한 설정 파일

이 구조를 사용하면 **동일 Skill을 여러 AI 환경에서 사용할 수 있다.**

---

## 3) Skill에는 승인 요건을 반드시 포함한다

Skill에는 반드시 **자동 검증 가능한 기준**을 포함해야 한다.

예시

* 리뷰별 개별 커밋 생성
* 모든 커밋 push 완료
* 리뷰 reply 작성 완료
* 린트 / 빌드 테스트 통과

검증 기준은 **AI 작업의 정확도를 보장하는 핵심 요소**이다.

---

# 5. Skill 사용 방식

개발자는 간단한 요청으로 Skill을 실행할 수 있다.

예시

```
PR 리뷰 반영해줘
```

AI는 해당 요청을 Skill과 매핑하여 다음 절차를 수행한다.

1. PR 리뷰 수집
2. 리뷰 단위 코드 수정
3. 리뷰별 커밋 생성
4. 커밋 push
5. 리뷰 reply 작성
6. 검증 기준 검사

---

# 6. Skill 작성 원칙

Skill을 작성할 때 다음 기준을 따른다.

### 1. 반복 작업만 Skill로 만든다

일회성 작업은 Skill로 만들 필요가 없다.

---

### 2. 작업 절차를 명확히 정의한다

AI가 판단하지 않도록 **단계적 작업 순서를 명시한다.**

---

### 3. 승인 요건을 명확히 정의한다

작업 완료 여부를 **객관적으로 검증 가능해야 한다.**

---

# 7. Skill 예시 (PR 리뷰 반영)

예시 Skill 목적

PR 리뷰 코멘트를 기반으로 코드 수정, 커밋 생성, 리뷰 답글 작성까지 자동 처리

예시 승인 요건

* 리뷰별 별도 커밋 생성
* 모든 커밋 push 완료
* 각 리뷰 코멘트에 reply 작성
* reply에 커밋 해시 포함
* PR 충돌 해결
* 린트 / 빌드 테스트 통과

이 Skill을 사용하면 PR 리뷰 반영 작업을 **일관된 방식으로 자동 처리**할 수 있다.

---

# 8. 핵심 정리

AI Skill은 다음 역할을 한다.

* 반복 작업 자동화
* 작업 절차 표준화
* 결과 검증 가능

따라서 Skill은 **프롬프트 관리 기능이 아니라 팀 개발 프로세스를 AI에 적용하는 방식**이다.


AI Skills

코드 리뷰