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/progressive-disclosure.ko.md

View on GitHub
# 점진적 공개

**Purpose**: 스킬을 간결하게 유지하면서 깊은 내용을 필요한 순간에 찾을 수 있게 만듭니다.

## 1. 세 단계 로딩 모델

모든 스킬을 에이전트가 단계적으로 로드한다고 가정하고 설계합니다.

| 단계 | 로드되는 내용 | 설계 목표 |
|---|---|---|
| 발견 | `name`, `description`, 경로 | 올바른 스킬 선택 |
| 활성화 | `SKILL.md` 전체 | 핵심 워크플로와 실행 계약 |
| 실행 | `rules/`, `references/`, `scripts/`, `assets/` | 필요할 때만 읽는 세부, 결정적 도우미, 출력 자원 |

계층이 깊을수록 내용은 더 구체적이고 더 선택적이어야 합니다.

단계마다 비용이 다릅니다. 메타데이터는 쓰이든 쓰이지 않든 설치된 스킬마다 약 100토큰씩 로드됩니다.
본문은 활성화할 때 로드되며 5,000토큰 아래로 유지해야 합니다. 번들 파일은 읽기 전에는 비용이 없고,
스크립트 코드는 컨텍스트에 들어가지 않으며 출력만 들어갑니다. 일부 런타임은 호출된 본문을 파일을
다시 읽지 않고 이후 턴에도 컨텍스트에 남겨 두므로, 본문의 모든 줄이 되풀이되는 비용이고 가장 중요한
지침은 앞부분에 두어야 합니다.

## 2. 컨텍스트 예산

아래 두 수치는 **서로 다른 것**이며 그 차이가 중요합니다.

| 수치 | 지위 | 대상 |
|---|---|---|
| 500 lines | `PRIMARY` - 명세가 말합니다 | `SKILL.md` 본문 |
| 5,000 tokens | `PRIMARY` - 명세가 말합니다 | `SKILL.md` 본문 |
| 300 | **이 저장소가 고른 게이트** | `instructions/` 아래 파일만 |

300줄 값은 출처가 말한 수치가 아닙니다. 이 저장소가 고른 기본값이며 `scripts/check-sources.sh`가
`MAX_LINES=300`으로 강제하고, 그 스크립트는 `DOC_SCOPE="instructions"`를 설정하므로
`instructions/**`를 검사하고 **현재 이 스킬은 덮지 않습니다**. 300을 명세 요구처럼 제시하지 말고,
다른 검사가 우연히 다른 범위를 본다는 이유로 이 스킬이 500줄 예산에서 면제된다고도 보지 않습니다.

그 밖의 예산 규칙:

- 각 `references/` 파일은 한 주제에 집중합니다.
- 깊은 참조 사슬을 만들지 않습니다.
- 지원 파일을 만들었으면 `SKILL.md`에서 직접 참조합니다.
- 지원 파일이 필요하지 않았던 설명은 만들지 않습니다.
- 평가 픽스처와 프롬프트 템플릿은 실제로 실행하거나 복사할 때 산문 참조가 아니라 `assets/`에 둡니다.

## 3. 핵심을 간결하게 유지

핵심 스킬은 다음을 담습니다.

- 직업, 트리거, 경계
- 권위, 안전, 출력, 검증, 정지 조건 요약
- 상위 수준 워크플로
- 함정: 합리적 가정을 뒤집는 환경 사실. 에이전트가 그 상황을 만나기 전에 읽도록 핵심에 둡니다.
  참조 파일은 에이전트가 열어야 할 줄 이미 알고 있을 때만 도움이 됩니다
- 읽는 조건이 붙은 더 깊은 파일 안내

밖으로 옮길 것:

- 긴 예시
- 공식 출처 요약
- 스키마와 제공자별 세부
- 변형별 워크플로
- 결정적 명령 로직
- 출력 템플릿

## 4. 안내 문구

`see references/`처럼 모호하게 쓰지 않습니다.

약한 예:

```markdown
For more information, see references/.
```

나은 예:

```markdown
Read `references/official/openai.md` only when Codex-specific skill behavior changes the rule.
Read `rules/validation-and-iteration.md` before declaring the skill complete.
Run the target package's documented validator when present.
A repository-maintenance gate stays in the repository's policy documents, not in the skill artifact (`rules/self-containment.md`, SK-S-1).
```

읽는 조건은 디렉터리가 아니라 에이전트가 알아볼 수 있는 상황으로 씁니다. "`references/`를 보세요"보다
"API가 200이 아닌 상태 코드를 반환하면 `references/api-errors.md`를 읽으세요"가 낫습니다.

## 5. 한 단계 깊이

지원 파일은 `SKILL.md`에서 직접 연결하는 것을 우선합니다. 참조는 핵심에서 **한 단계 깊이**로
유지합니다.

이유는 정돈이 아닙니다. 에이전트는 다른 참조에서 참조된 파일을 부분적으로 읽고 `head -100` 같은
명령으로 미리보기한 뒤 불완전한 그림으로 행동할 수 있습니다. `SKILL.md`가 직접 연결한 파일은 전체가
읽힙니다. 규칙이 다른 규칙을 요구하고 그 규칙이 또 다른 참조를 요구하는 사슬은 명시적으로 정당화하지
않는 한 피합니다.

