Skills 헌법 (Skills Constitution)

한 줄 요약: 모든 스킬/도구/플러그인 위에 군림하는 메타 규칙. 모든 능력 호출은 반드시 이 관문을 통과해야 합니다.

v2.25.0 (현재) — 제5조 '답변 추천' 극도로 토큰 절약 개편: 추천 출처를 "매번 전체 GitHub 검색"에서 로컬 순위 스냅샷 읽기(data/skill_rankings.json + scripts/recommend_skills.py —— 네트워크 제로, 약 20KB, 순수 결정론적 규칙 매칭 + 자동 설치 제외)로 변경; scripts/update_skill_rankings.py 신규 추가: 낮은 빈도로 권위 있는 순위표(quemsah/awesome-claude-plugins, 인덱스 3.6만+ 저장소)를 가져와 스냅샷 재구성, 만료(>30일) 시에는 알림만 표시하고 자동으로 가져오지 않음; step5에 추천 출처 표시 소프트 검증 추가("로컬 순위 스냅샷" = 토큰 절약 모범 사례). v2.24.0 — 보이지 않는 스킬 관리 + 출입 통제 '한 번에 세 가지 검사, 전체 통과' + 경량 인덱스. 실제 수정 5가지: ① parse_frontmatter가 YAML 블록 스칼라(>/| 및 접기 변형) 지원 — 이전 버전은 ponytail 전체 등 137개 스킬의 description을 단일 > 문자로 파싱하여 검색이 절대 적중되지 않음(전형적인 사례: 사용자가 GitHub 116k★의 ponytail을 설치했지만 한 번도 호출되지 않음); ② 인덱스 설명 상한 200→2000 — 트리거 단어(예: ponytail의 lazy mode, 400+ 문자 위치)가 더 이상 잘려서 버려지지 않음; ③ 출입 통제 작업 수준 패스 — 작업 시작 시 세 가지 검사 통과(플랫폼 주입 또는 step1 PASS) 시 전체 통과, 차단을 작업 시작 시의 일회성 알림으로 이동(사용자 명시적 요청: 작업 시작 시 이미 세 가지 검사 완료, 중간에 다시 차단하지 않음); ④ scripts/skill_doctor.py 신규 추가: 보이지 않는/손상된 스킬 자동 진단(8가지 검사) + --fix 자동 수리 + --quarantine 손상 격리 + --emit-min-index 경량 인덱스(전체 인덱스 약 20% 크기, 잘린 부분의 긴 꼬리 트리거 단어 유지, 인기 없는 스킬도 토큰을 절약하며 여전히 적중 가능); ⑤ 그래프 앵커 추출은 항상 처음 200자 사용 + 불용어 세 번째 배치 확장 + DF 상한 0.05→0.035 — 설명 완화 후 앵커가 급증하여 752노드 거대 클러스터가 발생했었으며, 이제 ≤80 규율 복구(회귀 테스트 106/106). v2.23.0 — 스킬 그래프(GitNexus의 사전 계산 관계 지능 차용): 스킬 트리 위에 결정론적 관계 그래프(skill_graph.json, 스킬 트리 재구성 시 자동 생성) 추가. 세 가지 엣지 모두 제로 의존성 결정론적 추출——chains_to(레지스트리의 출력→입력 스키마 교집합) / co_anchor(공유 엔티티 앵커, 불용어 및 문서 빈도 필터 포함) / alternative(동일 분류의 높은 중복 대안); 결정론적 레이블 전파로 기능 클러스터 형성. 세 가지 적용: ① 주입 블록을 "전체 분류 목록"에서 "앵커 스킬의 태스크 라인 그래프"로 축소("왜 관련 있는지" 출처 포함, 토큰 절약); ② Gate step3에 Layer F 그래프 증거 검증 추가——참조된 스킬은 태스크 앵커 그래프와 연결되어야 하며, 연결이 끊긴 클러스터 증거는 FAIL; ③ 대체 엣지는 통과 증빙으로 사용되지 않으며, 클러스터링에 참여하지 않음(GitNexus와 동일하게 구조적 엣지만 커뮤니티 탐지 대상). 그래프 누락 시 모든 연결 체인 동작은 이전 버전과 동일(추가만 하고 삭제하지 않음).

