만 단어 프롬프트 대신 Agent Skills로 팀용 프런트엔드 리뷰 스킬 만들기

팀에서 누군가 AI로 PR을 봐주기 시작하면, 금세 똑같은 문제에 부딪히게 된다. 모든 사람의 대화창마다 '프론트엔드 리뷰 규범' 한 부씩이 들어차 있는 것이다. 오늘은 세 줄을 추가하고, 내일은 두 줄을 지우고, 누군가는 지난달 버전을 그대로 복사해 오기도 한다. 규범 자체는 틀리지 않았다. 잘못된 것은 그것이 있어야 할 곳에 있지 않다는 점이다. 즉 채팅 기록 속에 있지, 저장소에 있지 않다.

Agent Skills가 하는 일은 아주 소박하다. '어떤 종류의 작업을 어떻게 할지'를 하나의 폴더로 정리하는 것이고, 핵심은 SKILL.md 한 부다. 어시스턴트가 필요할 때 직접 읽으면 되고, 매번 만 자짜리 매뉴얼을 Prompt에 붙여 넣을 필요가 없다. 2026년 10월 22일, Anthropic은 이 개방 표준을 Linux 재단 산하의 Agentic AI Foundation(AAIF)에 기증했다. 규범은 계속 개방되며, 이름, 로고, GitHub 조직과 agentskills.io까지 함께 넘겨 여러 제품에서 공용할 수 있게 했다.

이 글은 개념 순례를 하지 않는다. 목표는 딱 하나다. 다 읽고 나면 프론트엔드 리뷰 Skill 한 부를 저장소에 복사해 넣고, 그날 바로 사용할 수 있게 하는 것. 글 말미에 완전한 템플릿이 있고, 함께 딸린 demo/ 디렉터리로도 검증 스크립트를 곧바로 실행할 수 있다.

먼저 구분하자: Prompt, AGENTS.md, Skill은 각각 무엇을 맡는가

입에 담을 때는 다들 섞어 말하기 좋아하지만, 실제로 적용할 때는 구분하는 게 좋다.

| 항목 | 더 닮은 것 | 담기 좋은 것 | | --- | --- | --- | | 일회성 Prompt | 그 자리에서 하는 지시 | "이번에는 이 diff를 봐 줘" | | 프로젝트 수준 설명(예: AGENTS.md류) | 입사 안내서 표지 | 저장소 규약, 디렉터리 구조, 기본 어조 | | Agent Skill(SKILL.md) | 벽에 붙은 특정 작업 카드 | 특정 유형 작업의 고정 절차 (예: 프론트엔드 리뷰) |

Skill의 가치는 '더 길게 쓰기'가 아니라 발견 가능하고, 재사용 가능하며, 필요할 때 로딩된다는 데 있다. 규범에서는 이를 progressive disclosure(점진적 공개)라고 부른다. 시작할 때는 각 skill의 name + description만 보고, 실제로 작업과 매칭될 때에야 완전한 SKILL.md를 읽으며, 스크립트와 참고 문서는 그 뒤에 필요에 따라 연다. 이렇게 하면 저장소에 skill을 많이 걸어 두어도 처음부터 컨텍스트를 터뜨릴 필요가 없다.

1차 설명은 다음에서 볼 수 있다. Agent Skills 규범, Anthropic 기증 공고(2026-10-22).

Skill 디렉터리는 대체 어떻게 생겼나

최소한 파일 하나만 있으면 된다.

frontend-review/ └── SKILL.md

조금 더 완전하게 만들면 이렇게 된다(뒤의 세 디렉터리는 모두 선택 사항).

frontend-review/ ├── SKILL.md # 필수: YAML 헤더 + Markdown 본문 ├── scripts/ # 선택: 실행 가능한 스크립트 ├── references/ # 선택: 필요 시 읽는 보충 설명 └── assets/ # 선택: 템플릿, 정적 리소스

SKILL.md는 반드시 YAML frontmatter로 시작해야 한다. 규범은 최소 두 개 필드를 요구한다.

- name: 소문자 / 숫자 / 하이픈이며, 디렉터리 이름과 일치해야 하고, --를 쓸 수 없으며, 앞뒤에 -가 올 수 없다.

- description: 무엇을 하는지, 언제 쓰는지를 분명히 밝힌다. 이것이 어시스턴트가 '너를 활성화할지'를 결정하는 주된 근거다.

