지식위키

fable-ish · 스킬 워크플로우 지침 계층

fable-ish · 스킬 워크플로우 지침 계층

한 줄 요약

fable-ish의 “스킬 계층”은 모델(Claude)이 직접 읽는 마크다운 작업 매뉴얼로, 훅이 기계적으로 “지금은 deep 모드”라고 찔러주면 그 한 줄을 “그럼 무엇을 어떻게 검증하나”로 풀어주는 사람용 지침서다. 왜 배우나 → 코드(훅)로는 적을 수 없는 “판단 규율”을 어떻게 글로 적어 모델에게 위임하는지, 그리고 토큰 낭비 없이 필요할 때만 펼치는 점진적 공개 설계를 배우기 위해서다.

그림

flowchart TD
    P[사용자 프롬프트] --> H1["UserPromptSubmit 훅<br/>모드·위험도 분류"]
    P --> SK["런타임이 트리거 매칭<br/>→ SKILL.md 본문만 로드"]
    H1 -->|"짧은 지시 한 줄 주입<br/>'지금은 deep 모드…'"| M[모델]
    SK -->|"핵심 규칙 + 참조 색인"| M
    M -->|필요할 때만 펼쳐 읽음| R1["references/workflow.md<br/>모드·작업루프"]
    M -->|필요할 때만 펼쳐 읽음| R2["references/verification.md<br/>검증 사다리"]
    M -->|필요할 때만 펼쳐 읽음| R3["references/final-report.md<br/>보고 형식"]
    M --> ACT["작업 + 검증 실행"]
    ACT --> PT["PostToolUse 훅<br/>증거를 장부에 기록"]
    M --> ST{"Stop 훅<br/>증거 충분한가?"}
    PT --> ST
    ST -->|"증거 없음 → 종료 차단"| M
    ST -->|"증거 충분 → 통과"| END["최종 보고<br/>final-report 형식"]

쉽게 풀기

fable-ish 플러그인은 두 개의 뇌로 돌아간다고 생각하면 쉽다.

  • 첫 번째 뇌 = 훅(파이썬 스크립트). 사람 손 없이 작업을 자동 분류하고, 증거를 기록하고, 증거가 없으면 “끝내지 마”라고 종료를 막는 기계적 게이트다. 정직하지만 융통성은 없는 “문지기”다.
  • 두 번째 뇌 = 스킬 워크플로우 지침 계층(이 노트의 주제). 코드가 아니라 모델이 읽는 마크다운 매뉴얼이다. “위험이 큰 작업일수록 더 깊게 검증하라”, “직접 돌려보지 않은 검증을 통과했다고 말하지 마라” 같은, 선배가 신입에게 일러주는 작업 규율을 글로 적어둔 것이다.

핵심 트릭은 점진적 공개(progressive disclosure) 다. 비유하자면 두꺼운 업무 매뉴얼 전체를 책상에 항상 펼쳐두는 게 아니라, 표지+목차 한 장(SKILL.md) 만 늘 보이게 두고, 상세 챕터(모드선택·작업루프·검증사다리·보고형식)는 서랍(references/ 폴더의 별도 파일 3개)에 넣어두는 방식이다. 모델은 목차를 보고 “이번 작업은 검증 증거가 필요하니 검증 챕터만 꺼내 읽자”처럼 그 작업에 필요한 챕터만 꺼낸다.

훅과 스킬은 한 쌍으로 작동한다. 훅이 매 프롬프트마다 “지금은 deep 모드다, 종료 전 증거를 대라”라는 한 줄짜리 컨텍스트를 찔러 넣으면, 스킬은 그 한 줄을 “그럼 검증 사다리에서 어느 단을 골라야 하지?”로 풀어주는 사람용 해설서가 된다. 같은 규율의 기계어판(훅)과 사람어판(스킬) 인 셈이다.

핵심 정리

SKILL.md를 구성하는 두 부분

