Lab 02: 절차를 스킬로 붙인다

반복할 절차를 어디에 두면, 다음 요청에서도 그대로 재사용되는가?

프롬프트에 절차를 매번 쓰는 대신 스킬로 저장하고, 에이전트에 매핑하고, 호출해서 형식이 그대로 재현되는 것을 확인합니다. Lab 1에서 만든 nxt-store-ops 크루를 그대로 사용합니다.

• Create New Skill 폼으로 스킬을 직접 만듭니다.
• 만든 스킬이 디스크에 어떤 파일로 남는지 확인합니다.
• 스킬을 Agent Template에 매핑하고 적용합니다.
• $ 호출로 스킬이 로드되는 순간을 화면에서 관찰합니다.
• 스킬이 정의한 출력 형식이 실제 답변에 강제되는 것을 확인합니다.
• 스킬의 형식을 직접 수정하고 다음 호출에 반영되는지 확인합니다.

이 실습은 새 세션을 만들지 않습니다. 공통 준비의 세션 연결 절차 대신, Lab 1에서 쓰던 세션을 5단계에서 다시 엽니다.

□ Lab 1을 완료했다 — nxt-store-ops 크루와 그 세션이 남아 있다
□ Gateway가 실행 중이고 대시보드에 접속해 있다
□ 실행 모드가  Normal

이 실습만의 조건입니다.

• Lab 1 정리 단계에서 크루나 세션을 지웠다면 Lab 1의 2~5단계로 다시 만듭니다.
• 준비 파일이 없습니다. 스킬 본문도 실습 중에 직접 입력합니다.

Agent Capabilities → Skills를 엽니다.

화면 설명이 스킬의 정의입니다.

Specialized knowledge files your agent loads on demand for specific tasks

번역: 특정 작업을 위해 에이전트가 필요할 때 불러오는 전문 지식 파일입니다.

항상 로드되는 것이 아니라 필요할 때 로드되는(on demand) 지식 파일입니다. 목록의 스킬마다 on-demand 배지가 붙어 있는 이유입니다.

아무 스킬이나 하나 선택해 상세를 읽습니다.

구성	역할
DESCRIPTION	무엇을 하는 스킬이고 언제 쓰는지
TRIGGERS	이 키워드가 나타나면 로드 후보가 됨
SKILL.md	절차 본문
scripts/ templates/	스킬이 쓰는 보조 파일 (선택)

Lab 1의 크루와 같은 구조가 보입니다. 언제 불려 나올지(TRIGGERS)와 무엇을 하는지(본문)가 분리되어 있습니다.

Create New Skill을 누릅니다.

폼을 채웁니다

필드	입력
Name	nxt-status-report
Category	training
Description	점검·확인 요청의 결과를 고정된 보고 형식으로 작성하는 절차. 사용자가 점검, 확인, 보고를 요청할 때 적용한다.
Triggers	재고 점검, 점검 보고, status report

폼의 안내를 읽어 둡니다.

• Category — Groups the skill in the list. Leave empty for the general category. 목록의 분류 그룹입니다. 3단계에서 이것이 실제로 무엇이 되는지 확인합니다.
• Triggers — Comma-separated keywords that activate this skill. Prefix with ! to exclude. 트리거는 활성화 키워드이고 !로 제외 키워드도 지정할 수 있습니다.
• Tags — Metadata only — not used for matching. 태그는 분류용일 뿐 매칭에 쓰이지 않습니다. 트리거와 태그는 다릅니다.
• Always loaded 체크박스 — 모든 세션에 전체 내용을 주입합니다. 켜지 않습니다. 항상 로드되는 규칙은 스킬이 아니라 Lab 3에서 다룰 Steering의 역할입니다.

Instructions에 절차 본문을 씁니다

# NXT 점검 보고 절차

점검·확인 요청에는 반드시 아래 형식으로 답한다.

## 출력 형식

1. 확인한 사실 — 도구 결과로 검증된 것만. 각 항목에 근거(도구, 파일, 결과)를 붙인다.
2. 미확인 — 요청과 관련되지만 도구로 확인하지 못한 것. 추측으로 채우지 않는다.
3. 다음 검증 — 미확인을 해소할 구체적 방법 한 가지 이상.

## 규칙