선택 필드로는 license, compatibility, metadata, allowed-tools(실험성) 등이 있다. 본문 작성에는 강제 템플릿이 없지만, 공식 권장은 본문을 너무 비대하게 만들지 말고 세부 자료는 references/로 분리하고, 스크립트화할 수 있는 것은 scripts/에 넣으라는 것이다.

최소 골격은 이렇게 생겼다.

--- name: frontend-review description: Review frontend code changes in this repo. Use when the user asks for code review, PR review, 前端 review, 检查改动, or before merging UI changes. --- # 프론트엔드 리뷰 순서대로 실행: 변경 범위 파악 → 타입 체크 → Lint → 위험 변경 금지 구역. 고정된 구조로 결론을 출력하고, 빈말은 적게 쓴다.

이 몇 줄만으로도 이미 '리뷰 규범을 새 대화마다 붙여 넣기'보다 낫다. 버전 관리에 들어갔으니, 한 군데만 고치면 다음 세션에서 팀 전체가 그대로 누릴 수 있기 때문이다.

왜 프론트엔드 리뷰가 첫 Skill로 적합한가

모든 프로세스가 skill로 만들 가치가 있는 것은 아니다. 프론트엔드 리뷰는 마침 몇 가지 지점을 건드린다.

- 단계가 안정적이다: 먼저 범위를 보고, 그다음 typecheck, 그다음 lint, 그다음 민감한 면을 본다. 사람이 리뷰할 때도 이 순서다.

- 명령을 실행할 수 있다: tsc --noEmit, eslint, biome이 '이 코드는 우아하게 쓰인 것 같다'보다 신뢰할 만하다.

- 금지 구역이 명확하다: .env, 인증, dangerouslySetInnerHTML, origin을 검증하지 않은 postMessage…… 목록으로 뽑아낼 수 있다.

- 팀의 말투를 통일해야 한다: 가장 걱정되는 것은 각자 Prompt에 제각각 '반드시 고쳐야 함 / 고치면 좋음'을 적는 것이다.

한마디로, '우리 팀이 프론트엔드를 어떻게 리뷰하기로 했는가'를 채팅 기록에서 저장소로 옮기는 것이다.

직접 해보기: 쓸 만한 '프론트엔드 리뷰' Skill 작성하기

아래 내용은 글 말미의 demo/frontend-review/SKILL.md와 같은 출처이며, 그대로 복사할 수 있다. 여러분 저장소의 스크립트 이름에 맞춰 두 군데만 고치면 된다.