전체 버전 역사는 CHANGELOG.md를 참조하세요.

⚠️ 사전 필터: 작업 유형 판단(제로 조항)

본 헌법은 "전문 작업"에만 적용됩니다, 단순 질의응답에는 적용되지 않습니다. 실행 전에 먼저 판단하세요:

작업 유형	특징	스킬 확인 여부
단순 질의응답	번역, 윤문, 개념 설명, 일반 지식 질의응답	❌ 건너뜀
전문 작업	코딩, 데이터 크롤링, 파일 작업, API 호출, 복잡한 분석	✅ 반드시 확인
모호한 작업	전문 도구 필요 여부 불확실	✅ 일단 확인(놓치지 않음)

판단 기준:

작업이 파일 시스템, 네트워크 요청, 코드 실행, 전문 도구를 포함 → 전문 작업
작업이 텍스트 처리, 지식 질의응답, 간단한 설명에 불과 → 단순 작업

자체 면제: 본 헌법 자체는 메타 규칙이므로, 헌법 조항을 실행할 때 스킬을 다시 확인할 필요 없음(무한 루프 방지).

오판 롤백(제로 조항-C): 에이전트가 작업 유형을 잘못 판단한 경우(예: 전문 작업을 단순 질의응답으로 건너뜀), 사용자는 지적할 권리가 있습니다("이것은 전문 작업입니다. 스킬을 확인해야 합니다"). 이 경우 에이전트는 반드시:

사과하고 오판 인정
즉시 전체 헌법 절차로 롤백(메모리 확인부터 시작)
이번 오판을 메모리 레이어(MISJUDGMENTS)에 기록하여 반복 실수 방지

문제점

에이전트 생태계의 가장 큰 낭비: 스킬을 많이 설치해 놓고도 멍하니 작업을 처리하거나, 기억에 의존하여 잘못 선택하거나, 검색을 전혀 하지 않음. 본 헌법은 "능력 확인→매칭→필수 사용→검색→추천"을 강제 절차로 만들고, 게이트(constitution-check)를 통해 "자율"을 "검증 가능, 차단 가능"으로 만듭니다.

핵심 개념(플랫폼 독립적)

본 헌법은 다음 범용 용어를 사용하며, 각 플랫폼의 구체적인 대응어는 플랫폼 매핑 테이블을 참조하세요:

범용 용어	의미	각 플랫폼의 명칭 예
능력 레지스트리	에이전트가 현재 사용 가능한 모든 스킬/도구/플러그인 목록	available_skills / tools / plugins / extensions / Gems / MCP servers
스킬 설명	각 능력의 트리거 조건 설명	description / trigger / when_to_use / system prompt
스킬 인덱스	기능별로 분류된 스킬 트리(사전 생성, 매칭 가속). ⚠️ 저장소 내 `skill_tree.json`은 작성자 스냅샷/예제이며, 사용자는 `scripts/build_skill_tree.py`를 실행하여 자신의 인덱스를 생성해야 합니다.	skill_tree.json(작성자 스냅샷) / 사용자가 생성한 스킬 트리
스킬 발견	설치 가능한 새 능력 검색	find-skills / GPT Store / SkillHub / MCP Registry / Extensions
메모리 레이어	세션 간 지속되는 규칙 저장소	MEMORY.md / CLAUDE.md / AGENTS.md / Custom Instructions / .cursorrules
스킬 파일	능력을 정의하는 구조화된 문서	SKILL.md / GPT Actions / MCP Config / Gem Instructions

헌법 조항

제0조: 메모리 확인(Pre-Check Memory)

작업을 실행하기 전에 반드시 해당 플랫폼의 메모리/규칙 레이어를 확인하여 관련 규칙, 기록 컨텍스트 또는 할 일이 있는지 확인합니다.

각 플랫폼 메모리 레이어 경로:

플랫폼	메모리 레이어 경로
WorkBuddy	`~/.workbuddy/MEMORY.md` + 프로젝트 `.workbuddy/memory/`
Claude Code	`CLAUDE.md` 또는 `.claude/CLAUDE.md`
Cursor	`.cursorrules` + `.cursor/rules/`
Windsurf	`.windsurfrules`
Cline	`.clinerules`
ChatGPT	Custom Instructions
Gemini	Gem Instructions
Codex	AGENTS.md
일반 규칙	프로젝트 루트 `RULES.md` 또는 `.agent/rules.md`

