Skills — GEODE Docs

스킬은 마크다운으로 적은 절차적 지식입니다. 도구가 모델이 호출하는 함수라면, 스킬은 사용자가 /skill로 호출하거나 트리거 키워드로 매칭되는 지시문 묶음입니다. 런타임 엔진은 core/skills/skills.py입니다.

3계층 저장소

스킬은 세 계층에서 발견됩니다 (core/cli/commands/skill.py).

계층	위치	성격
builtin	`<package>/.geode/skills/` (wheel과 함께 배포)	코드와 같이 버전 관리
project	`.geode/skills/`	팀 공유, git에 커밋
personal	`~/.geode/skills/`	개인 로컬 전용

로더(core/skills/skills.py)는 번들 → 개인 → 프로젝트 순서로 디렉터리를 걷고, 같은 이름이 충돌하면 나중 스코프가 이깁니다. 프로젝트 스킬이 최우선입니다. GEODE 개발 중 Claude Code와 Codex가 쓰는 scaffold 스킬은 이 런타임 레지스트리와 별개입니다. 저장소는 .agents/skills/를 단일 정본으로 공개하고, .claude/skills/는 같은 바이트를 가리키는 상대 symlink만 둡니다.

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} 블록 한 곳으로만 들어갑니다.

프로젝트·개인 스킬 승인

wheel과 함께 출하되는 builtin 스킬은 1급 코드로 승인됩니다. project와 personal 스킬은 계층 우선순위로 승자를 고른 다음확장 신뢰 정책의skill:<name> 항목을 확인합니다. 승인되지 않은 상위 계층 스킬을 발견했다고 하위 계층의 같은 이름으로 몰래 fallback하지 않습니다.

wheel은 arxiv-digest, deep-researcher,frontier-ui-ux-catalog, geo,geode-context, grilling,long-task-watcher, pdf만 번들합니다. 저장소에 함께 공개된 pr-reviewer,slop-audit, wiki-sync는 project-only라 wheel에는 들어가지 않습니다. 전체 메타·런타임 인벤토리는저장소 문서에서 확인할 수 있습니다.

"skill:my-skill": {
  "enabled": true,
  "trusted": true,
  "execution": "trusted",
  "capabilities": ["shell"]
}

capabilities: ["shell"]은 본문에!`cmd` 동적 컨텍스트가 있을 때만 필요합니다. 이 권한은 명령을 샌드박스에 넣지 않습니다. 해당 스킬을 신뢰해 호출 시점에 GEODE 프로세스 권한으로 실행하도록 명시적으로 승인하는 것입니다.

스킬 평가 경계

GEODE의 prospective native suite는 web, repository, delegation 과제를 target Skill이 보이는 arm과 보이지 않는 arm으로 짝짓습니다. 두 arm은 같은 도구 schema와 격리 workspace를 사용하며, availability, selection, activation, verifier outcome, 비용·안전 지표를 따로 보고합니다. 반복은 새 example로 세지 않고 source example 안에서 묶습니다. 이 계약은 diagnostic-only이며 live 실행에는 별도 승인된 run spec이 필요합니다. 전체 계약은 Skill attribution evaluation 문서를 따릅니다.

호출

표면	동작
`/skill <name> [args]`	스킬 하나를 호출합니다. `$ARGUMENTS` 치환과 동적 컨텍스트 실행 포함 (`core/cli/commands/skills.py`)
`context: fork` 스킬	렌더된 본문을 `run_agentic_oneshot`(`core/cli/bootstrap.py`)으로 넘겨 격리된 서브에이전트 원샷으로 실행합니다. geode-mcp의 `run_agent`와 같은 최소 스택입니다
`/skills`	목록, 추가, 리로드
`/grill`, `/geo`	`grilling`과 `geo` 스킬을 기존 AgenticLoop에 스트리밍 주입하는 전용 별칭. 장기 GEO는 최대 3개의 독립 읽기 전용 증거 branch만 기존 협업 도구로 실행하고 부모가 합성·검증합니다. 별도 executor나 thought-tree 엔진은 만들지 않습니다
`geode skill list / create / show / remove`	3계층을 관리하는 CLI. `--private`로 personal 계층에 생성합니다

frontmatter의 user-invocable: false는 스킬을 배경 지식으로 돌려 /skills 목록에서 숨깁니다.

실패 모드

증상	원인	해법
새로 만든 스킬이 안 보임	레지스트리가 아직 옛 카탈로그를 들고 있음	`/skills reload` 또는 세션 재시작
같은 이름인데 의도한 버전이 안 잡힘	스코프 override. 프로젝트가 개인을 이깁니다	`geode skill show <name>`으로 어느 계층이 잡혔는지 확인합니다
project/personal 스킬이 발견됐지만 목록에 없음	`skill:<name>` 승인 누락 또는 동적 컨텍스트의 `shell` 권한 누락	extension policy를 고친 뒤 새 세션을 시작합니다. 거부 상태는 runtime health의 `extensions`에서 확인합니다
fork 스킬이 메인 대화 컨텍스트를 못 봄	`context: fork`는 격리 실행이 목적	필요한 내용을 인자로 전달하거나 fork를 빼고 인라인으로 돌립니다

프롬프트 조립. {skill_context} 블록이 들어가는 자리.
도구와 툴셋. 스킬과 도구의 경계.
서브에이전트 오케스트레이션. fork 실행의 기반.