--- name: frontend-review description: Review frontend code changes in this repo. Use when the user asks for code review, PR review, 前端 review, 检查改动, 帮我看看这段代码, or before merging UI/React/Vue/Next changes. Runs typecheck then lint, then checks a deny-list of risky paths. Do not invent security exploits; only report defensive findings. license: MIT metadata: author: team-frontend version: "1.0" audience: frontend --- # 프런트엔드 Review Skill 당신은 이 저장소의 **프런트엔드 변경 검토**를 돕고 있습니다. 목표는 장문의 글을 쓰는 것이 아니라, 정해진 순서에 따라 문턱을 점검하고 실행 가능한 결론을 내는 것입니다. ## 언제 활성화되는가 사용자가 code review / PR review / 检查改动 / 帮我看看这段前端代码(이 프런트엔드 코드 좀 봐줘) / merge 전 자체 점검을 언급할 때 이 skill을 활성화합니다. ## 강경 규칙(순서대로, 건너뛰지 말 것) 1. **변경 범위를 명확히 파악** - 먼저 이번 관련 파일을 나열한다(`git status` / `git diff --stat`, 또는 사용자가 붙여넣은 조각). - 요구 범위를 벗어난 곁다리 리팩터링: 「별도 PR을 여는 것을 권장」으로 표시하고, 기본적으로 사용자를 대신해 직접 고치지 않는다. 2. **타입 검사** - 저장소에 TypeScript가 있으면 프로젝트 스크립트를 우선 실행한다. 예를 들어: - `pnpm typecheck` / `npm run typecheck` / `npx tsc --noEmit` - 오류가 있으면: 먼저 오류 경로와 정보를 붙여 보여주고, 그다음에 스타일을 논한다. 3. **Lint** - ESLint / Biome / Oxlint가 있으면 해당 스크립트를 실행한다. 예를 들어 `pnpm lint`. - 이번 변경과 관련된 경고만 고친다. 저장소 전체의 누적 부채는 따로 기록하고, 이를 핑계로 대청소하지 않는다. 4. **위험 변경 금지 구역(방어 체크리스트)** diff가 다음 경로나 패턴을 건드리면 반드시 **명시적으로 빨간색 표시**하고, 사람의 확인을 받은 뒤 계속 진행할 것을 요구한다: - `**/.env*`, 키, Token, 개인 키, 내부망 주소 하드코딩 - `**/auth/**`, 로그인 상태, Cookie / LocalStorage 민감 필드写入 - `dangerouslySetInnerHTML`, 살균되지 않은 HTML 조합 - `postMessage` / `iframe`의 `origin` 미검증 - 의존성 잠금 파일이 무관한 변경으로 대규모 재작성됨 - CSP, CORS, CSRF, 권한 검사 관련 코드 삭제 또는 약화 - 사용자 입력을 그대로 `eval`, 동적 `Function`, 미검증 라우팅 점프에 조합 **방어적 설명만** 한다: 위험 지점과 제안 수정 방식을 지적한다. 재현 가능한 공격 절차, PoC, payload는 제시하지 않는다. ## 출력 형식(구조 그대로 따라 쓸 것) (출력 템플릿 시작) ## Review 결론 - 결론: 통과 / 조건부 통과 / 불통과 - 한 문장 이유: … ## 수행한 검사 - [ ] 변경 범위 확인 완료 - [ ] 타입 검사: 통과 / 실패 / 저장소에 스크립트 없음(설명) - [ ] Lint: 통과 / 실패 / 저장소에 스크립트 없음(설명) - [ ] 금지 구역: 미해당 / 해당(파일 나열) ## 반드시 수정 1. … ## 수정 권장 1. … ## 나중에 해도 되는 것 1. … (출력 템플릿 끝) ## 작성 톤 - 동료가 리뷰하듯: 짧은 문장, 파일 지목, 형용사 최소화. - 확실하지 않으면 확실하지 않다고 말하고, 사용자가 확인해야 할 점을 적는다.

금지 구역 세부 규칙은 references/denylist.md에 따로 두고, 본문에서 거기로 링크할 수 있다 — 이는 정확히 progressive disclosure를 활용하는 것으로, 평소에는 컨텍스트를 차지하지 않고 실제로 민감한 변경을 만났을 때만 펼쳐진다.

저장소에 붙여넣기: 어떻게 두고, 어떻게 검증하고, 어떻게 부르는가

1) 디렉터리를 어디에 두는가

공식 Quickstart(VS Code 기준)는 기본적으로 프로젝트 아래에서 찾는다:

mkdir -p .agents/skills cp -R frontend-review .agents/skills/

제품마다 스캔 경로는 조금씩 다를 수 있지만, 파일 형식은 동일한 한 세트다. 현재 사용 중인 Agent 문서를 기준으로 하라. 핵심은: name 필드와 폴더 이름이 모두 frontend-review라는 점이다.

2) 먼저 skill 자체가 제대로 작성됐는지 검증

함께 제공되는 스크립트는 네트워크에 연결하지 않고, frontmatter, 명명, 줄 수만 검사한다:

bash demo/frontend-review/scripts/check-skill.sh

다음과 비슷한 출력이 보여야 한다:

OK: frontmatter 구분자 OK: name=frontend-review OK: description 길이 … OK: SKILL.md 줄 수 … 전부 통과. 이 디렉터리를 저장소의 .agents/skills/frontend-review/에 복사하면 바로 시험해볼 수 있다.

규범 문서에서는 공식 참조 구현에 있는 skills-ref validate ./my-skill로 더 완전한 검증을 할 수 있다고도 언급한다. 위의 bash 스크립트는 「의존성 제로, 즉석에서 실행 가능」을 위해 준비한 것이다.

3) 대화에서 어떻게 트리거하는가

새로운 한 라운드의 Agent 대화를 열고, 그냥 사람 말로 하면 된다. 예를 들어:

前端 review skill에 따라 현재 변경 사항을 심사해줘. 먼저 typecheck, 그다음 lint.

또는:

이건 React PR이야, code review 해줘.

