스킬 문서는 반복 실행을 스크립트로 내리고 같은 지시를 한 곳에서만 소유하게 쓴다

스킬을 오래 쓰다 보면 SKILL.md 는 두 방향으로 부푼다. 매 실행마다 같은 셸 레시피가 본문에 들어 있고, 같은 규칙이 여러 절에 조금씩 다른 말로 반복된다. 이 글은 Claude Code 스킬 시스템에서 소개한 스킬 문서를 오래 유지하기 위한 두 가지 원칙을 정리한다. 하나는 반복 실행을 스크립트로 내리는 것이고, 다른 하나는 같은 지시를 한 곳에서만 소유하게 하는 것이다.

사례는 모두 공개 저장소 fos-skills의 커밋 이력에서 가져왔다.

실행 코드는 scripts 에, 판단 문맥은 SKILL.md 에

자동화에는 성격이 다른 두 자산이 있다. 하나는 결정적으로 반복할 수 있는 실행이고, 다른 하나는 에이전트가 읽고 판단해야 하는 문맥이다. 두 자산을 서로 다른 파일에 두면 각자 따로 검토하고 고칠 수 있다.

분리하면 얻는 것은 네 가지다.

• 에이전트가 긴 코드를 매번 다시 만들지 않고 같은 실행을 재사용한다.
• 명령 구현을 바꿔도 판단 기준과 사용자 흐름을 독립적으로 검토할 수 있다.
• 같은 지시를 여러 스킬에 복제해서 생기는 어긋남(drift)이 줄어든다.
• 스크립트의 종료 코드와 산출물을 테스트할 수 있어, 자연어 지시보다 강한 검증 경계가 생긴다.

사례: 본문에 있던 셸 레시피를 스크립트로 내린다

fos-skills 의 docs-check 스킬은 2026-07-27 에 정적 검사를 별도 스크립트로 분리했다. 커밋 메시지가 적은 이유는 이렇다. SKILL.md 본문에 25줄짜리 셸 레시피 세 개가 들어 있어서, 모델이 매 실행마다 코드를 다시 옮겨 적었다는 것이다. 그 저장소의 스킬 작성 규칙은 다섯 줄을 넘고 매 실행마다 반복되는 코드는 분리하라고 정한다.

분리하는 과정에서 결함이 두 건 드러났고 함께 고쳤다.

• 코드 스팬 안의 ~/path 를 취소선으로 오탐했다. 코드 블록과 코드 스팬을 검사에서 제외하도록 고쳤다.
• grep -nP 는 기본 BSD grep 에서 지원되지 않아 공용 코어에 맞지 않았다. PCRE 없이 리터럴 매칭으로 바꿨다.

본문에 적혀 있을 때는 실행할 때마다 달라질 수 있는 코드였으므로 이런 결함이 드러나기 어려웠다. 스크립트로 내리자 한 번 고치면 모든 실행에 반영된다. 현재 이 검사는 docs-check/scripts/static_check.py 와 docs-check/tests/test_static_check.py 로 존재한다.

같은 판단은 다른 스킬에도 적용된다. planning 스킬이 어느 하위 프로젝트의 오버레이를 읽을지 정하는 규칙은 문서에 순서가 적혀 있고, 같은 순서를 scripts/overlay_paths.py 가 그대로 실행한다. 종료 코드가 0 이면 대상을 정했다는 뜻이고, 1 이면 사용자에게 물어야 하며, 2 이면 실행하지 못했다는 뜻이다. 문서는 종료 코드의 뜻과 그에 따른 행동만 설명하고, 판정 자체는 스크립트가 맡는다.

같은 지시는 한 곳에서만 소유한다

스킬 문서는 시간이 지나며 절이 늘어난다. 새 절을 추가하면서 기존 절의 내용을 요약해 다시 적으면 같은 규칙이 두 곳에 존재한다. 한쪽만 고치면 다른 쪽이 낡은 채 남고, 문서가 스스로 모순된다. 어느 쪽이 맞는지는 실행 시점에 판단이 갈린다.

판정 기준

• 소유자를 정한다. 두 절이 같은 내용을 담고 있으면 더 구체적으로 다루는 쪽(절차 절이나 하위 reference)을 소유자로 정한다. 핵심 원칙 같은 상위 요약에서는 지운다. "통과 조건은 절차 절이 단일 소스다" 처럼 소유권을 밝히는 한 줄이 중복을 막는다.
• 자기소개도 대상이다. "이 스킬은 공용 코어다" 같은 소개가 README 나 description 에 이미 있으면 본문 첫머리의 소개는 지운다.
• 모델이 이미 아는 내용은 적을 값이 없다. git 의 기본 동작이나 자명한 도구 동작은 지시로 적지 않는다.
• 끊긴 참조를 만들지 않는다. 소유자를 옮길 때 다른 곳이 그 절의 이름을 참조하고 있으면, 참조를 먼저 떼거나 그 줄이 혼자 읽히도록 흡수한 뒤에 지운다.
• 옮긴 뒤에 내용이 그대로인지 확인한다. 절을 옮기거나 합칠 때 변경 전후를 정렬해 비교하면 내용은 그대로이고 위치만 바뀐 것인지 확인할 수 있다.

