writing-skills

writing-skills 스킬 개요

writing-skills가 하는 일

writing-skills 스킬은 테스트 주도 워크플로로 agent skill을 만들고, 수정하고, 검증하는 Skill Authoring 가이드입니다. 핵심 아이디어는 단순하지만 분명한 기준이 있습니다. 스킬 작성도 프로세스 문서를 위한 TDD처럼 다루자는 것입니다. 먼저 조언부터 써놓고 잘 되길 기대하는 대신, 압박이 걸리는 시나리오를 만들고, 스킬이 없을 때 어떤 실패가 나는지 관찰한 다음, 실제로 행동을 바꾸는 가이드만 씁니다.

writing-skills를 써야 하는 사람

writing-skills는 Claude Code, Codex 스타일 agent 환경, 또는 이와 비슷한 로컬 skill 디렉터리용 스킬을 직접 작성하는 사람에게 가장 잘 맞습니다. 특히 규율 준수, 검증 단계, 또는 시간 압박이 있을 때 agent가 건너뛰기 쉬운 워크플로를 강제해야 하는 스킬을 만들 때 유용합니다.

실제로 해결하려는 문제

대부분의 사용자는 “markdown 작성 도움”이 필요한 게 아닙니다. 정말 필요한 것은 속도, 자신감, 이미 들인 비용 때문에 agent가 프로세스를 무시하려 할 때에도 실제로 발견되고, 지켜지고, 계속 지켜지는 SKILL.md를 반복 가능하게 만드는 방법입니다. writing-skills는 바로 그 문제를 겨냥합니다.

왜 이 스킬은 일반적인 프롬프트와 다른가

일반적인 프롬프트로도 스킬 초안은 만들 수 있습니다. 하지만 writing-skills는 그 스킬이 실제로 행동을 바꾼다는 것을 입증하는 방법을 제공합니다.

• 압박 시나리오 정의
• 스킬 없이 baseline 테스트 실행
• 관찰된 실패 패턴에 맞춰 문서 작성
• 허점을 막기 위한 재테스트와 리팩터링

그래서 단발성 “스킬 하나 써줘” 지시보다 Skill Authoring에 훨씬 더 적합합니다.

중요한 선행 조건과 트레이드오프

가장 큰 도입 장벽은 writing-skills가 이 저장소의 TDD 관점을 이미 이해하고 있다고 전제한다는 점입니다. 이 스킬은 superpowers:test-driven-development 배경지식을 명시적으로 요구합니다. 이 기반 없이 바로 들어가면 작성 가이드가 필요 이상으로 엄격하거나, 이상할 정도로 테스트 중심처럼 느껴질 수 있습니다.

트레이드오프도 분명합니다. 이 워크플로는 직감으로 초안을 쓰는 것보다 느립니다. 하지만 실패 비용이 크거나, agent가 스킬을 건너뛸 이유를 스스로 합리화할 가능성이 높을 때는 훨씬 낫습니다.

writing-skills 스킬 사용법

writing-skills 설치 맥락

이 저장소에서는 개인 스킬이 Claude Code의 ~/.claude/skills, Codex의 ~/.agents/skills/ 같은 agent별 디렉터리에 들어간다고 안내합니다. obra/superpowers repo에서 skill manager로 설치한다면, 결과물이 실제로 agent가 스캔하는 디렉터리에 들어가는지 꼭 확인하세요.

설치 전에 수동으로 검토할 계획이라면, 먼저 아래 파일부터 보는 것이 좋습니다.

• skills/writing-skills/SKILL.md
• skills/writing-skills/testing-skills-with-subagents.md
• skills/writing-skills/anthropic-best-practices.md
• skills/writing-skills/examples/CLAUDE_MD_TESTING.md

먼저 읽어야 할 파일

빠르게 판단하려면 아래 순서로 읽는 것이 가장 효율적입니다.

1. 메인 워크플로와 포지셔닝을 확인하는 SKILL.md
2. 스킬에 RED/GREEN/REFACTOR를 어떻게 적용하는지 설명하는 testing-skills-with-subagents.md
3. 간결한 작성 원칙을 담은 anthropic-best-practices.md
4. 현실적인 압박 시나리오 예시가 있는 examples/CLAUDE_MD_TESTING.md
5. 스킬이 합리화에 저항해야 한다면 persuasion-principles.md
6. 다이어그램이 필요할 때만 graphviz-conventions.dot와 render-graphs.js

이 순서는 SKILL.md 상단만 대충 훑는 것보다 정보 획득량이 훨씬 높습니다.

writing-skills가 사용자에게 필요로 하는 입력

writing-skills는 주제만 던졌을 때보다, 구체적인 증거를 가져올 때 훨씬 잘 작동합니다. 좋은 입력은 다음과 같습니다.