- 사실과 해석을 한 문장에 섞지 않는다.
- 근거가 없는 문장은 미확인으로 내린다.
- 형식을 임의로 바꾸지 않는다.

Create를 누르면 목록 개수가 하나 늘어납니다. 이 화면에서는 Skills (20)이 Skills (21)로 바뀝니다. 숫자는 설치된 스킬 수에 따라 다릅니다.

필터에 nxt를 입력하면 방금 만든 스킬이 training/nxt-status-report 경로와 함께 나타나고, 본문이 렌더되어 보입니다.

Lab 1에서 크루가 JSON 한 덩어리였던 것처럼, 스킬이 무엇인지 파일로 확인합니다. 내장 터미널(좌하단 Terminal)에서 실행합니다.

macOS	Windows PowerShell
cat ~/.kiro/crew/skills/training/nxt-status-report/SKILL.md	type $HOME\.kiro\crew\skills\training\nxt-status-report\SKILL.md

---
name: nxt-status-report
description: |
  점검·확인 요청의 결과를 고정된 보고 형식으로 작성하는 절차.
  사용자가 점검, 확인, 보고를 요청할 때 적용한다.
triggers: 재고 점검, 점검 보고, status report
---

# NXT 점검 보고 절차
...

이 실습의 첫 번째 결론입니다. 스킬은 frontmatter가 붙은 마크다운 파일 하나입니다. 폼의 Name·Description·Triggers는 frontmatter가 되고, Instructions는 본문이 됩니다. Category(training)는 폴더 이름이 됐습니다.

Description을 폼에서 여러 줄로 입력하면 위처럼 멀티라인 블록(|)으로 저장됩니다. 이때 스킬 상세 패널의 DESCRIPTION 칸에는 파이프 기호만 보일 수 있습니다 — 표시가 어색할 뿐 파일에는 온전히 저장되어 있습니다. 한 줄로 입력하면 상세 패널에도 그대로 보입니다.

UI 없이 이 파일을 직접 써도 같은 스킬이 됩니다. 폼은 이 파일을 만들어 주는 편집기일 뿐입니다.

스킬은 만들어졌지만 아직 어떤 에이전트도 이 스킬을 쓰지 않습니다.

Agent Capabilities → Agent Templates에서 kirocrew 템플릿을 선택합니다. SKILLS 항목이 이렇게 되어 있습니다.

+ Add skill ∨
No skills mapped — this agent uses the default behavior.

번역: 매핑된 스킬이 없습니다 — 이 에이전트는 기본 동작을 사용합니다.

이 화면에서 2단계의 설명이 눈으로 확인됩니다 — SYSTEM PROMPT와 TOOLS 칩 목록이 템플릿에 붙어 있습니다. 크루가 무엇을 할 수 있는지는 여기서 옵니다.

+ Add skill을 누르고 nxt로 필터링합니다.

방금 만든 스킬이 나타납니다. 선택합니다. 설명 자리에 |만 보인다면 2단계에서 본 멀티라인 Description의 표시 한계입니다.

SKILLS    [⊕ nxt-status-report ×]  [+ Add skill ∨]

왼쪽 목록의 kirocrew 카드에도 스킬 개수 표시가 붙습니다.

Apply & Restart를 누릅니다. Lab 1과 같은 규칙입니다 — 적용하지 않으면 세션에 반영되지 않습니다.

크루가 아니라 템플릿에 매핑하는 이유. Lab 1에서 봤듯 크루는 Agent Template을 물려받습니다. 스킬을 템플릿에 붙이면 그 템플릿을 쓰는 모든 크루(default, nxt-store-ops)가 함께 씁니다. 크루 단위로 스킬을 나누려면 템플릿을 나눠야 합니다.

Sessions에서 Lab 1에서 쓰던 nxt-store-ops 세션을 엽니다. 같은 세션을 쓰는 이유는 마지막에 밝혀집니다.

입력창에 $를 입력하고 nxt를 이어서 칩니다.

방금 만든 스킬이 자동완성에 뜹니다. 선택하고 요청을 완성해 보냅니다.

$nxt-status-report 지금 폴더의 파일 상태를 점검해 줘.

관찰 1 — 로드가 화면에 표시됩니다

🔗 Loaded skill(s) via $ : training/nxt-status-report

번역: $를 통해 스킬이 로드되었습니다: training/nxt-status-report