메모리 확인 순서:

사용자 수준 메모리(장기 선호, 하드 규칙)
프로젝트 메모리(현재 프로젝트 규칙, 기록 결정)
오늘 작업 기록(당일 작업 기록, 중복 방지)

메모리 레이어 필수 내용(부트스트랩 전제: "메모리 확인"이 실제로 스킬을 발견하게 함, v2.3.0 신규):

헌법이 스스로 실행되도록 하기 위해 메모리 레이어에 다음 두 가지 항목을 유지해야 합니다:

항목	내용	예
`INSTALLED_SKILLS`	설치된 스킬 목록(이름 + 한 줄 설명)	`file-ops: 파일 읽기/쓰기 도구, 스킬 인덱스 읽기 용도`
`SKILL_INDEX_PATH`	스킬 인덱스 파일 경로(당신의 스킬 트리, 작성자 스냅샷 아님)	`<당신의 플랫폼 스킬 디렉터리>/skill_tree.json`(예: `~/.claude/skills/`)

예시:

INSTALLED_SKILLS:
- file-ops: 파일 읽기/쓰기 도구, 스킬 인덱스 읽기 용도
- find-skills: 스킬 검색 도구, 새 능력 발견 용도
- agent-memory: 메모리 관리 시스템

SKILL_INDEX_PATH: <당신의 스킬 디렉터리>/skill_tree.json

이 형식으로 메모리 레이어를 유지하기만 하면, 에이전트가 메모리를 확인하여 스킬 목록을 "기억"할 수 있으며, 실시간 스캔이 필요 없어 콜드 스타트 문제가 해결됩니다.

제1조: 먼저 확인(Pre-Check)

전문 작업을 실행할 때마다 반드시 먼저 능력 레지스트리를 확인하여 현재 작업과 관련된 능력이 있는지 판단합니다.

최적화 경로(v2.2.0 신규; v2.7.0 참조 수정):

먼저 당신의 플랫폼 능력 레지스트리(사용 가능한 스킬/도구/플러그인 목록, 예: Claude Code ~/.claude/skills, Cursor .cursor/rules, WorkBuddy available_skills)를 확인합니다. 로컬 스킬 트리가 있으면 우선 사용(scripts/build_skill_tree.py를 실행하여 당신만의 인덱스 생성).
작업 유형에 따라 기능 브랜치를 찾습니다.
브랜치 내에서 설명을 매칭합니다.
미적중 시 전체 스캔(최후 수단).

실행 강화(v2.5.0 신규, 무조건 첫 번째 단계; v2.11.0 강제 적중 목록):

"스킬 인덱스 먼저 확인"은 무조건적인 동작이어야 하며, "내가 필요하다고 생각할 때만 확인"이 아닙니다:

모든 전문 작업(설치 확인/라이브러리 확인 등 포함, 예: 특정 Python 라이브러리 설치 여부 확인)의 첫 번째 단계는 반드시 스킬 트리 인덱스를 읽어야 하며, "이 작업은 스킬 확인이 필요 없음"이라는 이유로 건너뛰는 것을 금지합니다——판단에 의한 건너뛰기가 바로 본 헌법이 방지하려는 행위입니다(실제 운영에서 cognee 확인 시 스킬 트리 건너뛰기가 사용자에게 적발됨).
스킬 트리 인덱스는 스킬(독립 + 플러그인, v2.21.0)과 설치된 Python 라이브러리/도구(🧩 분류)를 모두 포함해야 하며, 하나의 진입점으로 모두 확인 가능합니다.

작업 시작 시 "헌법 3가지 확인" 결과를 명시적으로 보고하여 절차를 보이게 하고 사용자가 감독할 수 있도록 합니다. v2.11.0 강제: ②스킬 트리는 적중된 스킬 이름 목록(이름+근거)을 반드시 나열해야 하며, "스킬 트리 읽음"만 쓰는 것을 금지합니다:

【헌법 3가지 확인】
① 메모리 ✅ 확인 완료(사용자 수준/프로젝트/오늘 작업)
② 스킬 트리 ✅ 읽음(적중 스킬 목록: `git-workflow-and-versioning`(코드/배포), `web-deploy-github`(GitHub 푸시)…)
③ 매칭 ✅ 적중 X → 사용하여 실행; 미적중 → "스킬 트리 무매칭" 설명 후 일반 능력/파일 시스템 사용

v2.11.0 작업 관련 하드 검증(Layer C): 작업에 "코드/코딩/프로그래밍/개발/작성/구현/git/github/push/commit/deploy/배포/크롤러/크롤링/웹페이지/프론트엔드/문서/데이터/이메일/이미지/비디오" 등의 키워드가 포함된 경우, 출력은 반드시 skill_tree.json의 해당 분류에 있는 실제 스킬 이름을 인용해야 함(예: git-workflow-and-versioning), "skills-constitution 확인 완료" 또는 "스킬 트리 읽음"만 쓰고 구체적인 스킬 이름이 없으면 Gate FAIL
단순 질의응답 면제(번역/윤문/개념 설명)

제1조 보충: 이중 메커니즘 플랫폼 커버리지(v2.21.0)

ZCode / Claude Code / DeepSeek Harness(dsh) 등의 플랫폼 능력은 동시에 두 가지 병렬 메커니즘——독립 스킬(스킬 디렉터리의 SKILL.md)과 플러그인 스킬(플러그인 패키지 내의 SKILL.md)에서 비롯됩니다. 본 헌법이 말하는 "능력 레지스트리 / 스킬 라이브러리 / 스킬 트리"는 항상 두 가지를 모두 포함합니다:

동등한 가중치: 플러그인 스킬과 독립 스킬은 "먼저 확인 → 매칭 필수 사용" 절차에서 완전히 동일한 지위를 가지며, "플러그인이므로 스킬이 아님"이라는 이유로 매칭을 우회하는 것을 금지합니다
전체 호출 이름: 플러그인 스킬의 호출 이름은 일반적으로 플러그인명:스킬명 형식(예: document-skills:docx, computer-use:computer-use)이며, 적중 후에는 반드시 전체 호출 이름으로 호출해야 합니다(이중 메커니즘 플랫폼에서 베어 스킬 이름은 스킬 메커니즘에 로드되지 않을 수 있음)
자동 트리 포함: build_skill_tree.py가 플러그인 캐시를 자동으로 스캔하여 스킬 트리에 편입하고 호출 이름을 표시합니다(알려진 플랫폼 경로 자동 발견; 다른 플랫폼은 환경 변수 PLUGIN_CACHE_DIRS 또는 저장소 루트 plugin_roots.json을 사용하여 캐시 디렉터리 지정; 비활성화된 마켓/플러그인은 자동 제외)
플러그인 부가 능력도 동일 규칙 적용: 플러그인이 제공하는 슬래시 명령 / MCP 도구도 "능력 레지스트리"에 속하며, 기존 능력이 있을 때 일반 능력으로 바퀴를 재발명하는 것을 금지합니다

제2조: 매칭 시 필수 사용(Mandatory Use)

작업이 어떤 능력의 설명과 관련되거나 부분적으로 관련되면 → 무조건적으로 해당 능력을 우선 로드하고, 해당 지침에 따라 실행합니다.

금지 행위:

❌ 능력을 우회하여 일반 능력을 직접 사용
❌ 기억에 의존하여 능력을 선택하고 설명을 보지 않음
❌ 여러 개 매칭 시 무작위로 하나 선택(관련도 순으로 정렬하여 최적 선택)

우선 조항: 어떤 능력이 "내가 직접 할 수 있다"고 말하더라도, 먼저 본 헌법을 통해 더 나은 매칭 능력이 없는지 확인해야 합니다.

제3조: 무매칭 → 스킬 발견(Search First)

능력 레지스트리에 매칭이 없음을 확인한 후, 먼저 플랫폼의 스킬 발견 메커니즘을 통해 관련 능력을 얻을 수 있는지 검색합니다.

찾음 → 사용자에게 설치/활성화 후 사용 제안
못 찾음 → 제4조로 진행

제4조: 능력 경계(Honest Boundary)

"할 수 없다 / 권한이 없다 / 도구가 없다"고 느껴지면 → 반드시 먼저 스킬 발견 메커니즘을 통해 확인하고, 사용 가능한 능력이 없음을 확인한 후에야 "할 수 없다"고 답변할 수 있습니다.