• 만들거나 수정하려는 정확한 스킬
• 바꾸고 싶은 agent의 행동
• 스킬이 없을 때 실제로 발생한 실패 사례
• agent가 프로세스를 건너뛰고 싶어지는 상황
• 스킬이 배치될 대상 디렉터리와 플랫폼

약한 입력:
“테스트 스킬 작성 좀 도와줘.”

강한 입력:
“데이터베이스 마이그레이션 배포 전 검증을 강제하는 스킬을 만들어줘. 지금은 수정이 뻔해 보이면 agent가 rollback 체크를 건너뛴다.”

막연한 목표를 실제로 쓸 수 있는 프롬프트로 바꾸기

좋은 writing-skills usage 패턴은 네 가지를 한 번에 요청하는 것입니다.

1. 압박 시나리오
2. baseline 실패 예상
3. 스킬 구조
4. 검증 계획

예시:

Use writing-skills for Skill Authoring.

Goal: Create a skill for release-checklist enforcement in ~/.claude/skills/release-checks.
Observed failures: agents skip smoke tests when changes look small; they rationalize that CI is enough.
Need:
- 3 pressure scenarios that trigger those shortcuts
- baseline RED expectations without the skill
- a concise SKILL.md outline
- refactor ideas to close loopholes after first test run
Keep it concise and optimized for discoverability.

이 방식은 “다듬어진 스킬 문서 하나 써줘”보다 훨씬 강력합니다. 스킬이 해결해야 할 실패 모델을 함께 제공하기 때문입니다.

권장되는 writing-skills 사용 워크플로

실무적으로는 아래 흐름이 가장 자연스럽습니다.

1. 강제하려는 행동을 정의한다
2. 압박 시나리오를 2~5개 작성한다
3. 스킬 없이 agent를 테스트한다
4. 실제 합리화 문구와 지름길 행동을 기록한다
5. 그 실패에만 대응하도록 SKILL.md 초안을 쓴다
6. 스킬을 로드한 상태로 다시 테스트한다
7. 여전히 미끄러지는 지점의 문구를 더 날카롭게 다듬는다
8. 준수율을 높이지 못한 설명은 삭제한다

마지막 단계가 중요한 이유는, 함께 포함된 best-practices 가이드가 토큰 효율성과 간결한 지시를 매우 중요하게 보기 때문입니다.

테스트 주도 방식이 특히 중요한 때

다음처럼 준수 비용이 있는 스킬이라면 writing-skills for Skill Authoring이 특히 효과적입니다.

• 추가 테스트가 필요한 경우
• 검증 속도가 느려지는 경우
• 문서 확인 단계가 필요한 경우
• 재시작이나 재작업이 필요한 경우
• 속도 인센티브와 충돌하는 규칙이 있는 경우

반대로 API 문법 치트시트처럼 순수 참고용 스킬은 agent가 굳이 내용을 우회할 이유가 적기 때문에, 이 방법의 효과가 상대적으로 작습니다.

subagent 테스트 참고 문서를 활용하는 방법

testing-skills-with-subagents.md는 실전용 보조 문서입니다. 스킬이 평온한 상황에서 그럴듯해 보이는지만이 아니라, 실제 압박 속에서도 버티는지 테스트하게 도와줍니다. 다음이 필요할 때 읽으세요.

• 시나리오 형식
• RED/GREEN/REFACTOR 대응 방식
• 합리화 포착 방법
• 압박 때문에 규정을 어기는 사례

초안은 괜찮아 보이는데 실제 채택이 약하다면, 보통 이 파일이 가장 빠른 개선 경로입니다.

예시 시나리오는 활용하되, 그대로 베끼지는 말 것

examples/CLAUDE_MD_TESTING.md가 유용한 이유는 압박 시나리오가 실제로 어떤 모습인지 보여주기 때문입니다. 시간 압박, sunk cost, 권위, 익숙함 편향 같은 요소가 구체적으로 드러납니다. 다만 이 시나리오를 관련 없는 스킬에 그대로 복사하는 것은 흔한 실수입니다.

대신 압박의 종류를 자신의 워크플로에 맞게 바꿔 적용하세요. 예를 들면:

• deployment 스킬 → 긴급성, rollback에 대한 두려움
• review 스킬 → 자신감, 속도 편향
• security 스킬 → “이번 한 번만” 식의 합리화
• style 스킬 → 도입 비용이 낮으므로 더 가벼운 테스트

설득 가이드는 워크플로에서 어떤 역할을 하나