어시스턴트는 먼저 description을 통해 frontend-review를 매칭하고, 그다음 본문을 로드하여 네 개의 관문에 따라 출력해야 한다. 만약 그것이 겉치레로 코드를 칭찬만 하고 검사를 실행하지 않는다면, skill의 「강경 규칙」을 더 강하게 쓰거나, 더 말을 잘 듣는 Agent 모드 / 모델로 바꿔라 — 도구 순응도는 제품에 따라 다르며, 이 점은 공식 Quickstart도 솔직히 적어 두었다.

4) CI와의 분업

Skill은 대화 속의 공정 카드이고, CI는 머지 관문이다. 전자는 일상적인 자체 점검 효율을 높이고, 후자는 대체되어서는 안 된다. typecheck / lint는 빨간불이어야 할 때 여전히 빨간불이어야 한다.

「그럴듯한」 Review 출력은 어떤 모습인가

동료가 로그인 페이지 근처의 컴포넌트를 고쳤고, 겸사겸사 postMessage 리스너도 건드렸다고 가정하자. Skill이 실행된 뒤 이상적인 출력은 대략 아래와 같다(예시일 뿐, 템플릿을 외우라는 뜻이 아니다):

Review 결론 - 결론: 조건부 통과 - 한 줄 이유: 타입 검사와 Lint는 통과했지만 `src/features/auth/sessionBridge.ts`의 postMessage가 origin을 검증하지 않아 수동 확인이 필요함. ## 실행한 검사 - [x] 변경 범위 확인 완료(5 files) - [x] 타입 검사: 통과(pnpm typecheck) - [x] Lint: 통과(pnpm lint) - [x] 금지 구역: sessionBridge.ts 적중(postMessage) ## 반드시 수정 1. `sessionBridge.ts`: 메시지를 처리하기 전에 `event.origin`을 검증하고, 화이트리스트 도메인만 허용할 것; 출처가 불명확하면 바로 return. 2. access token을 `localStorage`의 디버그 필드에 쓰지 말 것; 기존 session 래퍼를 사용할 것. ## 수정 권장 1. 로그인 버튼의 loading 상태와 오류 문구를 분리할 것, 실패 시 버튼이 계속 돌아가는 일을 피하기 위해. ## 나중에 해도 되는 것 1. 겸사겸사 재정렬한 무관한 import는 별도 PR을 열 것을 권장, 인증 변경과 묶지 말 것.

두 가지에 주의하라:

- 「조건부 통과」는 정상 상태이지, 애매하게 넘기는 것이 아니다. 금지 구역에 적중했다면 잠깐 멈춰야 한다.

- 반드시 수정 / 수정 권장 / 나중에 로 하는 분류가 한 편의 소논문보다 병합하기 좋다. 사람이 리뷰하는 시간도 아낀다: 「반드시 수정」에 빠진 게 없는지만 확인하면 된다.

만약 어시스턴트가 여전히 「전반적으로 좋은데 성능에 주의하세요」 같은 빈말을 출력한다면, 돌아가서 skill 본문을 고쳐라: 출력 형식을 강제 구조로 쓰고, 파일 경로 없는 칭찬을 명시적으로 금지하라.

팀 적용: 한 번에 작업 카드 열두 장을 발명하지 말라

이 순서로 확장할 것을 권한다:

- 먼저 Review(본문)를 올려라: 이득이 매일의 PR 대화에 즉시 드러난다.

- 다음으로 「새 페이지 / 새 컴포넌트」를 보강하라: 디렉터리, 명명, story / 테스트 필요 여부를 규정한다.

- 마지막에야 좁은 영역 skill(예: 「차트 수정」「폼 검증 수정」)을 만들어라, 처음부터 스킬 목록이 컴포넌트 라이브러리보다 길어지는 것을 피하기 위해.

협업에는 세 가지 실용적인 점이 있다:

- Skill의 수정은 PR로 진행하고, reviewer는 「공정이 더 엄격해졌는지/느슨해졌는지」를 본다, 문장 솜씨가 아니다.

- description 변경은 회귀 테스트를 해야 한다: 팀의 고빈도 입버릇으로 세 라운드 트리거를 시험하라.

- README나 기여 가이드에 한 줄 써라: 「프런트 자체 점검은 먼저 frontend-review skill을 불러도 된다」——말로 하는 홍보보다 오래간다.