스킬이 컨텍스트에 들어가는 순간이 명시적으로 보입니다. via $는 로드 경위입니다 — 사용자가 직접 지정해서 로드했다는 뜻입니다.

관찰 2 — 승인 카드가 하나 뜹니다

에이전트는 같은 세션의 맥락으로 “지금 폴더”를 프로젝트 폴더의 store/로 해석하고, cd로 그리로 이동해 ls -la와 git status를 실행하는 shell을 준비합니다. 세션 작업 폴더 밖으로 나가는 shell이므로 승인이 걸립니다 — Lab 1에서 본 경계 그대로입니다. Input 탭에서 명령을 확인하고 Allow once를 누릅니다. (에이전트가 “지금 폴더”를 다르게 해석해 승인 카드가 없을 수도 있습니다 — 그 경우 관찰 3으로 바로 진행합니다.)

관찰 3 — 형식이 강제됩니다

먼저 예측해 보세요 — 답변이 어떤 모양일까요?

아래 인용은 Lab 1의 산출물 daily-check.md가 지워진 상태에서 나온 예시입니다 — 여러분의 화면에는 그 파일이 있으므로 점검 결과의 내용이 다르게 나옵니다. 볼 것은 내용이 아니라 형식입니다.

지금 폴더(.../nxt-kirocrew-hands-on/labs/01-agent-creation/store)의 파일 상태를 점검했습니다.

1. 확인한 사실
- 해당 폴더에 파일 2개가 존재한다 — ls -la 결과: inventory-status.md (217 bytes),
  orders-today.md (435 bytes), 둘 다 8월 10일 08:58.
- 앞서 이 세션에서 저장한 daily-check.md 가 현재 폴더에 없다 — ls -la 출력에
  나타나지 않음 (직전 대화 기록상 생성했으나 현재 목록에 부재).
- 프로젝트 루트 git 상태에서 미추적 항목은 .kiro/ 하나뿐이다 — git status --short 결과.

2. 미확인
- daily-check.md 가 왜 사라졌는지 — 삭제·이동·별도 정리 중 무엇인지 도구로 확인하지 못함.
- store 폴더 두 파일이 git status에 안 뜨는 이유가 "이미 커밋됨"인지 "gitignore 처리"인지 — 확정 못 함.

3. 다음 검증
- 삭제 여부: git log --oneline -- labs/01-agent-creation/store/daily-check.md 로 추적 이력 확인.
- 추적 상태: git ls-files labs/01-agent-creation/store/ 로 어떤 파일이 git에 등록됐는지 확인.

모든 사실에 근거가 붙었고, 근거가 없는 것은 미확인으로 내려갔습니다. 스킬 규칙 그대로입니다.

관찰 4 — 같은 세션의 이전 답변과 비교합니다

위로 스크롤해 Lab 1의 pwd 답변을 봅니다. 같은 세션, 같은 크루, 같은 모델인데 그 답변에는 형식이 없습니다.

	Lab 1의 답변	방금 답변
스킬 로드 표시	없음	Loaded skill(s) via $
형식	자유 서술	3부 고정
근거 표기	일부	전 항목
추측 처리	본문에 섞임	미확인으로 분리

이 실습의 두 번째 결론입니다. 달라진 것은 모델이 아니라 컨텍스트에 들어간 절차 파일 하나입니다. 그리고 그 파일이 들어가는 순간이 화면에 기록됩니다. 절차가 적용됐는지 추측할 필요가 없습니다.

미확인 항목을 다시 읽습니다

인용 예시의 미확인 첫 항목이 이 실습의 숨은 검증입니다.

daily-check.md 가 왜 사라졌는지 — 삭제·이동·별도 정리 중 무엇인지 도구로 확인하지 못함.

인용 예시는 Lab 1의 산출물 daily-check.md가 지워진 상태에서 나온 답변입니다. 같은 세션의 대화 기록에는 파일을 만든 흔적이 있는데 디스크에는 없으니, 추측하자면 “삭제된 것 같습니다”라고 쓸 수 있는 상황입니다. 그러나 스킬 규칙(“근거가 없는 문장은 미확인으로 내린다”)대로 단정하지 않고 미확인으로 분류했고, 확인 방법(git log)까지 다음 검증에 제안했습니다.