사례: 소유자를 지키는 정리 커밋

fos-skills 의 이력에는 이런 정리가 반복된다. content-preview 스킬은 2026-09-22 에 자기를 부르는 쪽의 이름을 적은 문장을 지웠다. 공용 스킬이라 어느 저장소에서 받았는지에 따라 부르는 쪽이 없을 수 있기 때문이다. 커밋 메시지의 기준은 "누가 가리키는지가 아니라 무엇을 소유하는지만 적는다" 였다. 같은 커밋은 스크립트의 동작을 다시 설명하던 한 줄도 지웠다. 바로 다음 줄이 그 스크립트가 소유한다고 말하고, 아래 출력 표가 이미 다루기 때문이다.

2026-09-21 에는 harness-cleanup 스킬의 조건부 절차를 참조 문서로 내렸다. 저장소 밖에서 돌릴 때만 필요한 절차가 불릿 하나 안에 25줄로 들어 있어서 매 실행마다 컨텍스트를 차지했기 때문이다. 본문에는 발동 조건과 읽을 경로만 남겼다.

옮기는 과정에서 지시가 빠질 수 있다

단일 소유권으로 정리하는 일에는 위험이 있다. 앞의 참조 문서 이동에서 읽기 전용 검토자가 지시 하나가 유실된 것을 찾았다. "상대경로가 어느 디렉터리를 전제하는지 함께 본다" 는 문장이 옮기는 과정에서 사라졌고, 뒤쪽에서 그것을 되짚던 "위에서 요구한" 이 가리킬 곳을 잃었다. 이 문장을 원래 절에 되돌리고, 되짚는 문장이 그 절의 이름을 부르게 고쳤다.

그래서 옮긴 뒤에는 작성자가 아닌 쪽이 읽어 확인한다. 옮긴 사람은 내용이 그대로라고 믿고 있어서 유실을 잘 보지 못한다.

스킬 사이에서도 소유권이 있다

소유권은 스킬 사이에도 적용된다. fos-skills 에서 두 스킬이 다른 스킬 번들에 있는 파일 경로를 자기 번들의 파일처럼 적은 일이 있었다. 끊긴 참조를 세는 검사기를 처음 만들자마자 이 결함이 잡혔다. 이 검사기는 아래 「스킬 문서 자체를 채점하기」 에서 다룬다.

스킬 문서 자체를 채점하기

스킬 문서가 나아졌는지 알려면 기준이 고정돼 있어야 한다. 기준값 없이 고치면 개선 여부를 나중에 측정할 수 없다. 문서의 품질은 기계로 셀 수 있는 축과 판단이 필요한 축으로 나눠서, 축마다 담당 도구를 다르게 둔다.

판단축은 작성자가 직접 매기지 않는다. 자기 산출물을 자기가 채점하면 후하게 나오기 때문이다. 채점은 작성과 다른 세션이나 에이전트가 한다.

사례: 기준점을 먼저 남기고 검사기가 첫 실행에서 결함을 찾는다

fos-skills 는 2026-07-27 에 이 구조로 채점 도구를 넣었다. 커밋 메시지는 도입 이유를 기준점 없이 고쳐 와서 개선 여부를 소급 측정할 수 없었던 것으로 적는다. 스크립트는 본문 분량, 끊긴 참조, 표기 위반을 세고, 채점표는 판단축 네 가지를 0점에서 3점으로 매겼다.

구조를 바꾸기 직전에 기준값을 남겨 두면 변경 뒤 줄 수가 달라졌을 때 지시 내용이 바뀐 것인지 순수한 이동인지 구분할 수 있다. 끊긴 참조 검사는 만들자마자 앞 절의 결함, 즉 다른 스킬 번들의 파일을 자기 번들 경로처럼 적은 두 곳을 찾았다.

소비하는 곳이 없으면 제거한다

이 채점 도구는 같은 저장소에서 2026-09-04 에 제거됐다. 커밋 메시지가 적은 이유는 누적 점수를 소비하는 곳이 없었다는 것이다. 점수를 보고 무언가를 바꾸는 사용처가 없으면 채점 도구는 유지할 값이 없다. 같은 판단이 하네스 회고는 새 문서로 쌓지 않고 종류에 맞는 기존 단일 소스에 환원한다에도 나온다.

정리