부분역할핵심 내용
frontmatter스킬을 언제 켤지 신호name(디렉터리명과 일치) + description(트리거 문장)
본문 섹션모델이 읽는 행동 규율도입부 / Core Rule / References / Operating Notes

description 한 문장에 꾹 눌러담은 세 가지

  • 트리거 키워드 — complex implementation, debugging, refactoring, deployment preparation, “완료에 관찰 가능한 증거가 필요한 작업” 등 (스킬이 켜질 상황)
  • 오타 별칭 — common typo fablish (fable-ish를 fablish로 잘못 쳐도 같은 스킬이 걸리게)
  • 제외 조건 — “가벼운 설명/저위험 질문엔 켜지지 마라”는 음성(negative) 트리거

[!note] references/ 3개 파일 — 점진적 공개로 지연 로딩

  • references/workflow.md → 모드 선택 + 작업 루프 + 리뷰 렌즈 (4모드 판정 기준, 8단계 작업 루프, 5개 리뷰 렌즈, 선택적 서브에이전트)
  • references/verification.md → 어떤 증거를 고르고 보고할지 (6단계 검증 사다리, baseline delta-zero 규칙, 검증기 없을 때, 정지 기준)
  • references/final-report.md → 최종 보고 형식 (5항목 표준형, 9항목 플러그인 전환 보고, “실행·관찰 안 한 건 통과라 말하지 마라”)

[!note] 위험 비례 4모드 — 훅과 스킬이 같은 어휘를 공유

  • quick — 간단한 설명·방향 확인·저위험 리뷰, 또는 사용자가 속도를 요구할 때. 깊은 계획 강요 금지.
  • normal — 범위가 한정된 코드/문서/설정 변경, 집중 디버깅. 파일이 바뀌면 관련 검증 1개 실행.
  • deep — 운영·인증·DB·마이그레이션·배포·광범위 리팩터·생성 산출물 등 고신뢰 작업. 완료 전 “종료 증거”를 먼저 정의.
  • blocked — 파괴적 범위·비밀 노출·되돌릴 수 없는 원격 작업·자격증명 필요·사용자 결정 필요. 멈추고 확인 요청.

실제 예시

발췌 1 — SKILL.md frontmatter + References (점진적 공개의 심장)

// /home/seunghyeong/harness-work/fable-ish/skills/fable-ish/SKILL.md
---
name: fable-ish
description: Apply fable-ish verification discipline to Claude Code coding tasks with risk-proportional workflow, review, and final reporting. Use for fable-ish requests, common typo fablish, complex implementation, debugging, refactoring, deployment preparation, or work where completion needs observable evidence. Do not use for simple explanations or quick low-risk answers unless explicitly requested.
---

# fable-ish

Use this skill as the workflow instruction layer for the fable-ish plugin.
The plugin hooks provide a mechanical verification gate (task classification,
evidence tracking, stop-time review); this skill provides the human-readable workflow.
Treat `fablish` as a common typo alias for `fable-ish`; do not rename the plugin, skill, or directory.

## Core Rule

Match verification depth to task risk.

- Quick tasks: answer directly and do not force deep planning.
- Normal coding tasks: inspect relevant context, make a coherent change, and run one relevant proof when files change.
- Deep tasks: define the work unit and observable exit proof before final response.
- Blocked tasks: stop when the next action needs user confirmation, credentials, external state, or unsafe destructive scope.

Do not claim verification that was not observed.

## References

Read only the reference needed for the current task:

- `references/workflow.md`: mode selection, work-unit loop, optional review passes.
- `references/verification.md`: choosing and reporting proof.
- `references/final-report.md`: concise final report format.

발췌 2 — 위험 비례 4모드 + 작업 루프 (workflow.md)

// /home/seunghyeong/harness-work/fable-ish/skills/fable-ish/references/workflow.md
## Mode Selection