「규범을 시스템 Prompt에 적어 넣기」와 비교해, Skill은 두 가지가 더 있다: 버전과 필요 시 로딩. 시스템 Prompt는 한 번 고치면 모든 대화에 영향을 준다; Skill은 관련 작업에서만 불려 어쩌면 고치기도 더 과감해진다.

description은 어떻게 써야 불러낼 수 있는가

많은 사람이 description을 「코드 검토를 돕는다」라고 쓴다——너무 허무맹랑해서 어시스턴트가 언제 활성화해야 할지 모른다.

더 나은写法은 두 가지를 동시에 답한다: 무엇을 할 것인가, 그리고 사용자가 어떻게 너를 부를 수 있는가:

description: Review frontend code changes in this repo. Use when the user asks for code review, PR review, 前端 review, 检查改动, 帮我看看这段代码, or before merging UI/React/Vue/Next changes.

중영문 키워드를 조금씩 넣어도 되고, 여러분 팀의 실제 입버릇에 맞춰라. description을 고친 뒤에는 실제로 할 법한 서너 문장으로 트리거를 시험하라; 나서야 할 때 나서지 않는다면, 대개 설명이 너무 좁거나 너무 뜬 것이지, 본문이 충분히 길지 않은 게 아니다.

흔한 함정(우리가 밟았거나 남이 밟는 것을 본 것)

name과 디렉터리 이름이 불일치

규범에는 반드시 일치하라고 명시되어 있다. 디렉터리는 frontend-review인데 name을 FrontendReview로 썼다면, 곧바로 불합격이다.

설계 문서 한 권을 통째로 SKILL.md에 넣기

규범은 본문의 분량을 통제하고 세부 사항은 외부로 빼둘 것을 권한다. Review skill은 특히 3년 전 컴포넌트 규범 전문을 붙여 넣지 말아라; references/나 저장소 문서 경로로 링크하면 된다.

금지 구역을 「공격 튜토리얼」로 쓰기

방어 체크리스트에는 「무엇을 건드리면 빨간불을 켜야 하는지, 어떻게 조이는 것을 권하는지」만 쓴다. PoC를 쓰지 말고, payload를 쓰지 말라. 서드파티 skill은 scripts/를 먼저 통독한 뒤 설치해야 한다——공식 연구 글도 검토한 출처만 신뢰하라고 강조한다.

skill이 사람 검토를 대체할 것이라 기대하기

그것은 고정된 공정과 누락 항목 알림에 능하다; 제품 의미, 상호작용의 합리성은 여전히 사람이 정한다. 결론에 「조건부 통과」를 남기는 것이 억지로 「통과」를 주는 것보다 더 정직하다.

각자 로컬에 한 부씩 두고 서로 동기화하지 않기

Skill은 Git에 들어가야 의미가 있다. Review 규칙의 변경은 정상 PR로 진행하고, 더 이상 동료에게 .docx 한 부를 개인적으로 보내지 말라.

읽고 나면 최소한 무엇을 가져갈 수 있는가

- Agent Skills = 폴더 + SKILL.md; 제품을 넘나드는 개방형 포맷으로, 현재 AAIF가托管한다.

- 점진적 공개: 먼저 name/description, 필요할 때 본문과 첨부를 로드한다.

- 프런트 Review는 팀의 첫 skill로 만들기에 아주 적합하다: 순서가 고정되고, 명령을 실행할 수 있고, 금지 구역을 나열할 수 있다.

- 본문 내 템플릿 + demo/frontend-review/는 바로 복사할 수 있다; 먼저 scripts/check-skill.sh를 실행하고, 그다음 .agents/skills/에 넣어라.

다음에 「컴포넌트를 고치면 반드시 단위 테스트를 보충한다」「스타일을 고치기 전에 design token을 먼저 검색한다」 같은 규칙을 추가하고 싶다면, 새로 만 자(萬字) Prompt를 열지 말고——같은 SKILL.md에 딱딱한 규칙 하나를 더 추가하거나, 더 좁은 skill을 하나 더 붙여라. 작업 카드가 촘촘해질수록, 채팅창은 오히려 짧아질 수 있다.

참고

- Donating Agent Skills to the Agentic AI Foundation(Anthropic, 2026-10-22)

- Agent Skills Specification

- Agent Skills Quickstart

- agentskills/agentskills(GitHub)

- Equipping agents for the real world with Agent Skills(Anthropic, 배경)

속세의 한 길 잃은 작은 서동

50

글

84k

조회수

151

팔로워