금지 행위:

❌ 검색하지 않고 바로 "할 수 없음"
❌ 전문 능력이 필요한 작업을 일반 능력으로 억지로 처리
❌ 한 것처럼 속였지만 실제로 능력을 호출하지 않음

제5조: 답변 시 자동 추천(Auto-Discovery)

작업 완료 후(답변 단계) → 로컬에 설치된 스킬이 작업을 완벽하게 해결하지 못한 경우, 로컬 순위 스냅샷을 우선 읽어 더 나은 능력을 추천하고 사용자가 설치 여부를 결정합니다. 로컬 스킬이 부족한데 "추천하지 않음"은 위반입니다. v2.15.0: 추천 후보는 반드시 로컬에 설치된 스킬을 제외해야 함(추천은 "당신이 설치하지 않은 더 강한 능력", 설치된 항목은 절대 추천하지 않음). v2.25.0: 추천 출처를 '로컬 순위 스냅샷 우선'으로 변경, 극도로 토큰 절약 —— 답변 시마다 더 이상 전체 GitHub를 검색하지 않음.

트리거 시나리오(하나만 충족하면 반드시 실행):

로컬 스킬 트리를 확인했지만 완전히 매칭되는 스킬이 없음
로컬에 매칭되는 스킬이 있지만 실행 결과가 만족스럽지 않음(예: GitHub 푸시 차단, 스크립트 오류)
작업이 명백히 로컬 스킬 범위를 초과함(예: 전용 도구/agent/플러그인 필요)

추천 출처(v2.25.0 우선순위):

로컬 순위 스냅샷(최우선, 네트워크 제로, 검색 제로): data/skill_rankings.json(저장소 내 작성자 스냅샷) 읽기, python scripts/recommend_skills.py --task "<작업>" 실행 —— 순수 로컬 키워드 매칭 + 별 수 정렬 + 로컬 설치 스킬 자동 제외, 3개 출력(각각 GitHub 링크 + 별 수 + 획득 방법 포함, step5 검증 자연스럽게 충족).
GitHub 검색(스냅샷에 매칭이 없을 때만 최후 수단): 스냅샷 항목과 작업이 전혀 관련이 없을 때만 WebSearch/WebFetch로 github.com의 높은 Star 저장소를 검색하고, 추천 블록에 "출처: GitHub 검색"을 표시.
스냅샷 만료 처리: 스냅샷이 stale_days(기본 30일) 이상 업데이트되지 않은 경우, 추천 시 상단에 python scripts/update_skill_rankings.py 실행 알림 표시 —— 알림만 하고 자동으로 가져오지 않음(토큰 절약).

추천 형식:

🔍 관련 스킬 추천 (출처: 로컬 순위 스냅샷 data/skill_rankings.json, 업데이트: 2026-09-01):
- 이름: xxx — 한 줄 강조점 + GitHub 링크 + Star 수 + 획득 방법 (설치 여부는 당신이 결정)
(최대 3개, 도배 방지)

실행 세칙(v2.6.0 강화; v2.11.0 위치 수정; v2.15.0 설치 제외; v2.25.0 스냅샷 우선):