여러분의 화면에서는 daily-check.md가 그대로 있을 것이므로 점검 결과와 미확인 항목의 구체 내용이 다르게 나옵니다. 중요한 것은 특정 문장이 아니라 근거 없는 것을 단정하지 않고 미확인으로 내리는 동작입니다.

Windows. 이 단계에서 에이전트가 점검에 shell(pwd, ls, cat)을 쓸 수 있습니다. Windows에서 shell 실행이 차단되면 “파일 도구로만 점검하라”고 요청을 바꿔 봅니다. 형식 관찰이 목적이므로 조회 수단은 중요하지 않습니다.

형식을 자기 것으로 바꿔 봅니다

지금 형식은 우리가 준 것입니다. 실제 업무에서 쓸 사람은 여러분이니, 필요한 형식으로 직접 고쳐 봅니다.

Skills에서 nxt-status-report를 선택하고 Edit를 누릅니다. Instructions에 자기 상황에 맞는 변경을 하나 이상 가합니다. 예를 들면 —

• 맨 위에 요약(문제 유무와 개수)을 추가한다
• 확인한 사실을 문장 대신 표로 요구한다
• 각 문제에 심각도(높음/중간/낮음)를 붙이게 한다
• 보고 끝에 결재란(확인자·확인 일시)을 넣게 한다

출력 형식 맨 위에 요약 항목을 추가해 봅니다.

0. TI;DL 3줄 요약을 불릿포인트 3개로 작성한다.   ← 오타(TI;DL)는 일부러 넣는 것입니다. 고치지 말고 그대로 둡니다

Save 후 Apply & Restart를 누르고, 같은 세션에서 같은 호출을 다시 보냅니다.

$nxt-status-report 지금 폴더의 파일 상태를 다시 점검해 줘.

이번에도 프로젝트 폴더 밖의 store/를 조회하므로 승인 카드가 나타납니다. Input 탭에서 재검증 명령을 확인하고 Allow once를 누릅니다.

답변이 고친 형식으로 나옵니다 — 맨 위에 요약이 붙었습니다.

0. TL;DR
- 폴더에는 orders-today.md, inventory-status.md 2개 파일만 있고 둘 다 git에 추적·정상 상태다.
- 앞서 만든 daily-check.md 는 현재 폴더에 없다.
- daily-check.md 가 어떻게/왜 사라졌는지는 도구로 확인하지 못했다.

여기서 두 가지를 더 관찰할 수 있습니다.

1. 오타를 스스로 교정했습니다. 스킬에는 TI;DL이라고 일부러 잘못 써 뒀는데 보고는 TL;DR로 나왔습니다. 스킬은 기계적 강제 장치가 아니라 모델이 해석하는 문서입니다 — 의도는 통하고, 정확한 문구는 보장되지 않습니다.
2. 미확인이 사실로 승격됐습니다. 첫 보고가 “다음 검증”으로 제안한 git ls-files·git log를 재점검에서 스스로 실행했고, 미확인이던 “store 파일의 git 추적 여부”가 확인한 사실(“두 파일 모두 git에 추적됨”)로 올라갔습니다. 3부 형식은 점검을 반복 가능한 검증 루프로 만듭니다 — 이번 보고의 미확인이 다음 보고의 검증 대상이 됩니다.

절차의 개정이 파일 수정 한 번입니다. 프롬프트에 절차를 쓰던 시절에는 “다음부터는 요약도 붙여 줘”를 매번 다시 말해야 했습니다. 이제는 스킬을 한 번 고치면 다음 호출부터 모두 적용됩니다 — 그리고 무엇이 언제 바뀌었는지 파일 이력으로 남습니다.

이번에는 $로 직접 지정해 로드했습니다. Triggers에 적은 재고 점검, 점검 보고, status report는 직접 지정 없이도 요청에 그 키워드가 나타나면 스킬을 로드 후보로 만듭니다.

먼저 스스로 답해 본 뒤 접힌 답과 비교해 보세요.

트리거를 너무 넓게 잡으면(예: 점검) 어떤 일이 생기는가?

생각해 볼 답

무관한 요청에도 스킬이 로드 후보가 됩니다 — 가벼운 질문에까지 3부 보고 형식이 강제되고, 로드될 때마다 컨텍스트 비용이 붙으며, 트리거가 겹치는 다른 스킬과 충돌할 확률도 올라갑니다. 트리거는 “이 절차가 진짜 필요한 요청”만 잡도록 좁혀야 합니다.