persuasion-principles.md는 부수적인 파일이 아닙니다. 프로세스가 명확해도 실패하는 스킬이 있기 때문에 들어 있습니다. agent가 자주 거부하는 행동을 강제해야 한다면, 더 강한 문구가 도움이 될 수 있습니다. 이 파일은 authority, commitment, 명시적 선언 같은 구체적인 패턴을 제안합니다.

다만 신중하게 써야 합니다. 목적은 스킬을 더 시끄럽게 만드는 것이 아닙니다. 필요한 행동을 “안 해도 된다”고 합리화하기 더 어렵게 만드는 데 있습니다.

출력 품질에 영향을 주는 간결성 규칙

이 저장소에서 가장 가치 있는 포인트 중 하나는 스킬도 컨텍스트 예산을 공유한다는 점을 계속 상기시켜 준다는 것입니다. writing-skills는 더 많이 쓰라고 하지 않습니다. 행동을 바꾸는 내용만 쓰라고 요구합니다.

좋은 신호:

• 구체적인 트리거
• 명확한 필수 행동
• 실제 실패와 연결된 짧은 예시
• 최소한의 배경 설명

나쁜 신호:

• 긴 동기부여성 문장
• 반복되는 정의
• 프로세스의 역사 설명
• Claude가 이미 알고 있는 일반론적 “best practices”

선택 사항인 그래프 도구

이 skill 디렉터리에는 render-graphs.js가 포함되어 있습니다. 이 스크립트는 SKILL.md에서 dot 블록을 추출해, graphviz가 설치되어 있으면 SVG 다이어그램으로 렌더링합니다. 이 기능은 선택 사항이며, 주로 워크플로에 분기 상태나 검토 게이트가 있어 사람이 시각적으로 점검해야 할 때 유용합니다. writing-skills 스킬을 사용하는 데 필수는 아니지만, 유지보수자가 프로세스 복잡도를 디버깅하는 데는 도움이 됩니다.

writing-skills 스킬 FAQ

프롬프트를 이미 잘 쓸 줄 알아도 writing-skills를 설치할 가치가 있나?

있습니다. 특히 문제가 초안 작성 속도가 아니라 신뢰성이라면 그렇습니다. 일반적인 프롬프트로도 그럴듯한 스킬은 빠르게 만들 수 있습니다. 하지만 writing-skills는 압박 상황에서도 최종 스킬이 agent 행동을 실제로 바꾸는지에 대한 확신이 필요할 때 빛납니다.

writing-skills는 초보자에게도 친절한가?

어느 정도는 그렇습니다. 글쓰기 자체는 접근하기 어렵지 않습니다. 다만 이 방법론은 TDD식 사고에 익숙하다는 전제를 깔고 있습니다. Skill Authoring이 처음이라면 먼저 이 저장소의 TDD 관련 자료를 읽는 편이 좋습니다. 그렇지 않으면 이 워크플로를 불필요하게 번거로운 절차로 오해할 수 있습니다.

writing-skills가 맞지 않는 경우는 언제인가?

다음 경우에는 writing-skills를 굳이 쓰지 않는 편이 낫습니다.

• 단순 참고용 스킬
• 재사용할 목적이 없는 일회성 메모
• 가이드를 어길 유인이 현실적으로 없는 주제
• 전후 비교 테스트를 전혀 돌릴 수 없는 상황

이런 경우에는 더 가벼운 작성 워크플로만으로도 충분한 경우가 많습니다.

writing-skills는 Anthropic의 skill best practices와 무엇이 다른가?

함께 포함된 anthropic-best-practices.md는 간결하고, 발견 가능하며, 컨텍스트 효율이 좋은 스킬 작성에 초점을 둡니다. writing-skills는 여기에 한 걸음 더 들어가, 먼저 실패를 관찰하고 그 실패를 고치는 내용만 쓰는 행동 변화 관점을 추가합니다. 둘은 경쟁 관계가 아니라 상호 보완적인 가이드입니다.

writing-skills를 쓰려면 추가 repo 도구가 필요한가?

아니요. 이 방법의 효과를 보려면 큰 도구 체계가 필요한 것은 아닙니다. 핵심 자산은 테스트 가이드와 예시입니다. 그래프 렌더링은 선택 사항이며, 핵심 작성 워크플로에 필수인 지원 스크립트도 없습니다.

기존 스킬을 수정하는 데도 writing-skills를 쓸 수 있나?

네. 오히려 더 좋은 활용 사례 중 하나입니다. 이미 스킬이 있는데도 agent가 이를 무시하거나 잘못 사용한다면, writing-skills는 실제 실패 모드를 찾아내고, 쓸모없는 내용을 덜어내고, 가장 중요한 지시를 다시 쓰는 데 도움을 줍니다.

writing-skills 스킬 개선 방법

이상적인 문서가 아니라 관찰된 실패에서 출발하라