추천 핵심: 반드시 GitHub 높은 Star 수의 skill/tool/agent 저장소(별 수 + 링크 + 획득 방법 포함)——이것이 사용자가 설치 여부를 결정하는 근거입니다. 데이터 출처는 로컬 순위 스냅샷(recommend_skills.py 출력)을 우선하고, 그 다음이 GitHub 검색입니다.
토큰 절약 철칙(v2.25.0): 추천 단계는 기본적으로 네트워크 제로——로컬 data/skill_rankings.json(약 20KB)만 읽고 결정론적 규칙 매칭 실행; 스냅샷이 없거나 작업과 스냅샷이 전혀 관련이 없는 경우에만 GitHub 검색을 허용합니다.
스냅샷 갱신(저빈도): python scripts/update_skill_rankings.py로 권위 있는 순위표 저장소(quemsah/awesome-claude-plugins 등)에서 Top100을 가져와 스냅샷 재구성; 릴리스마다/매주 한 번 실행 권장, 평소에는 실행하지 않음.
추천 전에 "로컬에서 확인한 스킬과 부족한 이유"를 간략히 설명하는 것("로컬에 git-workflow-and-versioning이 설치되어 있지만 네트워크 차단")을 허용하여 사용자가 새 스킬이 필요한 이유를 이해하도록 돕습니다.
"로컬 설치 스킬 목록"으로 추천을 대체하는 것은 금지(로컬 스킬은 배경 설명으로만 사용).
v2.15.0 설치 제외(하드 액션): 추천 전에 반드시 로컬 설치 목록(예: ls ~/.workbuddy/skills/)과 대조하여 후보 저장소가 로컬 설치 스킬과 이름/출처가 동일하면 절대 추천하지 않음——여기에는 "검색 결과가 우연히 설치된 저장소와 일치하는 경우"도 포함됩니다(예: addyosmani/agent-skills가 설치되어 있으면 다시 추천 금지). recommend_skills.py는 해당 제외를 내장(_<name>-references 프레임워크 표시 포함); GitHub 검색 경로에서도 수동으로 확인해야 합니다. 배경 설명으로만 사용 가능("로컬에 X가 이미 있습니다. 더 강력한 것이 필요하면 Y를 확인하세요").
Gate constitution-check --step 5와 함께 사용하여 추천 블록의 규정 준수를 자동 검증 가능(github.com/owner/repo 링크 + 별 수 표시 + 획득 방법 + v2.15.0 Layer E 로컬 설치 제외 검증 + v2.25.0 추천 출처 표시: "로컬 순위 스냅샷" 표시 = 토큰 절약 모범 사례)

실행 폐쇄 루프(5단계)

작업 → ①유형 판단(단순 질의응답 면제; 전문 작업 필수 확인) → ②메모리 확인 → ③스킬 트리 확인(브랜치별 위치 확인) → ④매칭 시 필수 사용/무매칭 시 필수 검색 → ⑤답변 시 추천(설치 제외).

스킬 트리(Skill Tree)

기능별 분류, 실행 시 브랜치별 위치 확인으로 스캔 범위 80%+ 감소:

스킬 트리/
├── 📜 메타 규칙류(헌법/보안 감사)
├── 🧠 메모리/지식 관리류(개인 메모리/프로젝트 지식 그래프/세션 지속성)
├── 🌐 네트워크/검색류(웹 자동화/데이터 크롤링/API/검색)
├── 💻 개발/코딩류(코드 생성/리뷰/테스트/빌드 배포)
├── 📄 문서 처리류(PDF/Word/Excel/PPT/형식 변환)
├── 🖼️ 콘텐츠 생성류(이미지/비디오/UI 디자인)
├── 💰 비즈니스 전용류(금융/법률/전자상거래 마케팅)
└── 🔧 일반 도구류(파일 작업/프로세스 관리/환경 설정)

전체 인덱스: skill_tree.json은 작성자 스냅샷(예제). 사용자는 설치 후 반드시 자신의 스킬 트리를 재구성해야 함(전체 명령/플랫폼 차이/자가 진단은 → Load reference/skill-tree-guide.md 참조). 선별 스킬: registry.json.

스킬 그래프(v2.23.0): 트리는 "행정 구역"(인위적 분류), 그래프는 "자연 취락"(관계 기반). build_skill_tree.py가 스킬 트리 재구성 시 자동으로 skill_graph.json 생성(또는 scripts/build_skill_graph.py를 별도로 실행하여 기존 트리에서 재구성 가능): 노드=스킬, 엣지= chains_to(출력→입력 스키마 연결)/ co_anchor(공유 엔티티 앵커)/ alternative(대안), 결정론적 레이블 전파로 기능 클러스터 형성(예: "코드 릴리스" 클러스터 = git 워크플로 + 리뷰 + 배포). 용도: 작업 라인별 주입 축소, Gate Layer F 그래프 증거, 추천 시 스킬 간 관계 설명.

빠른 주입 템플릿

다음 템플릿을 각 플랫폼의 규칙/지침/메모리 레이어에 직접 복사하여 사용할 수 있습니다:

## Skills 헌법(Skills Constitution) v2.25.0

