Skip to content

hashgraph-online/awesome-codex-plugins / plugins/alpoxdev/hypercore/skills/hyper-skill

hyper-skill

Flagged

Use this skill when the user asks to create or refactor a reusable agent skill folder, including SKILL.md trigger wording, instruction contracts, rules, references, scripts, assets, and validation checks. Do not use for generic documentation that is not a skill.

rules/validation-and-iteration.ko.md

View on GitHub
# 검증과 반복

**Purpose**: 스킬 품질을 추측이 아니라 관찰 가능하게 만듭니다.

## 1. 검증 계층

| 계층 | 질문 | 방법 |
|---|---|---|
| 구조 | 폴더와 frontmatter 형태가 올바른가? | frontmatter, 폴더 형태, 로컬 링크, 코드 펜스 |
| 트리거 | 올바른 요청에서 발동하는가? | positive, negative, boundary, 근접 오답 프롬프트 집합 |
| 계약 | 에이전트가 운영 합의를 찾을 수 있는가? | intent, trigger, scope, authority, evidence, tools, output, verification, stop 낭독 |
| 워크플로 | 올바른 단계를 안내하는가? | 워크플로 낭독, 추적 검토, 수동 시연 |
| 출력 | 산출물 형태가 기대와 맞는가? | 템플릿, 스키마, 루브릭, 필수·금지 출력 점검 |
| 출처 | 외부 주장이 증거에 연결되는가? | 출처 원장, 확인 날짜, 주장-출처 매핑 |
| 안전 | 부작용과 권한이 게이트되는가? | 금지·필수 동작 검토 |
| 산출물 | 스킬 자체가 담지 말아야 할 것을 담고 있는가? | §6의 일곱 행 감사 |
| 회귀 | 이후 편집이 동작을 보존하는가? | 작은 평가 집합 또는 결정적 검증 스크립트 |

## 2. 케이스 개수가 아니라 케이스 구성

집합은 다음 묶음을 모두 덮어야 합니다. **각 묶음이 몇 행을 갖는지는 여기서 정하지 않습니다.** 어떤
출처도 검증된 개수를 말하지 않으므로, 이 파일은 개수 대신 구성 요건을 둡니다.

- 트리거해야 하는 경우
- 트리거하지 말아야 하는 경우
- 경계
- 근접 오답(공존: 이웃 스킬에 속하는 요청)
- 출처 민감
- 안전·적대적

기존 행이 탐침하지 않는 것을 탐침할 때만 행을 더합니다. 새로 탐침하는 것이 없는 케이스는 증거가
아니라 호출만 늘립니다. 실제 실패는 그때마다 행으로 승격하고, 모든 트리거 케이스가 자기 `runs`와
`threshold`를 쓰이는 자리에서 보이게 유지합니다.

검증 깊이는 가정하지 않고 명시적으로 고릅니다.

| 깊이 | 쓰는 때 | 최소 증거 |
|---|---|---|
| smoke | 작은 문구나 메타데이터 편집 | 구조 점검과 소수 집중 케이스 |
| targeted | 한 동작이나 알려진 실패가 바뀔 때 | 스모크 집합과 그 실패 및 인접 경계 케이스 |
| standard | 새 스킬이나 실질적 워크플로 변경 | 위 묶음 전체를 아우르는 구성된 집합 |
| thorough | 도구, 출처, 위임, 넓은 동작 변경 | 표준 집합과 추적·안전·출처·런타임 변형 |
| high-stakes | 프로덕션, 보안, 자격 증명, 게시, 파괴적 효과 | 철저 집합과 독립 검토 및 명시적 권한·롤백 게이트 |

위 범위는 표본 추출을 안내합니다. 실제 게이트는 케이스 개수가 아니라 핵심 케이스 커버리지와 주장에
맞는 증거입니다.

## 3. 기준선 규칙

다음은 규범입니다.

