스킬은 마크다운으로 적은 절차적 지식입니다. 도구가 모델이 호출하는 함수라면, 스킬은 사용자가 /skill로 호출하거나 트리거 키워드로 매칭되는 지시문 묶음입니다. 런타임 엔진은 core/skills/skills.py입니다.
3계층 저장소
스킬은 세 계층에서 발견됩니다 (core/cli/commands/skill.py).
| 계층 | 위치 | 성격 |
|---|---|---|
| builtin | core/skills/ (저장소와 함께 배포) | 코드와 같이 버전 관리 |
| project | .geode/skills/ | 팀 공유, git에 커밋 |
| personal | ~/.geode/skills/ | 개인 로컬 전용 |
로더(core/skills/skills.py)는 번들 → 개인 → 프로젝트 순서로 디렉터리를 걷고, 같은 이름이 충돌하면 나중 스코프가 이깁니다. 프로젝트 스킬이 최우선입니다. GEODE를 개발할 때 Claude Code가 쓰는 scaffold 스킬(.claude/skills/)은 이 런타임 레지스트리와 완전히 별개입니다.
SKILL.md 형식
--- name: my-skill description: 무엇을 하는 스킬인지. "키워드1", "키워드2" 키워드로 트리거 tools: read_document, grep_files user-invocable: true context: fork # 격리 서브에이전트로 실행 (선택) argument-hint: "[issue-number]" --- 본문 마크다운. $ARGUMENTS 가 호출 인자로 치환되고, !`cmd` 는 호출 시점에 셸 실행 결과로 치환됩니다.
로딩은 점진적입니다. 시작 시에는 frontmatter 메타데이터만 읽고, 본문은 호출 시점에 로드합니다. 시스템 프롬프트에는 스킬 카탈로그 요약이 core/agent/loop/_context.py의 {skill_context} 블록 한 곳으로만 들어갑니다.
호출
| 표면 | 동작 |
|---|---|
/skill <name> [args] | 스킬 하나를 호출합니다. $ARGUMENTS 치환과 동적 컨텍스트 실행 포함 (core/cli/commands/skills.py) |
context: fork 스킬 | 렌더된 본문을 run_agentic_oneshot(core/cli/bootstrap.py)으로 넘겨 격리된 서브에이전트 원샷으로 실행합니다. geode-mcp의 run_agent와 같은 최소 스택입니다 |
/skills | 목록, 추가, 리로드 |
geode skill list / create / show / remove | 3계층을 관리하는 CLI. --private로 personal 계층에 생성합니다 |
frontmatter의 user-invocable: false는 스킬을 배경 지식으로 돌려 /skills 목록에서 숨깁니다.
실패 모드
| 증상 | 원인 | 해법 |
|---|---|---|
| 새로 만든 스킬이 안 보임 | 레지스트리가 아직 옛 카탈로그를 들고 있음 | /skills reload 또는 세션 재시작 |
| 같은 이름인데 의도한 버전이 안 잡힘 | 스코프 override. 프로젝트가 개인을 이깁니다 | geode skill show <name>으로 어느 계층이 잡혔는지 확인합니다 |
| fork 스킬이 메인 대화 컨텍스트를 못 봄 | context: fork는 격리 실행이 목적 | 필요한 내용을 인자로 전달하거나 fork를 빼고 인라인으로 돌립니다 |
다음
- 프롬프트 조립.
{skill_context}블록이 들어가는 자리. - 도구와 툴셋. 스킬과 도구의 경계.
- 서브에이전트 오케스트레이션. fork 실행의 기반.