트리거를 너무 좁게 잡으면 스킬은 언제 죽은 파일이 되는가?

생각해 볼 답

아무도 그 정확한 문구로 요청하지 않을 때입니다. 사람들이 실제로 쓰는 말과 트리거가 어긋나면 스킬은 $로 직접 지정할 때만 살아나는 파일이 됩니다. 요령은 실제 요청 문구를 관찰해서 트리거를 맞추는 것 — 트리거도 운영하면서 다듬는 대상입니다.

Always loaded로 만들면 무엇을 얻고 무엇을 잃는가?

생각해 볼 답

얻는 것은 “로드를 잊을 일이 없다”는 일관성입니다. 잃는 것은 모든 세션의 컨텍스트 비용과, 형식이 필요 없는 대화까지 보고 형식이 붙는 과잉 적용입니다. 항상 지켜야 할 것이 짧은 규칙이라면 그 자리는 스킬이 아니라 Steering(Lab 3)입니다 — 절차는 필요할 때, 규칙은 항상.

이 스킬을 팀 동료가 쓰게 하려면 무엇을 전달해야 하는가?

생각해 볼 답

3단계에서 본 대로 SKILL.md 파일 하나입니다. 다만 파일 전달이 곧 활성화는 아닙니다 — 받은 사람이 자기 스킬 폴더에 넣고, 템플릿에 매핑하고, Apply & Restart까지 해야 동작합니다. 4단계에서 밟은 그 절차가 곧 배포 절차입니다.

다음 랩(Lab 3~7)을 이어서 진행한다면 아무것도 지우지 않습니다. 크루와 스킬을 계속 씁니다.

과정을 여기서 끝내는 경우에만 정리합니다.

1. Agent Templates → kirocrew의 SKILLS에서 nxt-status-report 옆 ×로 매핑을 해제합니다.
2. Skills에서 nxt-status-report를 선택하고 Delete를 누릅니다.
3. Apply & Restart로 적용합니다.
4. 파일이 사라졌는지 확인합니다.

macOS	Windows PowerShell
ls ~/.kiro/crew/skills/training/	dir $HOME\.kiro\crew\skills\training\

주의. 삭제 확인 대화상자는 브라우저 기본 창일 수 있습니다. 화면에서 직접 누릅니다.

• Create New Skill로 스킬을 만들었고 목록에 추가된 것을 확인했습니다.
• SKILL.md 파일을 열어 frontmatter와 본문을 확인했습니다.
• Category가 폴더 이름이 된 것을 확인했습니다.
• Agent Template에 스킬을 매핑하고 Apply & Restart 했습니다.
• $ 자동완성에 스킬이 나타났습니다.
• 답변에서 Loaded skill(s) via $ 표시를 확인했습니다.
• 답변이 3부 형식을 지켰고 전 항목에 근거가 붙었습니다.
• 스킬을 직접 고쳐 재호출했고, 바뀐 형식이 답변에 적용됐습니다.
• 같은 세션의 Lab 1 답변과 형식 차이를 비교했습니다.

증상	먼저 확인할 항목
$ 자동완성에 스킬이 없음	Apply & Restart를 눌렀는지
스킬이 로드됐는데 형식이 다름	답변 상단의 로드 표시 유무. 로드됐다면 Instructions 내용을 다시 읽고 규칙을 명확히
Instructions에 한글이 깨짐	브라우저 입력기 문제. Edit raw markdown으로 직접 붙여넣기
파일 경로가 없음	Category를 다르게 입력했는지 — Category가 폴더 이름이 됩니다
매핑을 해제해도 계속 로드됨	Apply & Restart 후 새 세션에서 시험했는지

스킬은 frontmatter가 붙은 마크다운 파일 하나입니다. 폼은 그 파일을 만들어 주는 편집기입니다.

스킬은 만들어진 것만으로는 아무 일도 하지 않습니다. 템플릿에 매핑되고, 적용되고, 로드되어야 합니다. 각 단계가 화면에서 확인 가능합니다.

절차를 파일로 고정하면 출력 형식이 재현됩니다. 달라진 것은 모델이 아니라 컨텍스트에 들어간 파일 하나입니다.

먼저 스스로 답해 본 뒤 접힌 답과 비교해 보세요.

스킬 본문에 규칙을 더 추가하면 답변은 어디까지 통제되는가? 통제가 깨지는 지점은 어디인가?

생각해 볼 답

형식·구조·분류 기준처럼 판별 가능한 규칙은 잘 통제됩니다. 이번 실습에서도 3부 구조와 근거 표기가 재현됐습니다. 통제가 약해지는 지점은 규칙끼리 충돌할 때, 무엇이 충분한 근거인지 해석해야 하는 회색지대, 대화가 길어져 규칙이 컨텍스트에서 밀릴 때입니다. 스킬은 강제 장치가 아니라 컨텍스트에 들어간 문서이므로 문장 표현이 실행마다 조금씩 달라질 수 있습니다.

트리거 키워드가 서로 겹치는 스킬이 두 개 있으면 무엇이 로드되는가?

생각해 볼 답

두 스킬 모두 로드 후보가 됩니다. 함께 로드되면 컨텍스트 비용이 늘고, 두 스킬의 지시가 충돌할 때 어느 쪽을 따를지 보장하기 어렵습니다. 트리거는 서로 다른 업무를 가리키도록 좁고 명확하게 정하고, 실제로 무엇이 로드됐는지는 답변의 Loaded skill(s) 표시로 확인합니다.

SKILL.md 파일을 직접 편집하면 UI에 언제 반영되는가?

생각해 볼 답

3단계에서 확인했듯 파일이 원본이고 UI는 그 파일을 보여 주는 창입니다. 직접 편집한 내용은 파일에 즉시 반영되고, 화면 목록과 상세는 새로고침 뒤, 세션에는 다음 로드 때 반영됩니다. 확실하게 확인하려면 편집 후 Apply & Restart를 누르고 같은 스킬을 다시 호출합니다.

이 스킬을 저장소에 커밋해서 팀과 공유한다면 어떤 경로 문제를 만나는가?

생각해 볼 답

스킬은 저장소가 아니라 각자의 홈 디렉터리(~/.kiro/crew/skills/)에 있습니다. 공유하려면 복사본을 저장소에 두고 각자의 스킬 폴더로 설치하는 절차가 필요합니다. 스킬 본문이 상대 경로로 다른 파일을 참조하면, 스킬이 저장소가 아닌 홈 디렉터리에서 로드되므로 그 경로가 깨질 수 있습니다. 공유할 스킬은 경로 의존을 없애거나 경로 규칙을 함께 정해야 합니다.

클론한 저장소의 themes/program-office/는 방금 밟은 흐름을 대학 사업단 상황으로 다시 도는 테마 팩입니다. themes/program-office/README.md의 Lab 매핑 표에서 Lab 2 항목은 사업 진행 보고 형식 표준화입니다. 실제 민감 데이터나 회사 자료는 넣지 말고, 가상의 이름과 숫자로 연습하세요.

1. themes/program-office/README.md를 열어 Lab 2의 파일과 시나리오를 확인합니다.
2. nxt-status-report와 같은 방식으로 사업 진행 보고용 스킬을 새로 만듭니다. 사업단 담당자가 점검·확인·보고를 요청했을 때 적용되도록 Triggers를 정합니다.
3. Instructions에 다음과 같은 출력 형식을 넣습니다.

1. 확인한 진행 사실 — 보고 기간, 완료 항목, 근거 파일을 구분한다.
2. 미확인 — 자료로 확인하지 못한 일정·수치·담당자를 추측하지 않는다.
3. 다음 확인 — 미확인 항목마다 담당자에게 물어볼 질문이나 확인할 파일을 제시한다.

4. 사업 진행 보고 형식 스킬을 kirocrew 템플릿에 매핑하고 Apply & Restart 합니다.
5. 테마 팩의 가상 사업 자료를 읽고, $로 스킬을 직접 호출해 보고 형식이 적용되는지 확인합니다. 첫 보고에서 미확인으로 남은 항목을 다음 호출에서 다시 검증해 사실로 올려 보세요.

같은 구조를 자기 업무의 소재로 바꿔 한 번 더 만들어 봐도 좋습니다. 실제 민감 데이터 대신 구조만 재현한 가상의 예시 파일을 사용하세요.