writing-skills (obra/superpowers)

리뷰

Codex CLI 0.166 (gpt-6-astra, low reasoning)을 전용 Windows 테스트 PC에서 실행했고, 실행마다 새 임시 프로젝트와 임시 HOME/TMPDIR/캐시를 사용했습니다. 스킬 설치(스킬 사용군), 미설치(대조군), 미설치 상태에서 스킬의 핵심 요구사항만 한 문장으로 압축해 프롬프트에 덧붙인 경우(한 문장 프롬프트군)로 나눴으며, 과제·그룹당 2회씩 실행했습니다. 네트워크는 끄고 /tmp 쓰기는 차단했습니다. 프롬프트에는 스킬 이름을 언급하지 않았습니다(아래에 적은 경우 제외). 과제는 세 가지입니다: 네 가지 규칙으로 커밋 메시지 스킬 작성하기, 핵심을 잃지 않고 부풀려진 AGENTS.md 다듬기, 버그 트리아지 스킬 작성하기(S1/S2/S3와 '빠진 재현 절차를 먼저 요청'). 대조군에는 과제만 주어집니다. 한 문장 프롬프트에는 설명 규칙, 짧은 SKILL.md, 구체적 예시 하나를 담은 문장을 추가했습니다.

3개 그룹 비교

Codex CLI에서 18회 실행해 측정했고, LLM 심사 없이 규칙 기반 검사로 채점했습니다. 총점 17.6 / 30, 판정 상황에 따라.

판정: 상황에 따라 (17.6 / 30). 출처: obra/superpowers, skills/writing-skills, 커밋 2ce8aa1에 고정. 설치: npx skills@latest add obra/superpowers --skill writing-skills. 라이선스: MIT(저장소 LICENSE).

무엇인가

obra/superpowers의 writing-skills 스킬입니다. 에이전트 스킬을 작성하는 가이드로, 테스트 주도 작성법(실패를 기준선으로 삼고, 최소 스킬을 작성하고, 허점을 막음)을 중심으로 합니다. 프런트매터 설명(트리거 조건만, 'Use when'으로 시작, 워크플로 요약 금지), 파일 구조, 토큰 효율, 상호 참조에 관한 규칙을 정합니다. render-graphs.js 도우미와 긴 참고 파일을 제공합니다.

테스트 방법

Codex CLI 0.166(gpt-6-astra, 낮은 추론)을 전용 Windows 테스트 PC에서 실행했고, 실행마다 새 임시 프로젝트와 임시 HOME/TMPDIR/캐시를 사용했습니다. 스킬을 설치한 스킬 사용군, 스킬이 없는 대조군, 스킬 없이 핵심 요구사항을 한 문장으로 압축해 프롬프트 끝에 붙인 한 문장 프롬프트군으로 나눴으며, 작업·군당 2회 실행, 네트워크 차단, /tmp 쓰기 차단 조건이었습니다. 프롬프트에는 스킬 이름을 전혀 언급하지 않았습니다(아래에 적은 표현 제외).

세 가지 작업입니다. 네 가지 규칙으로 커밋 메시지 스킬 작성, 핵심을 잃지 않고 비대해진 AGENTS.md 압축, 버그 트리아지 스킬 작성(S1/S2/S3와 '누락된 재현 단계를 먼저 묻기'). 대조군은 작업만 받습니다. 한 문장 프롬프트는 설명 규칙, 짧은 SKILL.md, 구체적 예시 하나를 담은 문장을 추가합니다.

1. 커밋 메시지 스킬 작성 — skills/commit-writer/SKILL.md에 스킬(SKILL.md)을 작성해, 코딩 에이전트가 다음 규칙에 따라 커밋 메시지를 쓰게 하세요. 제목은 명령형이고 50자 미만이며 끝에 마침표를 찍지 않습니다. 그다음 빈 줄과 72자에서 줄바꿈한 본문…
2. AGENTS.md 압축 — AGENTS.md가 아무도 읽지 않을 만큼 커졌습니다. 에이전트가 실제로 필요한 것을 잃지 않으면서 최대한 짧아지도록 그 자리에서 다시 작성하세요.
3. 버그 트리아지 스킬 작성 — skills/bug-triage/SKILL.md에 스킬(SKILL.md)을 작성해, 에이전트가 들어온 버그 보고를 S1(데이터 손실 또는 서비스 중단), S2(주요 기능 고장이나 우회 방법 있음), S3(사소하거나 외관상 문제)로 분류하고, 누락된 재현 단계를 먼저 묻…