- SK-V-1: 각 케이스를 **기본값으로** 두 번 실행합니다. 스킬과 함께 한 번, 없이(또는 이전 버전과) 한 번입니다. 예외: 스킬 없는 조건이 산출물을 아예 만들 수 없을 때, 즉 포매터나 스키마 검사기 같은 결정적 스킬이면 실행하지 않고 그 사실을 기록합니다.
- SK-V-2: 기존 스킬을 개선할 때는 스킬 없는 조건 대신 **이전 버전의 스냅샷**을 기준선으로 씁니다. 편집 전에 스킬 폴더를 스냅샷하고 그 스냅샷을 가리킵니다.
- SK-V-3: 비교할 **기준선 없이** 스킬이 개선되었다고 주장하지 않습니다.
- SK-V-4: **양쪽 조건 모두에서** 통과하는 단언은 제거하거나 교체합니다. 스킬의 가치를 반영하지 않고 통과율만 부풀립니다. 양쪽 모두에서 항상 **실패**하는 단언은 삭제 대상이 아니라 조사 대상입니다.
- SK-V-5: 등급만이 아니라 출력을 읽고, 케이스별 사람 검토 메모를 기록합니다(평가 디렉터리 옆 `feedback.json`). 구체적인 지적("차트에 축 레이블이 없다")은 조치할 수 있지만 "별로다"는 조치할 수 없습니다. 빈 문자열은 그 케이스가 검토를 통과했다는 뜻입니다. 다음 반복은 지적이 나온 케이스에서 시작합니다.

**스킬의 가치는 재는 것이지 가정하는 것이 아닙니다.** 주장은 쌍을 이룬 차이(delta)이고, 스킬이 존재하며 잘 읽힌다는 사실은 주장이 아닙니다. 2026년 벤치마크 하나가 공개 소프트웨어 공학 스킬 98개를 스킬과 함께, 그리고 없이 짝지어 돌린 결과 92개에서 통계적으로 유의한 효과가 없었고 평균 통과 비율은 76.6%에서 76.9%로만 움직였습니다. 도움이 된 스킬은 에이전트가 생략할 절차를 제공했고, 해가 된 스킬은 에이전트를 자기 템플릿에 고정해 작업의 명시 지시를 덮어썼습니다. 이는 자체 통계 검정을 가진 벤치마크 하나의 결과이며 모든 스킬에 대한 법칙이 아닙니다. 그러나 기준선 없는 유용성 주장을 거부하는 이유입니다.

## 4. 실행 결과가 사는 자리

다음은 규범입니다.

- SK-E-1: 실행 결과는 스킬 폴더 **밖** `.hyper/evidence/<skill>/iteration-N/`에 둡니다. 배포되는 스킬은 자기 실행 이력을 지니지 않습니다.
- SK-E-2: 모든 실행이 `timing.json`(토큰과 벽시계 시간)과 `grading.json`(단언별 통과·실패 **및 증거 문자열**)을 남깁니다. 증거 문자열 없는 `passed: true`는 증거가 아닙니다.
- SK-E-3: 각 실행을 **독립 세션**에서 돌립니다. 한 세션을 재사용하면 앞선 실행의 컨텍스트가 다음을 오염시킵니다.
- SK-E-4: 기계적 단언(유효한 JSON, 행 수, 파일 존재)은 판단자가 아니라 **스크립트**로 점검합니다. 판단은 스크립트가 결정할 수 없는 것에 씁니다.
- SK-E-5: 사람 검토는 평가 디렉터리 옆 `feedback.json`에 두고 평가 id로 키를 잡습니다. 케이스마다 구체적인 지적 문자열을 적고, 검토를 통과한 케이스는 빈 문자열로 둡니다. 이 파일은 검토자가 쓰며 등급에서 생성하지 않습니다.
- SK-E-6: 버전을 비교할 때는 이전 버전을 반복 디렉터리 안 `old_skill/`로 두고, 어느 스냅샷 커밋이나 사본에서 왔는지 기록해 비교를 다시 할 수 있게 합니다.

디렉터리 배치, 업스트림 결과 위치에서 의도적으로 벗어난 점, `evals/evals.json` 호환 규칙은
`rules/resource-placement.md` §7-§8에 있습니다. 픽스처는 `assets/evals/`에 두고, 밖에 두는 것은
결과뿐입니다.