- `quick`: simple explanation, direction check, low-risk review, or user asks for speed.
- `normal`: bounded code/docs/config changes, focused debugging, or ordinary implementation.
- `deep`: production, auth, database, migrations, deployment, broad refactor, generated artifacts, or high reliability work.
- `blocked`: destructive scope, secret exposure, irreversible remote action, missing credentials, or user decision required.

## Work Loop

For normal and deep tasks:

1. Inspect the relevant local context before editing.
2. Name the work unit as behavior, invariant, or artifact contract.
3. Choose an observable exit proof.
4. Implement the smallest coherent slice.
5. Run the narrowest relevant verification first.
6. Review likely failure scenarios.
7. Fix confirmed issues.
8. Stop only when proof passes or a concrete blocker remains.

발췌 3 — 검증 사다리 6단계 + baseline delta-zero (verification.md)

// /home/seunghyeong/harness-work/fable-ish/skills/fable-ish/references/verification.md
## Verification Ladder

Pick the lowest proof that actually covers the risk:

1. Static file/schema/manifest validation.
2. Focused unit or integration test.
3. Typecheck, lint, or build.
4. Runtime smoke check, curl, browser, or health endpoint.
5. Artifact rendering or consumer check.
6. CI, deployment, or production/internal URL check when that is the real boundary.

## Baseline Failures

If the baseline was already red, do not hide it.

- Record the failing command.
- Identify whether the new work changed the failure.
- Use `delta-zero` only when the failure is unrelated and unchanged.
- If you cannot distinguish baseline from new failure, report it as uncertain.

발췌 4 — 훅이 주입하는 additionalContext (스킬과 한 쌍)

# /home/seunghyeong/harness-work/fable-ish/scripts/classify_task.py
def context_for_mode(mode: str, risk_flags: list[str]) -> str:
    lines = [f"fable-ish task mode: {mode}."]
    if risk_flags:
        lines.append("Risk flags: " + ", ".join(risk_flags) + ".")
    if mode == "quick":
        lines.append("Keep the response concise; do not force deep planning or broad verification.")
    elif mode == "normal":
        lines.append("If files change, run one relevant verification command or state why none applies.")
    elif mode == "deep":
        lines.append("Define the exit proof before completion and verify changed behavior before final.")
    elif mode == "blocked":
        lines.append(
            "This request touches a sensitive or destructive boundary. Confirm scope, prefer the safest "
            "reversible action, and stop for user confirmation when the next step needs credentials, "
            "irreversible remote writes, or destructive deletes. Rely on Claude Code permissions for hard enforcement."
        )
    lines.append("Never claim verification that was not actually observed.")
    return "\n".join(lines[:10])

[!important] 짝 맞춤이 핵심 훅의 한 줄 문구(“Define the exit proof before completion…“)는 스킬 workflow.md의 작업 루프 3단계, verification.md의 사다리와 같은 어휘로 설계돼 있다. 훅은 모드를 판정해 짧게 찌르고, 스킬은 그 어휘를 풀어쓴 상세 절차를 제공한다 — 같은 규율의 기계어판과 사람어판.

직접 만들 때 — 최소 SKILL.md 골격

---
name: my-skill
description: <무엇을 적용하는지> Use for <트리거 키워드 나열>, common typo <오타별칭>. Do not use for <제외 조건> unless explicitly requested.
---

# my-skill

Use this skill as the workflow instruction layer for the <플러그인> plugin.
The plugin hooks provide a mechanical gate; this skill provides the human-readable workflow.

## Core Rule

<위험 비례 핵심 규칙 한 줄>.

- Quick: <가벼운 작업 행동>.
- Normal: <보통 작업 행동>.
- Deep: <고위험 작업 행동>.
- Blocked: <정지 조건>.

Do not claim verification that was not observed.

## References

Read only the reference needed for the current task:

- `references/workflow.md`: 모드 선택, 작업 루프, 리뷰.
- `references/verification.md`: 증거 선택과 보고.
- `references/final-report.md`: 최종 보고 형식.

만들 때 체크리스트

  • frontmatter name이 디렉터리명과 정확히 일치하는가.
  • description에 (1)트리거 키워드 (2)오타/별칭 (3)제외 조건이 모두 들어갔는가.
  • SKILL.md 본문이 “훅=기계 게이트 / 스킬=사람 워크플로우” 역할 분담을 명시했는가.
  • 상세 절차를 SKILL.md에 다 적지 않고 references/로 분리했는가(점진적 공개).
  • ## References에 “필요한 것만 읽어라(Read only the reference needed)” 지시가 있는가.
  • 훅의 context_for_mode() 문구와 스킬 references의 어휘가 같은 단어를 쓰는가(짝 맞춤).
  • verification.md에 “낮은 단부터 위험을 덮는 사다리”와 baseline delta-zero 규칙이 있는가.
  • 모든 파일에 “관찰 안 한 검증을 통과라 말하지 마라” 원칙이 반복되는가.
  • 플러그인 이름·디렉터리 변경 금지 + 오타 별칭 유지 경고가 있는가.

요약 & 셀프체크

3줄 요약

  1. 스킬 계층은 모델이 직접 읽는 마크다운 매뉴얼로, 코드로는 못 적는 “판단 규율”(어떤 검증이 위험을 덮나, baseline 실패와 새 실패를 어떻게 구분하나)을 글로 적어 모델에게 위임한다.
  2. 점진적 공개: 목차격인 SKILL.md만 항상 올리고, 상세 챕터 3개는 references/에 두어 그 작업에 필요할 때만 모델이 Read로 펼친다(토큰 절약).
  3. 훅(모드 판정·종료 차단)과 스킬(상세 절차)은 같은 어휘를 공유하는 한 쌍이며, Stop 게이트가 종료를 막으면 모델은 스킬의 검증 사다리를 보고 다음 검증을 고른다.

스스로 답해보기

  • quick 작업인데 references/ 3개를 모두 읽으면 무엇이 잘못되나? (힌트: 점진적 공개의 목적)
  • 훅이 “Define the exit proof before completion”이라고 찔렀을 때, 모델은 어느 파일의 어떤 절차를 펼쳐 이를 실행하나?
  • description에서 “제외 조건”을 빼면 어떤 상황에서 스킬이 잘못 켜지나?

연결

FB_개요 · _분석축_루브릭 · FB_40_task-classification-engine(훅이 모드를 정하는 분류기) · FB_30_context-injection-via-additionalContext(훅이 한 줄을 찔러 넣는 경로) · FB_70_stop-completion-gate(증거 없으면 종료를 막는 게이트) · FB_50_evidence-ledger-state(증거 장부)

[!tip] Codex 교차검증 보존 이 노트의 핵심 사실관계(스킬=모델이 읽는 마크다운 지침 계층, 훅=기계적 게이트라는 역할 분담 / SKILL.md frontmatter의 name·description 2필드 / description에 인코딩된 트리거·오타별칭(fablish)·제외 조건 / references/ 3분할에 의한 점진적 공개와 “필요한 것만 읽어라” 지시 / 위험 비례 quick·normal·deep·blocked 4모드 / verification.md의 6단계 검증 사다리와 baseline delta-zero 규칙 / 훅 context_for_mode()의 주입 문구와 스킬 references 어휘의 짝 맞춤 / “관찰하지 않은 검증을 통과라 주장 금지” 원칙)는 위 발췌 소스 파일들에 대한 직접 대조로 확인되었다. 단, 위 발췌·근거에 표기된 경로(/home/seunghyeong/harness-work/fable-ish/...)는 원본 fable-ish 플러그인 기준이며, 동일 머신의 후속 포크는 harness-fablize/skills/fablize/로 이름·구조가 진화해 있다(예: references 3분할 대신 번호 섹션 통합). 이 노트는 원본 fable-ish 설계를 문서화한 것이므로 원본 경로·발췌를 그대로 보존했다.