writing-skills 결과를 가장 빠르게 개선하는 방법은 실패 증거를 가져오는 것입니다. 이상적인 프로세스만 설명하면 출력이 대체로 평범해집니다. 반대로 agent가 실제로 어떤 지름길을 택했는지 보여주면, 결과 스킬은 더 날카롭고 더 짧아집니다.

더 강한 압박 시나리오를 제공하라

좋은 시나리오는 스킬을 건너뛰고 싶은 실제 유혹을 만들어냅니다. 다음 요소를 포함하세요.

• 시간 압박
• 이전 경험에서 오는 자신감
• sunk cost
• 사람의 권위에서 오는 압박
• “수정은 뻔하다”는 프레이밍

이 조건들이 있어야 지시가 어디서 너무 약한지, 어디서 너무 모호한지 드러납니다.

agent의 실제 합리화 문구를 그대로 잡아라

실패를 “스킬을 무시했다” 정도로 요약하지 마세요. agent가 실제로 무엇을 말했는지, 혹은 어떤 뜻을 내비쳤는지를 기록해야 합니다.

• “이건 작은 변경이다”
• “CI가 잡아줄 것이다”
• “이 패턴은 이미 안다”
• “스킬 읽는 데 시간이 너무 든다”

이런 합리화가 있어야 수정된 writing-skills usage 프롬프트와 최종 스킬 문구가 무엇을 정면으로 다뤄야 하는지 보입니다.

준수가 중요한 지점은 문구를 더 단단하게 다듬어라

스킬이 선택이 아닌 행동을 강제하려는 목적이라면, 모호한 언어는 치명적입니다. 느슨한 제안 대신 명시적 트리거와 필수 행동으로 바꾸세요. 설득 가이드도 여기서 도움이 되지만, 가장 큰 개선은 결국 구체성에서 나옵니다.

• 언제 스킬을 로드해야 하는지
• 가장 먼저 무엇을 해야 하는지
• 무엇은 건너뛸 수 없는지
• 무엇을 성공으로 볼 것인지

행동을 바꾸지 못하는 내용은 제거하라

writing-skills 스킬 출력에서 흔한 실패 패턴은 과도한 설명입니다. 어떤 문단이 발견 가능성, 준수, 테스트 가운데 어느 것도 개선하지 못했다면 잘라내세요. 저장소의 best-practices 파일이 이 점을 핵심 원칙으로 두는 데는 이유가 있습니다.

첫 합격 결과 뒤에도 반복하라

첫 번째 “GREEN” 결과가 나왔다고 충분한 것은 아닙니다. 쉬운 조건에서만 통하는 스킬일 수 있기 때문입니다. 더 거친 프롬프트와 다른 표현으로 다시 테스트하세요. agent가 급할 때, 확신이 강할 때, 혹은 이미 끝낸 작업을 지키려 할 때도 스킬이 여전히 작동하는지 확인해야 합니다.

저장소나 팀 맥락의 예시와 함께 써라

팀에 반복되는 워크플로가 있다면, 대상 스킬의 도메인에 맞는 worked example 하나를 포함하세요. 추상적인 규칙을 더 추가하는 것보다 이런 예시 하나가 실제 채택을 더 크게 끌어올리는 경우가 많습니다. 다만 길고 백과사전식 예시가 아니라, 짧고 압박 테스트를 거친 예시여야 합니다.

다듬기보다 구조를 요청하는 방식으로 프롬프트를 개선하라

writing-skills를 호출할 때는 다음을 요청하세요.

• 시나리오 목록
• 실패 분석
• 간결한 스킬 개요
• 허점을 막기 위한 수정안

처음부터 “세련되게 만들어줘”, “포괄적으로 써줘”라고 하지 마세요. 그런 요청은 보통 길이만 늘리고 준수율은 높이지 못합니다.

애초에 그 스킬이 필요한지 점검하라

writing-skills 가이드 자료의 유용한 결과 중 하나는, 어떤 주제는 애초에 스킬이 필요 없다는 사실을 발견하게 된다는 점입니다. 프로세스가 자명하고, 위험이 낮고, 반복 빈도가 적다면 스킬은 행동 개선 대비 유지 비용만 늘릴 수 있습니다. 그런 결론도 충분히 타당하며, 저장소 품질을 오히려 높입니다.

writing-skills는 새로 만들 때뿐 아니라 리팩터링에도 써라

writing-skills의 가장 가치 있는 활용은 기존 스킬이 실패하는 장면을 본 뒤 그것을 리팩터링하는 경우가 많습니다. 그때 이 방법은 단순한 문서 작성이 아니라 행동 엔지니어링이 됩니다. 바로 그 지점에서 이 저장소가 가장 실질적인 가치를 제공합니다.