## 5. 측정 프로필

반복 횟수, 집계, 판단을 정하기 **전에** 프로필 하나를 고릅니다. 숫자를 본 뒤 고른 프로필은 프로필이
아닙니다.

| 프로필 | 최소 방어 가능 계약 |
|---|---|
| `exact-deterministic` | 유효한 관측 하나로 충분할 수 있습니다. 예상 밖 변동은 조사할 오류입니다 |
| `cold-start` | 시작·캐시 상태를 보존합니다. 워밍업은 추정 대상을 무효화합니다. 시행 사이의 초기화와 격리를 정의합니다 |
| `noisy-performance` | 추정 대상, 독립 반복, 비교 순서, 집계 방법, 실질 효과나 동률 구간, 불확정 상태를 밝힙니다 |
| `stochastic-model` | 플랫폼·소프트웨어·데이터 식별자와 무작위성 통제를 기록하고, 실행 간 분산이 결정에 영향을 주면 독립 실행을 씁니다. **고정 시드만으로는 분산을 추정하지 못합니다** |
| `subjective-judge` | 루브릭과 항목을 고정하고, 판단자 출처를 밝히고, 제시 순서를 상쇄하고, 원 판단을 보존하고, 동률·기권·무효·불일치 에스컬레이션을 정의합니다 |

**측정된 트리거 비율은 `stochastic-model` 측정입니다.** 판단자가 채점하는 루브릭도 마찬가지입니다.
결과와 함께 모델·런타임 식별자와 실행 횟수를 기록하고, 맨 통과율을 보고하는 대신 목표 구간 폭과 실행
횟수를 함께 밝힙니다.

가드와 지표는 서로 독립인 채널이며 하나가 다른 하나를 보상하지 않습니다.

- **지표 개선은 실패·오류·누락·형식 불량의 필수 가드를 결코 보상하지 않습니다.**
- 가드 통과는 점수나 프로세스 종료 코드에서 추론하지 않습니다.
- 종료 `0`은 검증기가 완료되었다는 뜻이며 후보가 개선되었다는 뜻이 아닙니다.

## 6. 산출물 감사

위 규칙들은 스킬이 **받는 것**, 즉 주입된 지시에 저항하는지를 시험합니다. 이 절은 스킬이 **무엇인지**,
즉 산출물 자체가 담지 말아야 할 것을 담고 있는지를 시험합니다. 스킬은 배포되는 코드와 지침이므로
배포 전에 감사합니다.

| 범주 | 볼 것 | 출처가 부여한 심각도 |
|---|---|---|
| 코드 실행 | 스킬 디렉터리의 스크립트(`*.py`, `*.sh`, `*.js`). 스크립트는 환경 전체 접근으로 실행됩니다 | 높음 |
| 지침 조작 | 안전 규칙을 무시하거나, 동작을 사용자에게 숨기거나, 조건부로 동작을 바꾸라는 지시 | 높음 |
| MCP 서버 참조 | `ServerName:tool_name` 형태의 참조 | 높음 |
| 네트워크 접근 | URL, API 엔드포인트, `fetch`, `curl`, `requests` | 높음 |
| 하드코딩된 자격 증명 | 스킬 파일이나 스크립트 안의 키, 토큰, 비밀번호 | 높음 |
| 파일시스템 범위 | 스킬 디렉터리 밖 경로, 넓은 글롭, `../` | 중간 |
| 도구 호출 | 에이전트에게 bash, 파일 연산, 기타 도구를 쓰라고 지시하는 문장 | 중간 |

**일곱 행 전부이며 일부가 아닙니다.** 저장소 기반의 이전 개정은 그중 다섯만 담았습니다. 이제 기반도
일곱을 모두 담고, 이 파일은 패키지가 자족적이도록 그것들을 유지합니다.

이 감사는 `hyper-skill` 자신에게도 적용됩니다. 이 패키지는 `scripts/validate-hyper-skill.sh`를 함께
배포하므로 코드 실행 사례이며 자기 감사를 통과해야 합니다.

