writing-skills

Execution contract

입력은 신규 스킬의 목적이나 수정할 스킬 경로다. 저자가 실제 실패와 기존 지침을 확인해 필요한 최소 스킬을 쓰고 행동으로 검증한다. 대상이 식별되지 않으면 확인한다. 배포할 스킬은 플러그인 리포의 skills/<이름>/SKILL.md에 둔다. 개인 스킬은 실행 환경의 스킬 디렉터리를 따른다. 이 문서의 링크는 스킬 디렉터리 기준이다. 출력은 스킬과 필요한 자산, 관측된 실패·수정 후 행동·재현 절차다. 다음 스킬로 자동 전환하지 않는다.

Start from observed behavior

스킬 없이 작업 시나리오를 실행해 실패를 관측한 뒤 그 실패만 겨냥한 문구를 쓴다. 기존 스킬은 수정 전후를 같은 시나리오로 비교한다. 대조군이 실패하지 않으면 해당 지침을 추가하지 않는다. 일반 지식, 적용을 바꾸지 않는 근거, 중복 지시와 가상 합리화는 본문에 넣지 않는다. 삭제해도 필요한 행동이 유지되는 지침은 제거한다. 참조 파일로 옮겨 매번 읽게 하는 것은 절감이 아니다.

예외가 필요하면 막연한 뉘앙스 조항 대신 적용 조건을 명시한다.

Write the skill contract

groundwork:writing-for-junior의 문서 계약과 판독 기준을 적용한다. 입력·실행자·출력·경로 기준을 밝히고, 실행 가능한 셸 블록은 변수 대입과 상태 공유 전제를 명시한다.

• 프론트매터는 name과 description만 쓴다. name은 문자·숫자·하이픈, 전체 프론트매터는 1,024자 이하로 쓴다.
• description은 500자 이하로 Use when으로 시작하고 트리거·증상·맥락만 적는다. 절차를 요약하지 않는다.
• h1은 스킬 디렉터리 이름, 나머지 헤딩은 영문 sentence case, 본문은 한국어로 쓴다. 작업 제목은 원형 동사, 개념 제목은 명사구로 쓰고 -ing로 시작하지 않는다.
• 절 참조는 실제 영문 제목과 Markdown 앵커, 파일 참조는 스킬 디렉터리 기준 상대 링크를 쓴다. 다른 스킬의 실행은 groundwork:<이름>으로 요청한다.
• 외부 URL은 파일 끝의 슬러그 각주로 모은다. 같은 URL은 한 정의를 공유한다.
• 철칙은 > [!CAUTION], 역할·주입 경계는 태그, 절차 예시는 코드 펜스, 주장은 볼드로 표현한다.

스킬은 본문 하나로 시작하고 자산은 필요할 때만 추가한다. 매 세션 주입은 800단어, 서브에이전트 프롬프트는 1,000단어, 그 밖의 본문은 2,500단어를 넘으면 불필요한 지침과 실제 로드량을 검사한다. 상한을 맞추려고 필요한 규칙을 지우지 않는다.

Verify the wording

행동을 바꾸는 새 문구는 실제 배치될 본문·프롬프트 전체와 실패를 유혹하는 작업으로 테스트한다. 문구 없는 대조군을 포함하고 변형마다 새 컨텍스트에서 5회 이상 반복한다. 자동 채점의 매치는 직접 읽어 인용·템플릿 반향을 제외한다. 규율 실패는 시간·매몰 비용·탈진 등 복합 압박에서도 확인한다. 문구 마이크로 테스트만으로 실제 작업의 준수를 주장하지 않는다. 수정 뒤에는 같은 시나리오의 행동과 실행 계약을 확인하고 새 실패가 없으면 더 보강하지 않는다. 배포에는 실제 관측과 검증의 한계를 함께 남긴다.