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/resource-placement.ko.md

View on GitHub
# 자원 배치

**Purpose**: 스킬 내용의 각 조각을 그 책임에 맞는 파일 유형에 둡니다.

## 1. 배치 행렬

| 내용 | 자리 | 이유 |
|---|---|---|
| 스킬을 언제 쓰는지 | `description`, 라우팅 규칙 | 발견과 트리거 신호 |
| 직업, 경계, 상위 워크플로, 정지 조건 | `SKILL.md` | 활성화 후 항상 필요 |
| 재사용 정책과 반복되는 판단 | `rules/` | 실행 전반에 적용 |
| 공식 문서, 스키마, 도메인 세부, 긴 예시 | `references/` | 필요할 때만 로드 |
| 결정적 검증이나 변환 | `scripts/` | 산문보다 신뢰할 수 있음 |
| 템플릿, 재사용 평가 픽스처, 정적 출력 자원 | `assets/` 또는 `assets/evals/` | 복사·채움·출력 삽입되거나 검증기가 재사용 |
| 런타임 메타데이터 | `agents/` | 플랫폼별 표시, 호출 정책, 의존성(예: Codex `agents/openai.yaml`)이며 런타임이 소비할 때만 |

## 2. 판단 순서

순서대로 묻습니다.

1. 핵심 정체성, 트리거, 경계, 정지 조건인가?
2. 재사용 정책이나 반복되는 판단 안내인가?
3. 필요할 때만 로드하는 상세 지식인가?
4. 결정적 실행이 더 나은가?
5. 추론 컨텍스트가 아니라 출력 자원인가?
6. 런타임이나 UI가 소비하는 플랫폼 메타데이터인가?

## 3. 규칙과 참조

`rules/`는 판단에 씁니다.

- 언제 스크립트를 더하는지
- 언제 결정적 검증기를 `scripts/`에 두는지
- 트리거 예시를 어떻게 검증하는지
- 출처 민감 주장을 어떻게 다루는지
- 핵심과 참조를 어떻게 나누는지

`references/`는 지식에 씁니다.

- 공식 문서 요약
- API 스키마
- 긴 예시
- 제공자별 경계 사례
- 도메인 용어집

## 4. 스크립트

다음 중 하나라도 참일 때만 스크립트를 더합니다.

- 같은 검사나 변환이 자주 반복됨
- 명령 순서가 깨지기 쉬움
- 기계 판독 가능한 출력이 필요함
- 실패 메시지가 에이전트의 자기 수정에 도움
- 버전 고정이나 매개변수 정규화가 신뢰성을 높임

모든 스크립트에 목적, 사용법, 의존성, 기대 출력, 실패 동작을 적습니다.

결정적 검증기는 `scripts/`에 둡니다. `hyper-skill`의 검증기는 `scripts/validate-hyper-skill.sh`에
속하며, 네트워크, 자격 증명, 커밋, 제품 파일 변경 없이 저장소 로컬 파일과 평가 픽스처를 소비해야
합니다.

번들 스크립트는 bash로 실행합니다. 규칙은 런타임 하나, 확장자 하나입니다. 패키지의 `scripts/`
디렉터리에 있는 디렉터리가 아닌 모든 엔트리는 `.sh` 파일이고, `.sh` 스크립트의 첫 줄은
`#!/usr/bin/env bash`입니다.

- `scripts/` 아래에 `.mjs`, `.py`, `.cjs`, `.js`, `.rb`, 확장자 없는 실행 파일을 두지 않습니다. 그 디렉터리에 `.sh`가 아닌 파일이 있으면 스타일 문제가 아니라 검증 오류입니다.
- 스크립트에서 셸을 다시 호출하지 않습니다. 값을 인용한 인자로 넘기고, 사용자 입력을 셸이 다시 해석하는 명령줄에 보간하지 않습니다.
- 다른 런타임이 아니라 bash인 이유: 이 스크립트를 실행하는 하네스에는 POSIX 셸이 이미 있습니다(macOS `/bin/bash` 3.2, Linux bash 4/5). 따라서 bash 스크립트는 런타임을 따로 설치할 필요가 없습니다. 연관 배열, `mapfile`·`readarray`, `${var,,}`·`${var^^}`, nameref, `wait -n`을 쓰지 않고 bash 3.2 기능 안에 머물며 POSIX 유틸리티와 JSON용 `jq`만 쓰면, 같은 파일이 두 플랫폼에서 실행됩니다.
- 소비자에게 필요한 것을 알립니다. 패키지가 스크립트를 포함하면 요구 셸과 외부 도구(예: bash 3.2+와 jq)를 `compatibility` frontmatter에 적어, 독자가 실행 전에 알 수 있게 합니다.
- 결정적 검증기가 확장자 규칙과 bash shebang을 강제하므로, 이를 어긴 번들 스크립트는 배포되지 않고 검증에서 실패합니다. 읽을 수 없는 `scripts/` 디렉터리도 오류입니다. 그곳에서는 규칙을 확인할 수 없기 때문입니다.

## 5. 자산

자산은 출력 생성을 돕는 파일에 씁니다.

- 보고서 템플릿
- 프롬프트 템플릿
- JSON 스키마
- 재사용 평가 픽스처, 특히 `assets/evals/` 아래 JSONL 케이스
- 복사하거나 채우는 예시

추론 전용 문서에는 자산을 쓰지 않습니다.

## 6. 공식 참조 배치

긴 공식 문서 증거를 핵심에 넣지 않습니다. 밖으로 나눕니다.

```text
references/
└── official/
    ├── agent-skills-standard.md
    ├── openai.md
    └── anthropic.md
```

각 파일은 확인 날짜, 출처 URL, 이 스킬에 영향을 주는 주장, 변동 주의 사항, 그리고 핵심 규칙으로
승격된 요약을 담습니다.

**`references/official/agent-skills-standard.md`가 공개 표준 스냅샷의 정본 파일 이름입니다.** 표준은
frontmatter 제약과 공개 예산의 일차 출처입니다. 그러므로 표준을 인용하는 패키지는 그것을 벤더 파일에
합쳐 넣지 않고 그 이름으로 함께 지녀야 합니다.

## 7. 평가 자원 배치

평가 자료를 "읽는 설명"과 "실행하거나 비교하는 픽스처"로 나눕니다.

```text
assets/
└── evals/
    ├── trigger-cases.jsonl
    └── workflow-cases.jsonl

references/
└── eval-rubric.md
```

- `assets/evals/*.jsonl`은 파서나 러너가 읽는 기계 판독 케이스를 담습니다.
- `references/eval-rubric.md`는 사람이 읽는 채점 기준과 주의 사항을 담습니다.
- 결정적 러너가 있으면 `scripts/run-evals.*`에 두고 의존성과 기대 출력을 문서화합니다.
- 평가 케이스가 외부 출처를 요구하면 출처 URL, 접근 날짜, 신선도 주의를 케이스 안이나 출처 원장에 적습니다.

**패키지된 평가 도구와의 호환.** `assets/evals/`는 이 저장소의 관례이며 어떤 패키지 도구도 읽지
않습니다. Anthropic의 `skill-creator`는 스킬 루트의 `evals/evals.json`을 읽고, 그 항목은 프롬프트, 입력
파일, 기대 동작, 단언을 담습니다. Claude Code의 `claude plugin eval`은 자체 케이스 형식을 쓰며,
제공자는 두 형식이 **서로 바꿀 수 없다**고 밝힙니다. 그래서 `assets/evals/`는 이 저장소 러너가 읽는
집합으로 유지합니다. 스킬을 그 도구들로도 평가하면 그 도구의 파일을 **추가하고** `assets/evals/`와
동기화하거나, 스크립트로 `assets/evals/`에서 생성합니다. 서로 어긋난 평가 집합 둘은 정본 집합 하나보다
나쁩니다.

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

위 픽스처는 입력입니다. 그것을 돌린 **결과**는 스킬 폴더 밖에 삽니다.

다음은 규범입니다.

- 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/`로 두고 어느 스냅샷 커밋이나 사본에서 왔는지 기록해, 비교를 다시 돌릴 수 있게 합니다.

배치:

```text
.hyper/evidence/<skill>/iteration-N/
├── benchmark.json
├── feedback.json
└── eval-<case>/
    ├── with_skill/
    │   ├── outputs/
    │   ├── timing.json
    │   └── grading.json
    └── without_skill/
        ├── outputs/
        ├── timing.json
        └── grading.json
```

기준선이 "스킬 없음"이 아니라 이전 버전이면 `without_skill/`을 `old_skill/`로 바꾸고 실행이 가리킨
스냅샷을 함께 남깁니다.

**업스트림의 결과 위치는 다르며 그 차이는 의도적입니다.** 출처는 결과를 스킬 폴더 옆 워크스페이스에
둡니다. 이 저장소에는 이미 평가 자료 배치가 둘로 갈려 있었고, 세 번째를 더하면 단일 답이 사라집니다.
증거 디렉터리에는 이 저장소의 선례가 있습니다. 맞바꿈은 실재합니다. 결과가 배포 스킬과 함께 다니지
않으므로 이 저장소 밖의 독자는 볼 수 없습니다. 파일 이름은 출처에서 왔고, 위치만 이 저장소의
선택입니다.

## 8a. 변동성 있는 값 배치

스킬 이름, 설명, 호출된 `SKILL.md`를 매 세션에 두는 런타임은 그 텍스트를 재사용되는 프롬프트 접두사의
일부로 만듭니다. 그것을 편집하면 그 파일을 로드하는 모든 세션의 캐시 재사용이 무효가 됩니다.

- 로드되는 머리는 안정적으로 유지합니다. `name`, `description`, `SKILL.md` 상단은 갱신할 때마다가
  아니라 의도적으로 묶어서 편집합니다.
- 변동성 있는 값("마지막 확인" 날짜, 버전 고정, 개수, 머신 경로)은 파일 하단이나 `references/`로
  옮깁니다. 그러면 날짜를 갱신할 때 머리가 아니라 꼬리를 건드립니다.
- 길이만이 아니라 안정성으로 나눕니다. 안정된 계약 텍스트는 `SKILL.md`에, 빠르게 바뀌는 제공자 상세는
  `references/`에 둡니다.
- 번들 파일은 안정된 이름 아래 안정된 순서로 나열합니다.

이 규칙이 정확성보다 앞서지는 않습니다. 잘못된 머리는 캐시 비용과 무관하게 고칩니다.

## 9. 설치 신뢰와 출처

스킬이 어디서 왔는지는 그것이 무엇인지의 일부입니다.

- 프로젝트 범위 스킬 디렉터리는 그 자체로 **신뢰 경계가 아닙니다.** 문서화된 런타임은 프로젝트 스킬을
  명시적 신뢰 단계 뒤에 두고, 스캔에 실패한 스킬을 격리합니다.
- 디렉터리 위치에 기대지 말고 설치 출처(출처 식별자, 내용 해시, 스캐너 결과)를 기록합니다.
- 서드파티 스킬과 함께 넣은 스크립트는 프롬프트 조각이 아니라 **코드 검토** 대상입니다.
- 동적 셸 보간보다 입력이 명시된 스크립트를 선호하고, 스킬 파일·예시·스크립트에 자격 증명을 넣지
  않습니다.
- 변경 가능한 상태를 설치 트리에 쓰지 않습니다.

## 10. 금지 패턴

- `SKILL.md`가 참조 지식 기반이 되는 것
- `references/` 파일이 여러 단계 참조를 다시 요구하는 것
- `SKILL.md`에 사용 조건을 밝히지 않고 스크립트를 만드는 것
- 실제 워크플로에 연결되지 않은 자산
- 공식 문서를 길게 그대로 옮기는 것
- 평가 픽스처를 다시 돌릴 수 없는 산문 체크리스트로 남기는 것
- 안전 경계를 도구 게이트에 연결하지 않고 최종 답변 어조 규칙으로만 쓰는 것
- 배포되는 스킬 폴더 안에 실행 결과를 커밋하는 것
- 서로 어긋난 평가 집합 둘(`assets/evals/`와 패키지 도구의 케이스 파일)
- `SKILL.md`의 로드되는 머리에 변동성 있는 날짜, 개수, 버전 고정을 두는 것

## 11. 완료 기준

- [ ] 모든 지원 파일에 배치 이유가 있습니다.
- [ ] 모든 지원 파일을 `SKILL.md`나 직접 연결된 규칙에서 찾을 수 있습니다.
- [ ] 스크립트·자산에 사용법과 검증 기록이 있습니다.
- [ ] 결정적 검증기는 `scripts/`에, 재사용 평가 픽스처는 `assets/evals/`에 있습니다.
- [ ] 제공자 민감 내용이 참조로 격리되어 있습니다.
- [ ] 핵심 트리거 로직이 참조에 숨지 않았습니다.
- [ ] 표준 스냅샷이 `references/official/agent-skills-standard.md`에 존재합니다.
- [ ] 평가 실행 결과가 스킬 폴더 밖에, 실행별 시간·채점·사람 피드백 기록과 함께 쓰입니다.
- [ ] `skill-creator`나 `claude plugin eval`로도 평가하는 스킬이면 그 도구의 케이스 파일이 있고 이 저장소 러너가 읽는 픽스처와 일치합니다.
- [ ] 변동성 있는 값이 `SKILL.md`의 로드되는 머리 밖에 있습니다.

## Sources

> 확인 2026-11-03.

| 주장 | 출처 |
|---|---|
| 스킬 폴더 밖에 두는 실행 결과, 증거 문자열이 있는 실행별 `timing.json`과 `grading.json`, 실행마다 독립 세션, 스크립트로 점검하는 기계적 단언, `feedback.json`의 사람 검토, 이전 버전 갈래로서의 `old_skill/` - `SK-E-1`부터 `SK-E-6`의 근거 | <https://agentskills.io/skill-creation/evaluating-skills> |
| 형제 워크스페이스 결과 배치, 그리고 이 저장소가 의도적으로 갈라서는 지점 | <https://agentskills.io/skill-creation/evaluating-skills> |
| `skill-creator` 입력으로서의 `evals/evals.json`, 그리고 `claude plugin eval` 형식이 그것과 호환되지 않는 별도 형식이라는 점 | <https://code.claude.com/docs/en/skills> |
| 로드되는 머리를 안정적으로 유지하고 변동성 있는 값을 그 밖으로 옮기기 | `instructions/cache/CACHE.md` §3 |
| `references/official/` 관례와 파일별 내용 | `instructions/skill/references/resource-placement.md` §5 |
| 프로젝트 스킬 신뢰 게이트, 스캔 격리, 기록되는 설치 출처 | <https://github.com/alpoxdev/hypercore/blob/01be78de5973eb75a616e5156058621a6fabbc97/instructions/cli/hermes-agent/SKILLS.md> |
| 읽기 전용으로 등록되고 이름 공간이 붙으며 설치 트리에 쓰지 않는 스킬 | <https://github.com/alpoxdev/hypercore/blob/01be78de5973eb75a616e5156058621a6fabbc97/instructions/cli/hermes-agent/PLUGIN_AUTHORING.md> |
| 스킬 디렉터리의 참조 검증기로서의 `skills-ref validate` | <https://agentskills.io/specification> |
| Windows는 콘솔 응용 프로그램으로 Command Prompt와 Windows PowerShell을 씁니다. 이 문서가 지목하는 것은 그 둘이며 POSIX `sh`가 아님 | <https://support.microsoft.com/en-us/windows/apps/command-prompt-and-windows-powershell> |
| 네이티브 Windows의 하네스는 Bash 도구로 Git for Windows를 쓰고 그것이 없으면 PowerShell로 폴백하므로, `sh` 스크립트가 아예 실행되지 않을 수 있음 | <https://code.claude.com/docs/en/setup> |

### 증거 등급

배치와 비용 기록 규칙은 `PRIMARY`이며 evaluating-skills 문서가 말합니다. 구체적 디렉터리 배치는
**저장소 결정**이며 출처가 말한 것이 아닙니다. 표준의 배치인 것처럼 제시하지 않고 선택과 그 맞바꿈을
기록합니다.
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: 470kUpdated 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