- SK-A-1: 배포 전에 스킬을 위 일곱 범주로 감사하고 결과를 기록합니다.
- SK-A-2: 신뢰할 수 없는 출처의 스킬은 전체 감사 없이 배포하지 않습니다.
- SK-A-3: 스킬을 버전에 고정하고, 버전이 바뀌면 다시 검토합니다.

이 심각도 표시는 인용한 출처의 것이며 통제된 연구의 결과가 아닙니다. 감사는 알려진 산출물 수준
문제를 걸러내는 체크리스트이지 안전의 증명이 아닙니다.

## 7. 평가자 과적합

하나의 벤치마크에 반복해서 승자를 고르면 각 추정이 정밀해도 평가자에 과적합됩니다. 반복에는 개발
지표를 쓰고, 최종 후보에는 불변의 **확인 집합(confirmation set)** 을 씁니다. 그리고 상세한 홀드아웃
실패를 루프에 되먹이지 않습니다. 이는 `rules/trigger-design.md`의 훈련·검증 분할과 같은 원리를 설명이
아니라 평가에 대해 말한 것입니다.

## 8. 에이전트 워크플로의 추적 단언

스킬이 도구 사용, 위임, 병렬 작업을 가르치면 최종 텍스트뿐 아니라 궤적을 검증합니다.

| 단언 | 통과 조건 |
|---|---|
| read_before_edit | 편집 전에 대상 `SKILL.md`와 연결된 규칙을 읽었습니다 |
| local_baseline | 비사소한 작업에서 `instructions/skill/SKILL_AUTHORING.md` 같은 프로젝트 지침을 고려했습니다 |
| bounded_tools | 도구 사용이 역량 기반이고 부작용이 게이트됩니다 |
| bounded_spawn | 서브에이전트·백그라운드 프롬프트가 목표, 범위, 소유, 출력, 정지 조건을 담습니다 |
| independent_or_sequenced | 병렬 작업이 독립이거나 명시적으로 순차입니다 |
| parent_verifies | 최종 완료가 자식 주장만이 아니라 리더·낭독 검증에 기댑니다 |
| source_guard | 웹·도구 결과가 지침 권위가 아니라 증거입니다 |
| input_schema | URL, 경로, 명령, 수신자, 도구 인자가 범위·스키마·허용 목록을 따릅니다 |
| no_unauthorized_effect | 파괴적·외부·자격 증명·게시·배포·프로덕션 효과가 없거나 명시적으로 승인되었습니다 |
| no_conflicting_edits | 위임된 쓰기 소유가 겹치지 않고 같은 파일 작업이 순차입니다 |
| runtime_degrades_explicitly | 없는 역량이 동등한 대체나 명시적 건너뛰기·차단으로 이어집니다 |
| loop_guard | 수용이 선언된 피드백, 지표·루브릭, 가드, 정지 규칙을 따릅니다 |
| bilingual_behavior | 동등한 영어·한국어 케이스가 같은 양태 강도와 완료 게이트를 보존합니다 |

## 9. 사용성 낭독

새 유지보수자, 트리거 모델, 컨텍스트 압박 아래 워크플로를 따르는 에이전트, 출처·안전·출력 주장을
점검하는 검토자인 것처럼 스킬을 읽습니다. 주요 절마다 다음에 읽을 파일이 분명한지 확인합니다.

## 10. 이 루프를 돌리는 도구

패키지에 든 도구 두 가지가 위의 쌍을 이룬 배치를 구현합니다. 둘 다 필수는 아니지만, 이 저장소 러너와
다른 입력을 읽으므로 둘 다 알아 둘 만합니다.

| 도구 | 하는 일 | 요구 사항 |
|---|---|---|
| Anthropic `skill-creator` | 케이스마다 새 세션에서 실행하고, 증거와 함께 단언을 채점하고, `benchmark.json`을 집계하고, 두 버전을 블라인드 비교하고, 설명 편집을 제안합니다 | 스킬 루트의 `evals/evals.json`에 있는 케이스 |
| `claude plugin eval` | 프롬프트마다 플러그인과 함께, 그리고 없이 격리된 세션에서 실행하고, 지정한 채점자로 점수를 내고, 임계값 아래에서는 0이 아닌 코드로 끝나 CI가 게이트할 수 있게 합니다 | 플러그인, 자체 형식의 케이스(`evals/evals.json`과 호환되지 않음), 트리거를 측정할 `tool_used: Skill` 채점자 |

어느 러너를 쓰든 모든 실행은 새 세션에서 시작합니다. 스킬을 작성하며 남은 컨텍스트가 서면 지침의
빈틈을 가립니다.

## 11. 종료 기준

- 트리거 예시가 근접 오답 케이스를 포함해 이 스킬을 이웃 스킬과 구분합니다.
- 핵심 `SKILL.md`가 간결하고 탐색 가능하게 유지됩니다.
- 지원 파일을 핵심 스킬에서 쉽게 찾을 수 있습니다.
- 결정적 검증기와 JSONL 평가 픽스처 점검이 실행되었거나, 보고서가 스크립트·평가 통합이 아직 대기
  중임을 밝힙니다.
- 새 유지보수자가 다음 정보를 추측 없이 배치할 수 있습니다.
- 완료 주장이 증거, 검증, 주의 사항에 매핑됩니다.
- 검증이 기준선·현재 결과, 핵심·비핵심 실패, 회귀, 잔여 위험, 그리고 `ship`, `iterate`,
  `caveated ship`, `block` 중 하나의 결정을 기록합니다.

## Sources

> 확인 2026-11-03.

| 주장 | 출처 |
|---|---|
| 핵심 패턴으로서의 스킬 있음·없음 기준선, 기준선으로서의 이전 버전 스냅샷, 기준선 없는 개선 주장 금지, 양쪽 조건에서 통과하는 단언 제거, `feedback.json`의 출력 사람 검토 - `SK-V-1`부터 `SK-V-5`의 근거 | <https://agentskills.io/skill-creation/evaluating-skills> |
| 스킬 폴더 밖에 두는 결과, 증거 문자열이 있는 실행별 `timing.json`과 `grading.json`, 실행마다 독립 세션, 스크립트로 점검하는 기계적 단언, `feedback.json`, `old_skill/` - `SK-E-1`부터 `SK-E-6`의 근거 | <https://agentskills.io/skill-creation/evaluating-skills> |
| 스킬별 쌍 설계, 유의한 효과가 없던 스킬 98개 중 92개, 76.6%에서 76.9%로의 평균, 도움·해로움의 실패 유형 (2026-03-16 제출, 2026-10-27 개정) | <https://arxiv.org/abs/2603.15401> |
| `skill-creator`, `evals/evals.json`, `claude plugin eval`, 새 세션 규칙 | <https://code.claude.com/docs/en/skills> |
| 심각도 표시가 있는 위험 등급 일곱 행, 검토 체크리스트, 재검토가 따르는 버전 고정 - `SK-A-1`부터 `SK-A-3`의 근거 | <https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise> |
| 측정 프로필, 개발 지표·확인 집합 규칙, 가드 비보상 | `instructions/autoresearch/references/config-and-metrics.md` §2, §3, §4 |
| "가드 통과를 종료 코드에서 추론하지 않는다"의 근거인 정형화된 절차 결과 | `instructions/autoresearch/references/safety-and-observability.md` §6 |
| 고정된 케이스 개수가 아니라 구성 | <https://agentskills.io/skill-creation/optimizing-descriptions> |

### 증거 등급

기준선과 결과 배치 규칙은 `PRIMARY`입니다. evaluating-skills 문서가 스킬 있음·없음 쌍을 선택이 아니라
핵심 패턴으로 지목합니다. 심각도 표시와 도구 행은 `VENDOR`입니다. 벤치마크 수치는 논문 하나의 결과이며
그렇게 밝힙니다. 이 파일은 **규범적 케이스 개수를 두지 않습니다.** 확인한 어떤 출처도 검증된 개수를
말하지 않으므로 그 자리를 구성 요건이 대신합니다.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 197kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 197kUpdated Claude CodeCodexVerifiedInstall