개요
writing-skills 스킬이 하는 일
writing-skills 스킬은 Claude 같은 에이전트용 스킬을 만들고, 다듬고, 테스트하는 사람을 위한 메타 스킬입니다. 고전적인 Test-Driven Development(TDD) 개념을 프로세스 문서 작성에 적용해, 여러분의 스킬이 다음과 같도록 돕습니다.
- 실제 압박 상황을 기반으로 설계되고
- 실제 에이전트 실패 사례에 비추어 검증되며
- 허점을 줄이고 합리화를 막도록 정교하게 다듬어집니다.
writing-skills를 사용하면, 시간 압박·매몰 비용 편향·상충하는 인센티브가 있어도 에이전트가 스킬을 발견하고, 따르고, 계속 따르게 만드는 스킬을 설계할 수 있습니다.
writing-skills가 적합한 사용자
다음에 해당한다면 writing-skills 스킬을 사용하는 것이 좋습니다.
- Claude 또는 유사 에이전트용 스킬을 만드는 개발자
~/.claude/skills또는~/.agents/skills/아래 워크플로를 표준화하려는 팀 리드- "읽기"를 넘어서 반드시 지켜져야 하는 스킬을 관리하는 문서 책임자
- 배포 전에 스킬이 실제로 에이전트 행동을 바꾸는지 검증하는 테스터
이 스킬은 일반적인 문체나 글쓰기 스타일을 다루지 않습니다. 효과적이고 테스트 가능한 에이전트 스킬을 작성하는 것에 특화되어 있습니다.
이 스킬이 해결을 돕는 문제들
writing-skills는 다음과 같은 상황을 위해 설계되었습니다.
- 에이전트가 압박 상황에서 스킬을 무시하거나 일부만 따를 때
- 새 스킬이 실제로 행동을 바꾸는지 확신이 서지 않을 때
- 배포 전에 subagent로 스킬을 반복적으로 테스트해야 할 때
- 추측 없이 Anthropic 스킬 작성 베스트 프랙티스를 따르고 싶을 때
- Graphviz로 복잡한 스킬 워크플로를 시각화·공유해야 할 때
현재 스킬이 일회성 스토리나 메모에 가깝다면, writing-skills는 그것을 재사용 가능한 테스트 가능한 레퍼런스 가이드 형태로 재구성하는 데 도움을 줍니다.
writing-skills가 잘 맞는 경우 / 맞지 않는 경우
적합한 경우:
- 규율을 강제하는 스킬(TDD, 검증, 리뷰 체크리스트 등)
- 실제 컴플라이언스 비용(시간, 재작업, 출시 지연 등)이 있는 스킬
- 에이전트가 "이번 한 번만" 하고 우회하려 할 수 있는 스킬
- 준수율을 계량적으로 개선하고 싶은 스킬
부적합한 경우:
- 순수 참고용 스킬(예: API 문법, 기초 언어 치트시트)
- 애초에 위반 가능한 규칙이 없도록 설계된 스킬
- TDD 스타일 테스트나 압박 시나리오까지는 필요 없는 가벼운 메모
한 번의 대화를 위해 빠르게 쓰는 가벼운 메모라면 writing-skills까지는 필요하지 않을 수 있습니다. 반대로, 운영 환경의 압박 속에서도 살아남는 스킬이 필요하다면 writing-skills가 적합합니다.
사용 방법
설치와 기본 설정
skills-aware 환경에 writing-skills 스킬을 설치하려면 다음을 실행합니다.
npx skills add https://github.com/obra/superpowers --skill writing-skills
이 명령은 obra/superpowers 저장소에서 writing-skills 스킬을 가져와 다른 스킬과 함께 등록합니다.
개인용 스킬은 보통 에이전트별 디렉터리에 위치합니다. 예를 들면:
- Claude Code용
~/.claude/skills/ - Codex 등 유사 에이전트용
~/.agents/skills/
해당 스킬 루트 아래에 writing-skills 디렉터리가 존재하는지, 또는 그 위치에 배치했는지 확인하여, 필요할 때 에이전트가 SKILL.md와 관련 파일을 로드할 수 있도록 합니다.
writing-skills의 핵심 파일 및 폴더
설치 후에는 먼저 다음 파일들을 열어 워크플로를 이해하고 적용해 보세요.
SKILL.md– writing-skills의 핵심 스킬 정의와 개요, 스킬용 TDD 매핑 포함anthropic-best-practices.md– Claude를 위한 간결하고 발견 가능하며 효과적인 스킬 작성에 대한 가이드testing-skills-with-subagents.md– 압박 시나리오 및 테스트 캠페인을 설계·실행하는 실무 가이드persuasion-principles.md– 에이전트의 스킬 준수율을 높이는 근거 기반 설득 패턴 정리graphviz-conventions.dot– 스킬 워크플로·프로세스를 Graphviz 다이어그램으로 표현하기 위한 컨벤션render-graphs.js– ```dot 블록을SKILL.md에서 추출해 SVG 다이어그램으로 렌더링하는 헬퍼 스크립트examples/CLAUDE_MD_TESTING.md–CLAUDE.md문서 버전에 대한 테스트 캠페인을 처음부터 끝까지 보여주는 완성 예시
이 파일들을 함께 사용하면 스킬에 대한 작성 + 테스트 + 시각화 전체 워크플로를 구축할 수 있습니다.
핵심 워크플로: 스킬에 대한 TDD
writing-skills는 TDD 개념을 스킬 작성에 직접 적용합니다. 상위 레벨 루프는 다음과 같습니다.
-
테스트 케이스(압박 시나리오) 작성
- 에이전트가 의도한 프로세스를 생략하거나 왜곡하도록 합리화할 수 있는 현실적인 상황을 설계합니다.
- subagent를 활용해 이 시나리오를 실행하고, 그 행동을 캡처합니다.
-
기준선 테스트 실행 및 실패 관찰
- 새 스킬 또는 수정 전 스킬을 로드하지 않은 상태로 시나리오를 실행합니다.
- 에이전트가 어디에서 실패하는지, 무엇을 생략·합리화·오해하는지 기록합니다.
-
스킬 작성 또는 개선
- 발견한 구체적 실패를 해결하도록
SKILL.md와 관련 파일을 새로 작성하거나 수정합니다. - 컨텍스트 윈도우 제약을 고려해 간결하고 명령형인 문장으로 작성합니다.
- 발견한 구체적 실패를 해결하도록
-
스킬을 로드한 상태에서 다시 테스트 실행
- 동일한 시나리오를 이번에는 스킬을 활성화한 상태로 재실행합니다.
- 에이전트가 이제 스킬을 발견하고, 선언하고, 실제로 따르는지 확인합니다.
-
허점 제거를 위한 리팩터링
- 여전히 남은 합리화나 부분 준수를 찾아냅니다.
- 설득 원칙(권위, 커밋먼트 등)을 적용해 준수 강도를 높입니다.
- 불필요한 토큰을 줄여 스킬을 최대한 간결하게 유지합니다.
이 루프는 고전적인 TDD의 RED → GREEN → REFACTOR를 그대로 따르되, 코드가 아닌 문서와 프로세스 준수에 적용한 형태입니다.
더 나은 스킬을 위한 anthropic-best-practices.md 활용
anthropic-best-practices.md는 Claude 생태계에 특화된 가이드를 제공합니다. 예를 들면:
- 왜 간결한 스킬이 컨텍스트 사용과 모델 성능을 개선하는지
- Claude가 언제, 어떤 방식으로
SKILL.md와 기타 파일을 컨텍스트 윈도우에 로드하는지 - 각 섹션이 토큰 비용을 정당화하도록 스킬을 어떻게 구성해야 하는지
이 파일을 스킬 리뷰용 체크리스트로 활용할 수 있습니다.
- Claude가 이미 알고 있는 설명은 제거합니다.
- 실행 가능한 패턴, 규칙, 워크플로에 집중합니다.
- 가장 중요한 지침이 앞부분에 명확히 드러나도록 구조를 설계합니다.
writing-skills의 TDD 루프와 이 베스트 프랙티스를 결합하면, 스킬을 발견하기 쉽고 효율적인 형태로 유지하는 데 도움이 됩니다.
subagent로 스킬 테스트하기
testing-skills-with-subagents.md는 TDD 접근법을 실제 테스트 방법으로 확장합니다.
- 시간 압박, 매몰 비용, 속도 대 품질 등 실제 운영 환경과 유사한 시나리오를 설계합니다.
- 메인 에이전트의 행동을 대리하는 subagent로 시나리오를 실행합니다.
- 실패와 합리화 패턴을 구조화된 형식으로 수집합니다.
이 방식은 특히 다음과 같은 스킬에 유용합니다.
- 테스트 선 작성과 같은 시간 소모적인 베스트 프랙티스를 강제하는 스킬
- 빠른 출시 vs 철저한 검증처럼 단기 목표와 충돌하는 스킬
- 사람이 명시적으로 "지름길"을 요구하는 상황에서도 유지되어야 하는 스킬
이 파일에서 제시하는 테스트 패턴을 따르면, 사용자에게 도달하기 전 압박 상황에서 스킬을 검증할 수 있습니다.
설득 원칙을 스킬 설계에 적용하기
persuasion-principles.md는 LLM 행동에도 영향을 미치는 심리학적 원칙을 정리합니다. 예를 들면:
- Authority(권위) – 안전 필수 규칙에 대해 분명하고 양보 없는 문구 사용
- Commitment(커밋먼트) – 에이전트가 스킬 사용을 선언하고, 선택한 경로를 계속 따르도록 요구
- Scarcity(희소성) 등 – 중요한 관행의 우선순위를 적절히 높이는 데 활용
실무적으로는 다음과 같이 활용할 수 있습니다.
- 선택 사항이 아닌 단계에는 더 명령형 어조를 사용합니다.
- 스킬을 적용할 때 에이전트에게 "I am using [Skill Name] now"라고 명시적으로 선언하게 합니다.
- 읽고 지나가는 문서가 아닌, 반드시 체크해야 하는 체크리스트 형태로 설계합니다.
목표는 조작이 아니라, 중요한 관행이 일관되게 준수되도록 만드는 것입니다.
Graphviz로 스킬 플로우 시각화하기
복잡한 스킬은 시각화했을 때 이해가 훨씬 쉬워집니다. writing-skills에는 다음이 포함되어 있습니다.
graphviz-conventions.dot– 다이어그램 구조와 스타일에 대한 권장 컨벤션render-graphs.js–SKILL.md에서 ```dot 블록을 추출해 SVG 파일로 변환하는 Node.js 스크립트
렌더러 기본 사용법은 다음과 같습니다.
./render-graphs.js path/to/your/skill
# 또는
./render-graphs.js path/to/your/skill --combine
이를 통해 다음을 할 수 있습니다.
- 스킬의 흐름을 팀 동료에게 시각적으로 설명
- 프로세스 설계 상의 누락이나 루프를 발견
SKILL.md안에 ```dot 코드 블록으로 다이어그램을 포함해 문서와 시각 자료를 동기화
writing-skills를 환경에 맞게 커스터마이즈하기
이 저장소는 그대로 복사하기보다는 각 환경에 맞게 변형해 쓰는 패턴을 제안합니다. writing-skills를 워크플로에 통합할 때는:
- TDD 루프는 유지하되, 시나리오 포맷은 사용하는 도구에 맞게 조정합니다.
- 디렉터리 구조는 팀 기준에 맞게 조정하되, 스킬 경계를 명확히 유지합니다.
- 테스트 캠페인을 기존 CI, 리뷰, 릴리스 프로세스에 통합합니다.
목표는 팀과 인프라에 잘 맞는, 반복 가능한 테스트 주도형 스킬 작성 워크플로를 갖추는 것입니다.
FAQ
writing-skills 스킬은 언제 로드해야 하나요?
다음과 같은 상황에서는 writing-skills를 로드해서 사용하는 것이 좋습니다.
~/.claude/skills또는 유사 디렉터리 아래에 새 스킬을 만들 때- 기존 스킬이 점점 무시되거나 본래 의도에서 벗어나기 시작했을 때
- 팀원·프로덕션 환경에 배포할 스킬을 준비할 때
- subagent를 활용한 스킬 테스트 캠페인을 설계·실행할 때
일회성 세션에서 가볍게 실험하는 정도라면, 전체 writing-skills 워크플로까지는 필요하지 않을 수 있습니다.
writing-skills를 쓰려면 TDD를 미리 알아야 하나요?
네. 이 스킬은 superpowers:test-driven-development에 대한 기본 이해를 전제로 합니다. writing-skills는 RED → GREEN → REFACTOR 사이클을 이미 알고 있다는 가정하에, 이를 문서에 적용합니다.
- RED: 스킬 없이 시나리오를 실행하고 실패를 캡처합니다.
- GREEN: 그 시나리오가 통과하도록 스킬을 추가하거나 개선합니다.
- REFACTOR: 명확성을 높이고, 허점을 줄이며, 토큰 비용을 줄입니다.
TDD가 처음이라면 먼저 TDD 관련 스킬을 로드해 학습한 뒤 writing-skills를 사용하는 것이 좋습니다.
writing-skills는 Claude에 특화된 동작에 어떻게 도움이 되나요?
writing-skills는 Claude 같은 환경을 염두에 두고 설계되었으며, 저장소에는 Anthropic 문서에 맞춘 가이드를 담은 anthropic-best-practices.md가 포함되어 있습니다. 두 가지를 함께 사용하면 다음을 할 수 있습니다.
- Claude가 스킬을 안정적으로 발견하도록 작성
- 컨텍스트 윈도우와 토큰 예산을 존중하는 구조 설계
- SKILL 파일을 Claude가 효율적으로 로드·활용할 수 있도록 구성
따라서 Claude용 스킬 라이브러리를 구축하려는 경우 특히 writing-skills가 유용합니다.
비기술적·비코드 스킬에도 writing-skills를 쓸 수 있나요?
네. 스킬이 시나리오 기반으로 테스트 가능한 반복 가능한 프로세스를 설명하고 있다면 사용할 수 있습니다. 예시는 다음과 같습니다.
- 인시던트 대응 체크리스트
- 코드 리뷰 워크플로
- 문서 리뷰·승인 프로세스
핵심은 프로세스에 다음 요소가 있는지입니다.
- 에이전트가 따르거나 위반할 수 있는 분명한 규칙
- 단계를 건너뛰었을 때 실제로 발생하는 결과
- 준수 여부를 의미 있게 테스트할 수 있는 시나리오
단순 설명이나 서술형 콘텐츠만 있는 경우에는 잘 맞지 않습니다.
examples/CLAUDE_MD_TESTING.md 파일은 어떤 용도인가요?
examples/CLAUDE_MD_TESTING.md는 다음을 보여주는 완전한 예시입니다.
- 시간 압박, 매몰 비용, 권위 vs 속도 등 현실적인 시나리오 설계 방법
- 서로 다른
CLAUDE.md문서 버전들에 대해 시나리오를 실행하는 방법 - 어떤 버전이 스킬 발견·사용을 더 잘 이끌어내는지 비교하는 방법
자신만의 스킬 테스트 캠페인을 설계할 때 이 파일을 템플릿처럼 참고하시면 됩니다.
스킬은 스토리나 케이스 스터디와 어떻게 다른가요?
writing-skills 모델에서:
- 스킬은 검증된 패턴·도구·워크플로를 재사용 가능한 레퍼런스 가이드 형태로 정리한 것입니다.
- 스토리나 케이스 스터디는 특정 문제를 한 번 어떻게 해결했는지에 대한 서술입니다.
writing-skills는 일회성 스토리에서 벗어나, 향후 에이전트가 새로운 상황에서도 찾아서 적용할 수 있는 일반화되고 테스트 가능한 스킬로 발전시키는 데 도움을 줍니다.
스킬이 길어도 괜찮나요?
길이는 컨텍스트 윈도우 때문에 중요합니다. anthropic-best-practices.md는 왜 간결한 스킬이 더 잘 동작하는지 설명합니다.
- 처음에는 메타데이터만 로드되지만, 일단
SKILL.md를 읽기 시작하면 모든 토큰이 대화 히스토리와 공간을 경쟁하게 됩니다. - 각 섹션이 그 자리를 차지할 만큼의 가치를 지니는지 계속 점검해야 합니다.
writing-skills는 다음을 권장합니다.
- 중복 설명을 과감히 줄이기
- 예시는 필요 시 별도 지원 파일로 분리하기
- 테스트 통과에 직접 기여하는 핵심 프로세스와 규칙에
SKILL.md를 집중하기
writing-skills가 효과를 내고 있는지 어떻게 알 수 있나요?
다음과 같은 변화를 통해 효과를 확인할 수 있습니다.
- 압박 상황에서 무시되던 스킬이 이제 실제로 준수되는 경우가 늘어남
- 새 스킬이 단순 텍스트가 아니라 명시적인 시나리오와 테스트를 동반해 도입됨
- 동일한 시나리오에 대해 스킬 유무에 따른 에이전트 행동의 전후 차이를 분명히 보여줄 수 있음
스킬의 유무에 따른 행동 차이를 보여줄 수 없다면, writing-skills에서 제공하는 TDD 루프와 설득·테스트 가이드를 다시 적용해 스킬을 재설계하는 것이 좋습니다.