菜单
새 SKILL.md 파일 생성, 기존 스킬 편집, 배포 전 스킬 검증, 또는 프로세스 문서를 실행 가능한 스킬로 정의할 때 사용. Use when creating a new SKILL.md file, editing an existing skill, validating a skill before deployment, or when any process documentation needs to be defined as an executable skill.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | writing-skills |
| description | 새 SKILL.md 파일 생성, 기존 스킬 편집, 배포 전 스킬 검증, 또는 프로세스 문서를 실행 가능한 스킬로 정의할 때 사용. Use when creating a new SKILL.md file, editing an existing skill, validating a skill before deployment, or when any process documentation needs to be defined as an executable skill. |
| metadata | {"version":"0.1.0","author":"Jay","category":"skill-craft","invoke_mode":"user-invocable","return_behavior":"stop-no-gate","skill_nature":"amplification","lifecycle":"active"} |
NO SKILL WITHOUT DEFINING TRIGGER CONDITIONS FIRST
트리거 조건 없는 스킬은 절대 호출되지 않거나 잘못 호출된다. 스킬을 작성하기 전에 "이 스킬이 언제 발동되어야 하는가"를 먼저 정의한다.
다음 상황에서 이 스킬을 실행한다:
스킬 작성 = 프로세스 문서화의 TDD.
스킬 없이 에이전트가 실패하는 시나리오를 먼저 정의하고, 그 시나리오를 통과시키는 SKILL.md를 작성한다.
| TDD 개념 | 스킬 작성에서의 대응 |
|---|---|
| 테스트케이스 | 압박 시나리오 — 에이전트가 스킬 없이 실패하는 상황 |
| 프로덕션 코드 | SKILL.md |
| RED | 스킬 없이 에이전트가 잘못 행동하는 상태 |
| GREEN | 스킬 있을 때 에이전트가 올바르게 준수하는 상태 |
| REFACTOR | 스킬을 더 명확하게, 더 짧게, 더 잘 호출되도록 개선 |
Claude는 스킬 목록에서 description을 먼저 읽어 어떤 스킬을 호출할지 결정한다.
description이 잘못 작성되면 스킬이 존재해도 호출되지 않는다.
절대 금지 — 워크플로우 요약 포함:
# ❌ 잘못된 예 — 에이전트가 description만 읽고 본문을 건너뜀
description: Manages the full debugging lifecycle by investigating root causes,
analyzing patterns, forming hypotheses, and implementing verified fixes using TDD.
올바른 형식 — "Use when..." 트리거 조건만:
# ✓ 올바른 예 — 에이전트가 정확한 상황에서만 호출
description: Use when a bug is reported, a test is failing, behavior is unexpected,
or any symptom requires diagnosis before a code change is made.
description 작성 체크리스트:
skills/
└── [skill-name]/
└── SKILL.md
---
name: [skill-name] # skills/ 디렉토리명과 일치
description: Use when ... # CSO 원칙 준수 — 트리거 조건만
metadata:
version: 0.1.0
author: [작성자]
category: [카테고리]
---
# [skill-name]
<!-- 한 줄 주석: 이 스킬이 무엇을 하는가 -->
## 철의 법칙 (선택)
> NO [ACTION] WITHOUT [PREREQUISITE]
## Trigger
[언제 이 스킬이 발동되는가 — 목록 형식]
## Purpose
[이 스킬의 목표 — 2-3문장]
## [메인 프로세스 섹션]
[단계별 지침]
## Examples
[실제 사용 예시 최소 2개]
## Troubleshooting
[흔한 문제 최소 2개]
## 철의 법칙: 절대 위반하면 안 되는 원칙 (강력한 프로세스 스킬에 권장)## Red Flags: 잘못된 행동 패턴 목록## 합리화 방지 테이블: 스킬을 건너뛰려는 시도 차단스킬을 작성하기 전에 에이전트가 스킬 없이 실패하는 상황을 나열한다:
압박 시나리오 목록:
1. 에이전트가 버그를 수정 요청받고 원인 조사 없이 바로 코드를 수정한다
2. 에이전트가 "아마도 될 것 같다"며 테스트 없이 완료를 선언한다
3. ...
이 목록이 스킬의 Trigger 섹션이 된다.
압박 시나리오 설계 상세:
_shared/patterns/skill-writing-guide.md참조
Step A — 구조 패턴 추천: 1단계에서 파악한 스킬 목적을 기반으로, _shared/patterns/skill-design-patterns.md의 결정 트리를 내부적으로 적용하여 구조 패턴(Tool Wrapper / Generator / Reviewer / Inversion / Pipeline)을 자동 판별한다. 사용자에게는 효과 중심으로 설명한다:
📐 구조 패턴: **[패턴명]**
- 이유: [왜 이 패턴이 적합한지 1문장]
- 구조: [디렉토리 구성 요약]
- 변경하려면 말씀해 주세요. 아니면 이대로 진행합니다.
5가지 패턴을 나열하여 사용자에게 선택을 강요하지 않는다. 사용자가 교정하거나 전문가가 패턴명으로 직접 지정하는 것은 허용.
기존 스킬 수정 시: Step B 전에 반드시 _shared/patterns/skill-writing-guide.md의 "수정 시 영향도 분석" 절차를 수행한다. description 키워드 변경, output_path 변경, 메타 태그 변경 시 다른 스킬에서의 참조·호출 영향을 확인.
Step B — 최소 동작 스킬 작성: 선택한 구조 패턴의 디렉토리 구조를 따라 압박 시나리오를 통과시키는 최소한의 스킬을 작성한다:
스킬 구조 설계 원칙:
_shared/patterns/skill-writing-guide.md참조 규율 강제 스킬의 언어 설계:_shared/patterns/persuasion-principles.md참조 행동 패턴 선택:_shared/patterns/skill-pattern-catalog.md참조 구조 패턴 상세:_shared/patterns/skill-design-patterns.md참조
아래 체크리스트를 모두 통과해야 배포한다.
Standard/Comprehensive depth: skill-reviewer 서브에이전트를 dispatch하여 자동 검증.
_shared/reviewers/skill-reviewer-prompt.mdMinimal depth: 아래 체크리스트를 수동으로 확인.
name이 디렉토리명과 일치하는가?description이 "Use when..."으로 시작하는가?description에 워크플로우 요약이 없는가?metadata.version, metadata.author, metadata.category가 있는가?## Trigger 섹션이 있는가?## Examples 섹션에 예시가 2개 이상 있는가?## Troubleshooting 섹션에 항목이 2개 이상 있는가?배포 전 검증 체크리스트가 모두 통과하면 (Standard/Comprehensive: skill-reviewer Approved):
A) 스킬 완성 — description 수동 검증으로 충분
B) 정량적 최적화 — skill-creator로 eval + description 최적화 실행
사용자 선택 없이 진행하지 않는다.
B 선택 시: Skill tool로 skill-creator 호출. skill-creator가 eval 생성 → 벤치마크 → description 최적화를 자체 워크플로우로 수행. 완료 후 이 스킬로 돌아와 결과 확인.
skill-creator 미설치 시: B 선택지를 표시하지 않고 A만 제시. 안내 문구:
A) 스킬 완성
ℹ️ skill-creator 플러그인이 설치되면 정량적 최적화(eval + description 최적화)도 가능합니다.
1단계 압박 시나리오:
- 에이전트가 "TypeError: 'NoneType'..." 에러를 받고 즉시 None 체크 코드를 추가한다
→ 실제 원인은 상위 함수에서 None을 잘못 반환하는 것
- 에이전트가 "이전에 비슷한 버그를 봤다"며 다른 케이스의 수정을 그대로 복사한다
→ 증상만 같고 원인은 전혀 다름
2단계 최소 동작 스킬 핵심:
## 철의 법칙
> NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
## 4단계 프로세스
1단계: 재현 및 스택 트레이스 전체 읽기
2단계: 작동하는 케이스와 차이점 비교
3단계: 단일 가설 → 최소 변경으로 검증
4단계: 실패 테스트 작성 → 수정 → 통과 확인
3단계 배포 전 체크리스트:
상황: aidlc-code-generation 스킬이 오케스트레이터 없이 단독 호출될 때 승인 게이트 처리가 모호함
수정 전 문제:
# 기존 description
description: Generates a code plan and implements it after approval.
Do NOT invoke directly — use using-devflow instead.
문제 분석:
수정 후:
description: Use when code implementation is needed for a defined unit or feature.
Produces a checkbox plan first, then generates code after explicit approval.
Can be used standalone or called by using-devflow orchestrator.
배포 전 체크리스트 재실행 → 통과 확인 후 배포
상황: "배포 전 보안 검사" 스킬을 새로 만들어야 함
1단계 — 압박 시나리오(RED): 에이전트가 "급하니까 보안 검사 스킵하자"며 배포 진행
2단계 Step A — 구조 패턴 자동 추천: Claude가 결정 트리를 적용:
📐 구조 패턴: **Reviewer**
- 이유: 보안 체크리스트 기준으로 코드를 평가하는 구조
- 구조: SKILL.md + references/security-checklist.md
- 변경하려면 말씀해 주세요. 아니면 이대로 진행합니다.
2단계 Step A — 행동 패턴 선택:
skill-pattern-catalog.md에서:
2단계 Step B — 최소 동작 스킬 작성: Iron Law 행동 패턴 + Reviewer 구조 패턴 조합:
## 철의 법칙
> NO DEPLOYMENT WITHOUT SECURITY CHECK FIRST
위반 시: 배포 취소, 보안 검사부터 재시작
## 리뷰 프로세스
1. `references/security-checklist.md` 로드
2. 대상 코드를 항목별 대조
3. 심각도별 결과 보고
3단계 — persuasion-principles 적용:
배포 전 체크리스트 + skill-reviewer dispatch → 통과 확인 후 배포
증상: 스킬이 있는데 에이전트가 스킬을 호출하지 않고 직접 처리함
원인과 해결:
증상: 관련 없는 상황에서 스킬이 호출됨
원인과 해결: