ouroboros · 확장점: Hooks / Skills / Slash-Commands 형식

한 줄 요약

ouroboros 플러그인은 호스트 AI(Claude Code/Codex)에게 자기 기능을 알릴 때 Hooks(자동 트리거) · Skills(기능 설명서 겸 대본) · Slash-Commands(사용자용 명령 버튼) 세 가지 통로만 쓰며, 하나의 기능이 이 셋에서 같은 이름으로 일관되게 선언된다. 왜 배우나: 이 세 통로의 형식과 역할 분담을 알아야 플러그인이 “AI에게 언제·어떻게 끼어드는지”를 이해하고, 새 명령을 직접 추가할 수 있다.

그림

flowchart TD
  U["사용자: ooo seed S123"] --> H[UserPromptSubmit 훅 발동]
  H --> KD[keyword-detector.py 프롬프트 분석]
  KD -->|MCP 미설정| GATE[setup 화면으로 리다이렉트]
  KD -->|키워드 매칭| INJ["원문 + 스킬추천 블록 주입"]
  INJ --> M[모델이 최종 프롬프트 수신]
  M --> CMD["commands/seed.md 가 위임"]
  CMD --> SK["skills/seed/SKILL.md 대본 적재"]
  SK --> MCP["call_mcp: ouroboros_generate_seed 호출"]
  MCP --> QA["QA 루프 0.90 / 사용자 게이트"]
  QA --> OUT[검증된 Seed YAML 산출]
  W["파일 Write/Edit"] --> PT[PostToolUse 훅 발동] --> DM[drift-monitor.py 활성세션 검사]

쉽게 풀기

ouroboros는 Claude Code(또는 Codex)라는 “운영체제” 위에 얹는 **앱(플러그인)**이다. 앱이 운영체제에게 “나 이런 기능 있어요”라고 알리는 콘센트가 딱 세 개뿐이라고 생각하면 된다.

Hooks — 자동 센서 “이런 순간이 오면 자동으로 이 작업을 해라”는 동작 감지기다. 비유하자면 현관 센서등이다. 사람이 스위치를 누르지 않아도, 정해진 순간(문 열림)에 자동으로 켜진다. ouroboros의 훅은 다음 세 순간에 미리 정한 파이썬 스크립트를 자동 실행한다.
- 세션이 시작될 때(SessionStart)
- 사용자가 메시지를 보낼 때(UserPromptSubmit)
- 파일을 쓰거나 고친 직후(PostToolUse)
Skills — 기능 설명서 겸 대본 skills/<이름>/SKILL.md라는 종이 한 장이다. 거기에는 그 기능의 이름, 한 줄 설명, 연결될 MCP 도구, 그리고 “이 작업을 하려면 어떤 권한(능력)이 필요한지”가 적혀 있다. 식당으로 치면 “이 요리를 만들려면 가스불·칼·냉장고가 필요하다”고 적힌 레시피 카드다.
Slash-Commands — 사용자용 버튼 commands/*.md는 사용자에게 /ouroboros:seed 같은 슬래시 명령으로 보이는 얇은 표면이다. 버튼 자체에는 로직이 거의 없다. 누르면 “옆방의 진짜 대본(SKILL.md)을 읽고 그대로 따라라”고 넘길 뿐이다.

핵심은 이름의 일관성이다. seed라는 하나의 기능이 commands/seed.md(버튼) → skills/seed/SKILL.md(대본) → ouroboros_generate_seed(MCP 도구) 세 곳에서 같은 이름으로 줄줄이 연결된다. 그리고 plugin.json/marketplace.json은 이 셋을 하나의 설치 꾸러미로 묶는 포장지(매니페스트)다.

핵심 정리

통로	정체	모델에 들어가는 방식
Hooks	자동 트리거 스크립트	호스트가 이벤트 때 실행 → stdout을 컨텍스트에 주입
Skills	기능 설명서 겸 절차 대본	사용자가 명령 칠 때 SKILL.md 전문을 모델이 적재
Slash-Commands	사용자용 명령 버튼	버튼이 SKILL.md로 위임

[!note] 관측된 훅 이벤트 3종

이벤트 matcher 스크립트 역할
SessionStart * session-start.py 업데이트 확인. 성공 시 침묵(stdout=컨텍스트라 오염 방지), 알림은 stderr
UserPromptSubmit *(생략 가능) keyword-detector.py 프롬프트 분석 → 매칭 스킬을 <skill-suggestion>으로 주입
PostToolUse Write|Edit drift-monitor.py 파일 수정 후 활성 인터뷰 세션 감지 → 드리프트 경고

이벤트	matcher	스크립트	역할
`SessionStart`	`*`	`session-start.py`	업데이트 확인. 성공 시 침묵(stdout=컨텍스트라 오염 방지), 알림은 stderr
`UserPromptSubmit`	`*`(생략 가능)	`keyword-detector.py`	프롬프트 분석 → 매칭 스킬을 `<skill-suggestion>`으로 주입
`PostToolUse`	`Write\|Edit`	`drift-monitor.py`	파일 수정 후 활성 인터뷰 세션 감지 → 드리프트 경고

[!note] Claude 변형 vs Codex 변형

Claude(hooks/hooks.json): 이벤트 3개, command가 단순 python3 "...경로...".

Codex(.codex/hooks.json): SessionStart 없이 2개. matcher를 생략하고, command에 ROOT="${CLAUDE_PLUGIN_ROOT:-$PWD}" 루트 폴백 + python3 ... || python ... 폴백을 넣는다. 런타임 환경이 덜 보장되기 때문.

스키마 필수 필드 체크:

Hooks: hooks.<EventName>[].hooks[].type은 관측상 "command"(셸 실행)뿐, command는 필수, timeout은 초 단위 상한(session-start=5, keyword-detector=5, drift-monitor=3)
Skills: name(슬래시 표면과 일치), description 필수 / mcp_tool, mcp_args($1=명령 첫 인자)는 선택
Commands: description 필수 / aliases 선택(seed→crystallize, run→execute), 본문은 SKILL.md로 위임하는 한 줄
매니페스트: plugin.json이 "skills": "./skills/", "mcpServers": "./.mcp.json"로 묶음(hooks·commands는 폴더 컨벤션으로 자동 발견)

[!note] 능력(Capability) 토큰 — SKILL.md 본문의 계약 블록 ## Required Skill Capabilities에 적는 추상 권한이며, 런타임별 실제 의미는 SKILL_CAPABILITY_GUIDE.md가 매핑한다.

능력 토큰 의미(seed 기준)
ask_user 구조화 질문으로 사람 판단을 물음
inspect_code 로컬 파일 읽기로 저장소 근거 확보(추측 금지)
call_mcp MCP 도구 직접 호출(필요 시 deferred 도구 탐색·로드)
run_shell 감사로그·셋업용 경계 있는 로컬 셸
refine_answer 자유서술 결정을 상태로 넘기기 전 구조화 확인
maintain_ledger QA 점수·후보·기각안·감사키를 세션에 가시화
(가이드 추가) run_lateral_review, web_research, run_closure_gate, restate_goal lateral 호출·웹리서치·게이트 감사·전환 전 목표 재진술

능력 토큰	의미(seed 기준)
`ask_user`	구조화 질문으로 사람 판단을 물음
`inspect_code`	로컬 파일 읽기로 저장소 근거 확보(추측 금지)
`call_mcp`	MCP 도구 직접 호출(필요 시 deferred 도구 탐색·로드)
`run_shell`	감사로그·셋업용 경계 있는 로컬 셸
`refine_answer`	자유서술 결정을 상태로 넘기기 전 구조화 확인
`maintain_ledger`	QA 점수·후보·기각안·감사키를 세션에 가시화
(가이드 추가) `run_lateral_review`, `web_research`, `run_closure_gate`, `restate_goal`	lateral 호출·웹리서치·게이트 감사·전환 전 목표 재진술

실제 예시

훅 정의 — Claude 변형과 Codex 변형의 차이를 비교하며 본다.

// /home/seunghyeong/harness-work/ouroboros/hooks/hooks.json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/session-start.py\"",
            "timeout": 5
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/drift-monitor.py\"",
            "timeout": 3
          }
        ]
      }
    ]
  }
}

// /home/seunghyeong/harness-work/ouroboros/.codex/hooks.json  (Codex 변형: matcher 없음 + 폴백 체인)
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "ROOT=\"${CLAUDE_PLUGIN_ROOT:-$PWD}\"; python3 \"$ROOT/scripts/keyword-detector.py\" || python \"$ROOT/scripts/keyword-detector.py\"",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

스킬 — frontmatter(메타 + 도구 연결) 아래에 능력 계약 블록.

# /home/seunghyeong/harness-work/ouroboros/skills/seed/SKILL.md  (frontmatter + 능력 계약)
---
name: seed
description: "Generate validated Seed specifications from interview results"
mcp_tool: ouroboros_generate_seed
mcp_args:
  session_id: "$1"
---

# /ouroboros:seed

## Required Skill Capabilities

- `ask_user` — ask human-judgment questions through the active runtime's user-question surface.
- `inspect_code` — read repo-local agent roles and recover exact context from local files before guessing.
- `call_mcp` — use available Ouroboros MCP tools directly, including runtime tool discovery when a deferred MCP surface must be loaded.
- `run_shell` — run bounded local commands for audit-trail writes and setup steps.
- `refine_answer` — confirm free-form user decisions before treating them as accepted seed revisions.
- `maintain_ledger` — keep QA scores, candidate decisions, rejected proposals, and audit trail keys visible.

슬래시 명령 — 로직 없이 SKILL.md로 위임하는 얇은 표면(façade).

<!-- /home/seunghyeong/harness-work/ouroboros/commands/seed.md -->
---
description: "Generate validated Seed specifications from interview results"
aliases: [crystallize]
---

Read the file at `${CLAUDE_PLUGIN_ROOT}/skills/seed/SKILL.md` using the Read tool and follow its instructions exactly.

매니페스트 — 세 표면을 폴더 컨벤션으로 묶고 MCP 서버 기동법을 선언.

// /home/seunghyeong/harness-work/ouroboros/.claude-plugin/plugin.json (발췌)
{ "name": "ouroboros", "version": "0.41.0", "skills": "./skills/", "mcpServers": "./.mcp.json" }

새 명령 foo를 세 표면에 일관 선언하는 최소 템플릿.

<!-- commands/foo.md — 얇은 표면 -->
---
description: "한 줄 설명"
aliases: [bar]
---
Read the file at `${CLAUDE_PLUGIN_ROOT}/skills/foo/SKILL.md` using the Read tool and follow its instructions exactly.

# skills/foo/SKILL.md — 대본 + 계약
---
name: foo
description: "한 줄 설명"
mcp_tool: ouroboros_foo
mcp_args:
  session_id: "$1"
---
## Required Skill Capabilities
- `call_mcp` — ...
- `ask_user` — ...
## Instructions
1. (deferred 도구면) runtime tool discovery로 ouroboros_foo 로드
2. call_mcp 로 호출 → 결과 처리

새 명령 추가 시 자기점검 체크리스트:

commands/foo.md의 description과 skills/foo/SKILL.md의 description이 일치하는가
skills/foo/SKILL.md의 name == /ouroboros:foo 슬래시 표면 == keyword-detector.py의 KEYWORD_MAP 항목
mcp_tool이 .mcp.json 서버가 실제로 제공하는 도구 이름인가
본문이 쓰는 능력 토큰이 모두 SKILL_CAPABILITY_GUIDE.md에 정의돼 있는가
hook command가 ${CLAUDE_PLUGIN_ROOT} 사용(Codex 대상이면 ${...:-$PWD} + python3||python 폴백)
hook stdout 규약: 성공 시 침묵 또는 Success만, 컨텍스트 주입은 의도된 경우만
plugin.json의 skills/mcpServers 경로가 폴더와 맞는가
MCP 미설정 시 setup으로 게이트되는가(SETUP_BYPASS_SKILLS 예외 여부 결정)

요약 & 셀프체크

3줄 요약:

ouroboros는 Hooks(자동 센서)·Skills(레시피)·Slash-Commands(버튼) 세 통로로만 호스트 AI에 끼어들며, 한 기능이 이 셋에서 같은 이름으로 연결된다.
Hooks는 모델이 부르지 않아도 이벤트 시 호스트가 실행해 stdout을 컨텍스트에 주입하고, Skills/Commands는 사용자가 명령을 칠 때 SKILL.md 대본을 모델에 적재한다.
이렇게 외부(훅)와 내부(스킬 대본)에서 게이트·QA 임계값(0.90)을 강제해, 모델이 임의로 행동하지 않고 스펙주도 절차를 밟게 만든다.

스스로 답해보기:

/ouroboros:seed를 쳤을 때, 모델이 실제로 컨텍스트에 적재하는 파일은 commands/seed.md인가 skills/seed/SKILL.md인가? 왜 그런가?
session-start.py가 성공 시 stdout을 침묵하고 알림을 stderr로 보내는 이유는?
Codex 변형 훅에만 ${CLAUDE_PLUGIN_ROOT:-$PWD}와 python3||python 폴백이 들어가는 이유는?

연결

OB_개요 · _분석축_루브릭

[!tip] 왜 모델이 이 표면을 소비하나 (설계 근거) ouroboros는 스펙주도(Seed → Double-Diamond) + 이벤트소싱 시스템이라, 모델이 임의로 행동하지 않고 **게이트(setup 게이트, User Adoption Gate)·온톨로지·QA 임계값(0.90)**을 거치도록 강제해야 한다. Hooks는 그 게이트를 모델 외부에서 주입하고(예: MCP 미설정이면 setup으로 리다이렉트하는 게이트, drift-monitor의 ~/.ouroboros/data/interview_*.json 1시간 내 활성세션 경고), Skills는 절차를 모델 내부 대본으로 주입한다. 즉 스킬 본문은 “모델에게 주입되는 절차적 프롬프트”다. 근거 파일: hooks/hooks.json · .claude/settings.json(UserPromptSubmit+PostToolUse, ROOT 폴백 변형) · .codex/hooks.json · scripts/session-start.py · scripts/keyword-detector.py · scripts/drift-monitor.py · skills/seed/SKILL.md · .claude-plugin/SKILL_CAPABILITY_GUIDE.md · commands/run.md · commands/seed.md · .claude-plugin/plugin.json · .claude-plugin/marketplace.json · .claude-plugin/.mcp.json (모두 /home/seunghyeong/harness-work/ouroboros/ 하위)