본 규칙은 모든 스킬/도구/플러그인보다 우선합니다. 모든 능력 호출은 반드시 이 관문을 통과해야 합니다.

실행 경로:
1. 먼저 메모리 확인: 플랫폼 메모리 레이어(MEMORY.md/CLAUDE.md 등) 확인
2. 먼저 스킬 확인: 스킬 인덱스 확인, 작업 유형별 기능 브랜치 위치 확인, **출력은 반드시 적중된 스킬 이름 목록을 나열해야 함**
   (스킬 인덱스는 독립 스킬과 플러그인 스킬 포함(v2.21.0): 플러그인 스킬 적중 시 전체 호출 이름 `플러그인명:스킬명`으로 호출)
3. 매칭 시 필수 사용: 매칭되면 무조건 해당 능력 우선 사용
4. 무매칭 시 필수 검색: 먼저 획득 가능한 능력 검색, 그 다음 일반 능력 고려
5. 능력 경계: "할 수 없음"을 말하기 전에 먼저 검색하여 사용 가능한 능력이 없음을 확인
6. 답변 추천(v2.25.0 스냅샷 우선, 극도로 토큰 절약): 로컬 스킬이 작업을 완벽하게 해결하지 못한 경우, **로컬 순위 스냅샷 우선** `python scripts/recommend_skills.py --task "<작업>"` 실행(네트워크 제로, 설치 자동 제외, 링크+별+획득 방법 포함 3개 출력); 스냅샷에 매칭 없을 때만 GitHub 검색; 스냅샷 만료(>30일) 시 `python scripts/update_skill_rankings.py` 실행하여 갱신; **v2.15.0 추천 후보는 반드시 로컬 설치 스킬 제외(먼저 로컬 설치 목록 확인, 설치된 항목은 절대 추천하지 않음)**

위반 판정: 메모리/스킬 목록 확인을 건너뛰고 바로 실행 / 매칭이 있지만 사용하지 않음 / 검색 없이 거절 / 스킬 트리 확인했지만 적중된 스킬 이름을 나열하지 않음(빈 보고) / 로컬 스킬이 부족한데 추천하지 않음(스냅샷 우선) / **로컬 설치 스킬을 추천(v2.15.0, Layer E 검증 FAIL)** / **플러그인 스킬 적중 시 "플러그인이므로"라는 이유로 우회(v2.21.0)**

필수 요구 사항

능력 작성자: description이 유일한 매칭 기준이므로, 트리거 조건(언제 나를 사용할지)을 정확히 작성하고 플랫폼 형식을 따르며 분류를 정확히 해야 합니다. 프레임워크 개발자: 세션 시작 시 헌법 주입; 능력 레지스트리는 작업 전에 접근 가능; 사전 생성된 스킬 인덱스(skill_tree.json)를 지원하여 매칭 가속.

다른 규칙과의 관계

우선순위 높은 순에서 낮은 순:

1. 🔴 시스템 보안 규칙(위반 불가)
2. 📜 Skills 헌법(본 규칙) —— 모든 스킬/도구/플러그인 위에 군림
3. 🔧 특정 능력의 실행 지침
4. 🤖 에이전트 일반 능력

위반 판정

다음 행위는 심각한 위반에 해당하며, 사용자는 재작업 및 이유 설명을 요구할 권리가 있습니다:

위반 행위	판정 기준
메모리 확인을 건너뛰고 바로 실행	작업 완료되었지만 플랫폼 메모리 레이어를 확인하지 않음
스킬 목록 확인을 건너뛰고 바로 실행	작업 완료되었지만 관련 능력을 로드하지 않음
매칭 있지만 사용하지 않음	능력 레지스트리에 매칭 능력이 있지만 로드하지 않음
빈 스킬 확인(v2.11.0)	"스킬 트리 읽음/헌법 확인 완료"만 쓰고 적중된 구체적인 스킬 이름을 나열하지 않으며, 작업에 코드/git/배포 등 키워드 포함
잘못된 브랜치 확인(v2.11.0)	작업이 코딩/푸시를 요구하지만 관련 없는 분류 스킬(예: 문서류)을 인용
검색 없이 거절	"할 수 없음"이라고 말했지만 스킬 발견 메커니즘을 통해 확인하지 않음
복습 추천 없음(v2.11.0; v2.25.0 스냅샷 우선)	로컬 스킬이 작업을 완벽하게 해결하지 못했지만 추천하지 않음(로컬 순위 스냅샷 `recommend_skills.py` 우선)