## 6. 참조 파일 구조

**100줄을 넘는 참조 파일에는 맨 위에 table of contents를 넣습니다.** 깊은 사슬을 위험하게 만드는 같은
부분 읽기 동작 때문에 독자가 여는 몇 줄만 볼 수도 있으며, 목차는 그때도 파일의 전체 범위를 보이게
합니다.

## 7. 필요에 따라 나누기

내용을 옮길 자리:

- 반복되는 정책은 `rules/`
- 상세 지식은 `references/`
- 결정적 실행은 `scripts/`
- 출력 자원은 `assets/`
- 소비되는 런타임·UI 메타데이터는 `agents/`

## 8. 낭독 점검

나눈 뒤 확인합니다.

- 핵심만으로도 여전히 말이 되는가
- 지원 파일을 핵심에서 찾을 수 있는가
- 핵심 지침이 계층 사이에 중복되지 않았는가
- 모든 지원 파일이 존재할 이유가 있는가

### 제거 시험

위 질문들은 내용이 *쓸모 있는지*를 묻습니다. 다음은 그것이 *설 자리를 얻는지*를 정합니다.

- SK-D-1: 각 지침에 대해 **"이것이 없으면 에이전트가 틀릴까?"** 를 묻습니다. 답이 아니오면 삭제합니다. 확신이 없으면 미심쩍다는 이유로 남기지 말고 시험합니다.
- SK-D-2: 스킬 없이도 작업이 성공한다면 그 스킬은 가치를 더하지 않을 수 있습니다. 에이전트가 이미 안정적으로 하는 일을 다시 적는 스킬은 이익 없는 비용입니다.
- SK-D-3: 잘 썼다는 이유만으로 그 스킬을 유지할 가치가 생기지는 않습니다. 2026년 벤치마크에서 공개 스킬 98개 중 92개가 통계적으로 유의미한 효과가 없었고, 해로운 스킬은 자기 템플릿에 에이전트를 고정하고 과제의 명시 지시를 덮어쓰는 방식으로 작동했습니다. 그래서 "내 스킬은 항상 잘 따른다"는 가치의 증거가 아닙니다.

낭독 질문 **과** 제거 시험을 함께 유지합니다. 둘은 다른 것을 묻습니다. 앞은 독자가 찾을 수 있는지를,
뒤는 그 내용이 애초에 있어야 하는지를 묻습니다.

## 9. 로드되는 앞부분을 안정적으로 유지

런타임이 스킬 이름, 설명, 호출된 본문을 세션마다 다시 보내는 경우, 그 텍스트는 재사용되는 프롬프트
접두사의 일부이고 이를 고치면 캐시된 재사용이 무효가 됩니다. 그러므로 길이뿐 아니라 **안정성**으로도
나눕니다. 안정적인 계약 텍스트는 `SKILL.md`에, 빠르게 바뀌는 제공자 세부와 날짜, 개수, 버전 고정값은
`references/`나 파일 아래쪽에 둡니다. 배치 규칙은 `rules/resource-placement.md` §8a에 있습니다.

## Sources

> 확인 2026-11-03.

| 주장 | 출처 |
|---|---|
| 500줄·5,000토큰 점진적 공개 예산, `SK-D-1`과 `SK-D-2`의 근거인 제거 시험, 함정 배치 규칙, 조건부 읽기 안내 예시 | <https://agentskills.io/skill-creation/best-practices> |
| 스킬당 약 100토큰의 메타데이터, 5k 토큰 미만 본문, 스크립트의 유일한 컨텍스트 비용인 스크립트 출력 | <https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview> |
| 파일을 다시 읽지 않고 이후 턴에도 컨텍스트에 남는 호출된 스킬 본문 | <https://code.claude.com/docs/en/skills> |
| `SK-D-3`의 근거인 98개 중 92개 무효과 결과와 템플릿 고정 실패 | <https://arxiv.org/abs/2603.15401> |
| 안정성으로 나누기와 로드되는 앞부분 유지 | `instructions/cache/CACHE.md` §3 |
| 세 단계 모델(메타데이터, 전체 지침, 참조 파일) | <https://agentskills.io/specification> |
| 한 단계 깊이 참조 규칙과 그 이유인 부분 읽기 | <https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices> |
| 100줄을 넘는 참조 파일의 목차 규칙 | <https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices> |
| 300줄 저장소 게이트와 그 범위 | `scripts/check-sources.sh` (`MAX_LINES=300`, `DOC_SCOPE="instructions"`) |

### 증거 등급

이 파일은 공개 예산의 **정본** 진술입니다. `rules/skill-anatomy.md`는 예산을 다시 적지 않고 이 파일을
가리킵니다. 500줄과 5,000토큰은 `PRIMARY`이며 명세가 말합니다. 300줄 값은 저장소 게이트이며 그렇게
표시하고 출처가 말한 값처럼 제시하지 않습니다.
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