채점은 프로그램 방식(숨은 테스트/심어 둔 문제 탐지/제약 조건 검사/해당되는 경우 렌더링+OCR)으로 진행하며 실행당 0~5점입니다. 어떤 점수도 LLM 심사자가 결정하지 않았습니다.

결과

세 번째 군에 제공한 한 문장 프롬프트: "스킬 설명문에는 언제 쓰는지만 적으세요(트리거 조건, 'Use when'으로 시작, 약 400자 미만, 워크플로 요약 금지). SKILL.md는 짧고 명령형으로 유지하고, 부피 큰 참고 자료는 밖으로 옮기고, 서술 대신 구체적 예시 하나를 넣으세요."

평균 점수: 스킬 없음 4.43 vs 스킬 사용 4.88(델타 +0.45). 실행당 토큰: 64k vs 163k(2.56배), 시간 34초 vs 52초. 한 문장 프롬프트군: 4.71(한 문장 프롬프트 대비 스킬의 이득: +0.17, 스킬 없음 대비 한 문장 프롬프트의 이득: +0.29). 한 문장 프롬프트는 실행당 66k 토큰이므로 스킬 비용은 한 문장 프롬프트의 2.45배입니다.

무슨 일이 있었나

• 스킬 4.88, 한 문장 4.71, 대조군 4.43(각 6회). 이득은 설명문에서 나옵니다. 대조군의 설명문은 워크플로를 요약했습니다('누락된 재현 단계를 요청하고 심각도를 S1, S2, S3로 분류하여 들어온 버그 보고를 트리아지합니다'). 이는 스킬이 경고하는 안티패턴이며, 대조군의 버그 트리아지 스킬 두 개 모두 품질 검사에서 7점 만점에 5점을 받았습니다('사용 시점' 표현과 구체적 예시). 스킬 군과 한 문장 군은 'Use when ...' 설명문을 작성해 트리아지와 커밋 메시지 실행 4회 모두 7/7을 받았습니다.
• 비용: 실행당 스킬 163k 토큰으로 대조군 64k, 한 문장 66k(2.5배)였습니다. 커밋 스킬 작업에서 스킬 사용 두 실행은 긴 참고 파일을 읽느라 243~255k 토큰을 썼고(트리아지에서는 최대 229k), 스킬과 무관한 AGENTS.md 압축 작업에서는 68~85k를 썼습니다.
• 커밋 메시지 스킬에서 대조군은 두 실행 모두 '이유를 설명하고 72자에서 줄바꿈' 규칙을 빠뜨렸고(규칙 4개 중 3개), 스킬과 한 문장 실행은 모두 네 가지를 지켰습니다.
• AGENTS.md 압축(작업 2)은 모든 군에서 같은 4.64였고, 한 문장 실행 하나가 3.64였습니다('마이그레이션은 추가 전용' 규칙을 빼고 오래된 문서 포인터를 남김). 이 작업에서 스킬이 압축된 파일을 더 낫게 만들지는 못했습니다. AGENTS.md에 다시 적힌 package.json 명령을 세는 검사는 18회 실행 모두 실패했으므로 결함 있는 검사로 보고 무시했습니다.
• 도우미(render-graphs.js, execFileSync로 dot 실행)는 실행하지 않았습니다.

항목별 점수

이 테스트의 한계

• 생성된 SKILL.md 파일에 대한 규칙 기반 검사(프런트매터, 설명 문구, 길이)와 규칙 탐지 검사를 했습니다. 작성된 스킬이 실제로 에이전트 행동을 바꾸는지는 테스트하지 않았는데, 바로 그것이 이 스킬의 방법이 요구하는 것입니다.
• 검사 하나(AGENTS.md의 package.json 명령)는 결함이 있어 모든 실행에서 실패합니다.
• 셀당 n=2.
• 작업·군당 n=2: 약 1점 미만의 차이는 노이즈입니다.
• 규칙 기반 채점은 검사가 볼 수 있는 것만 측정하며, 취향이나 결과가 최선인지는 판단하지 못합니다.

보안

security.md를 참고하세요. 스캔: CRITICAL 0 / HIGH 1 / MEDIUM 1. 판정: 실행해도 안전(네트워크 차단 샌드박스). 깨끗한 스캔 결과가 스킬의 안전성을 증명하지는 않습니다.

결론

트리거에 가장 중요한 한 가지 규칙(스킬이 무엇을 하는지가 아니라 언제 써야 하는지를 설명)을 가르치고 스킬 파일을 더 깔끔하게 만들지만, 토큰이 2.5배 들고 한 문장으로 거의 전부를 얻을 수 있습니다. 가이드를 읽어 보되, 작은 스킬 편집마다 로드하지는 마세요.