기술 경계 설명

"모든 능력을 무조건 활성화"는 불가능(컨텍스트 폭발). 올바른 설계는 설명 매칭으로 트리거하는 것이며, 본 헌법은 이 매칭 메커니즘이 건너뛰어지지 않도록 강제합니다. 스킬 트리 인덱스는 전체 스캔을 대상 브랜치로 축소(토큰 80%+ 절약); 인덱스는 build_skill_tree.py에 의해 생성되며, 수동 작성 금지(v2.17.0: 사용자는 로컬에서 SKILLS_DIR=<스킬 디렉터리> python scripts/build_skill_tree.py를 실행하여 자신의 트리를 생성하고 작성자 스냅샷을 교체해야 함).

게이트 증거 체인(v2.22.0): 게이트(constitution-gate)는 두 가지 "3가지 확인 완료" 증거를 인정하며, 하나만 충족하면 쓰기 작업을 통과시키고 마무리 시 중복 검증하지 않음: ① 본 작업 내 constitution-check --step 1 실제 검증 통과(수동 경로); ② 플랫폼이 메모리+스킬 트리를 이미 주입(주입 컨텍스트 ready) 하고 본 작업 내에서 적중 스킬을 실제로 호출함(스킬 호출은 게이트에 의해 자동 기록됨). 동일 작업 내의 추가 메시지는 증거를 재설정하지 않음; 게이트 자체의 상태/면제/위반 파일은 에이전트가 변조하는 것을 금지(변조 시 차단).

플러그인 스킬 스캔(v2.21.0): 이중 메커니즘 플랫폼(ZCode / Claude Code / DeepSeek Harness 등)에서 스킬 트리는 플러그인 캐시의 플러그인 스킬도 동시에 편입——알려진 플랫폼 경로 자동 발견(ZCode는 해당 config의 플러그인 활성화 테이블에 따라 비활성화 항목을 추가로 제외); 다른 플랫폼은 PLUGIN_CACHE_DIRS 환경 변수(여러 디렉터리는 시스템 경로 구분자 사용) 또는 저장소 루트 plugin_roots.json({"cache_dirs": ["..."]})을 사용하여 캐시 디렉터리 지정; PLUGIN_SCAN=0으로 전체적으로 끌 수 있음. 플러그인 항목은 qualified_name(전체 호출 이름) 필드를 가지며, pre-hook 주입 시 자동으로 표시됩니다.

선택적 강화(기본 비활성화): scripts/semantic_index.py 벡터 의미 검색은 pip install sentence-transformers faiss-cpu(약 90MB)가 필요하며 python scripts/semantic_index.py build로 인덱스를 구축해야 함; SAD 느슨한 의미 검색(제로 의존성)이 이미 일상 검색을 커버하므로 활성화하지 않아도 기본 경로 기능에 영향을 주지 않습니다.

참조 문서(필요 시 로드)

크로스 플랫폼 적응 / 플랫폼 매핑 테이블 → Load reference/platform-mapping.md
설치 / 훅 등록 / 검증 → Load reference/installation.md
게이트 검증 메커니즘(constitution-check 사용법 / hooks / 설계 포인트) → Load reference/gate-details.md
사용자 스킬 트리 구축 가이드(전체 명령 / 플랫폼 차이 / 자가 진단 / FAQ) → Load reference/skill-tree-guide.md

위는 점진적 공개: 메인 파일에는 핵심 조항만 포함되고, 세부 사항은 필요 시 로드하여 토큰을 제어합니다.

기여 가이드

Issue 및 PR을 환영합니다:

기능 개선: 분류 규칙 확장, 플랫폼 매핑 추가
문서 최적화: 표현 수정, 예제 추가
버그 수정: 분류 로직, 스크립트 오류

License

MIT License — 자유롭게 사용, 수정, 배포 가능.

작성자

jiabaobei — GitHub

이 규칙이 에이전트가 능력을 호출하지 않는 문제를 해결하는 데 도움이 되었다면 ⭐ Star를 눌러주세요!

jiabaobei/skills-constitution

skills-constitution란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서