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/anti-patterns.ko.md

View on GitHub
# 스킬 안티패턴

**Purpose**: 스킬 작성에서 흔한 실패를 막습니다.

## 피할 것

- 안정적으로 발동하기에 너무 모호한 설명
- 스킬이 무엇인지는 말하고 언제 쓰는지는 말하지 않는 설명
- positive·negative·boundary 트리거 예시가 없음
- 근접 오답 케이스가 없어 이웃 스킬의 트리거 가로채기를 한 번도 측정하지 않음
- 미니 위키가 된 `SKILL.md` 본문
- 참조에 숨은 핵심 트리거나 정지 조건 로직
- 핵심, 규칙, 참조에 중복된 세부
- 발견하기 어려울 만큼 깊게 중첩된 참조
- 런타임이나 사용자가 명시적으로 필요로 하지 않는 한 스킬 안에 두는 `README.md`, `CHANGELOG.md`, `QUICK_REFERENCE.md` 같은 추가 문서
- 정본 핵심 지침에 들어간 시점 민감 제공자 세부
- 신뢰성 근거, 사용법, 의존성, 실패 동작 없이 추가한 스크립트
- 복사되거나 채워지거나 워크플로에서 쓰이지 않는 자산
- 사용자·프로젝트 지침보다 높은 권위로 취급한 제공자 문서나 검색 조각
- 명시적 게이트 없는 자격 증명, 네트워크, 파괴적, 프로덕션 부작용
- 스킬이 하나의 길을 권해야 할 때 제시하는 너무 많은 선택지
- 피드백, 지표·루브릭, 독립 가드, 수용 규칙, 확고한 정지가 없는 루프
- 기준선이나 평가 집합을 바꾸고 그 결과를 개선이라 부르는 것
- 역량 확인이나 명시적 열화 경로 없는 공유 핵심의 제공자별 명령
- 실제 검증 실행보다 뒤인 출처 날짜, 또는 검색 조각·모델 요약을 출처로 기록하는 것
- 동등한 동작의 증거로 취급한 구조적 양언어 짝
- 도구 인자, 소유, 권한, 부작용이 중요한 워크플로에서 최종 출력만 검증하는 것
- `runs`나 `threshold`를 밝히지 않고 상속하는 트리거 케이스
- 길이 한도를 다시 확인하지 않고 항목 한도를 넘겨 키운 설명
- 스킬 있음·없음 **양쪽** 조건에서 통과해, 스킬의 가치를 반영하지 않고 통과율만 부풀리는 단언
- **증거 문자열** 없이 `passed: true`만 있는 `grading.json` 기록
- 배포되는 스킬 폴더 안에 둔 실행 결과 (`.hyper/evidence/` 아래가 아니라)
- 에이전트가 이미 안정적으로 하는 일을 다시 적는 스킬, 즉 이익 없는 비용
- 편의를 위한 부여가 아니라 권한 경계로 제시한 `allowed-tools`
- 계약의 일부를 표시 없이 떠안은 런타임 전용 frontmatter 필드(`disable-model-invocation`, `when_to_use`, `agents/openai.yaml`) 때문에 다른 런타임에서 스킬이 다르게 동작하는 것(SK-P-3)
- 배포, 게시, 전송, 삭제 스킬을 자동 활성화에 열어 둔 경우
- `SKILL.md`의 로드되는 앞부분에 있는 변동성 큰 날짜, 개수, 버전 고정값 때문에 갱신할 때마다 캐시된 재사용이 무효가 되는 것
- `assets/evals/`와 패키징된 도구의 케이스 파일, 두 평가 집합이 서로 어긋난 것
- 짝지은 기준선 없이 "스킬을 잘 썼으니 도움이 된다"고 유용성을 주장하는 것
- 구체적이고 실행 가능한 불평 대신 "별로다"로 끝나는 사람 검토 기록
- 숫자 상한, 독립 검사기, 선언된 결합 형태가 없는 무인 루프나 팬아웃

## 산출물 감사

이 절은 스킬이 받는 것이 아니라 스킬이 **무엇인지**를 시험합니다. 스킬은 배포되는 코드와 지침이므로
배포 전에 감사합니다. 일부가 아니라 일곱 행 전부입니다.

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

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

**이 패키지는 자기 감사의 코드 실행 사례입니다.** `skills/hyper-skill/scripts/validate-hyper-skill.sh`는
배포되는 스킬 디렉터리 안의 실행 코드이므로, 높음 등급의 코드 실행 행이 `hyper-skill` 자신에게
적용됩니다. 체크리스트로만이 아니라 대상으로서 감사합니다.

## 위험 신호

- "이 스킬은 여러 가지를 돕습니다."
- 어느 파일을 언제 읽을지 말하지 않는 "references/를 보세요."
- 출처 원장이나 갱신 조건 없는 "최신 모범 사례를 쓰세요."
- 권장 판단 경로 없는 "다섯 가지 접근이 있습니다."
- 같은 정의를 반복하는 여러 파일
- 현재 핵심 규칙에 섞인 오래된 제공자 지침
- 비사소한 스킬 변경에서 무시한 로컬 `instructions/skill/` 지침
- "구조가 좋아 보인다"는 이유로 생략한 검증
- 예산이나 유지·폐기 규칙 없는 "에이전트가 계속 시도할 수 있습니다."
- 결과·안전·실패 의미를 보존하지 않는 "쓸 수 있는 도구를 쓰세요."
- 부모 검증으로 대신 쓴 자식 에이전트의 성공 주장
- 무엇이 통과했는지 말하는 증거 문자열 없는 "통과했습니다"

## 수리 패턴

이 중 하나가 나타나면:

1. 스킬을 트리거 가능한 실행 패키지로 다시 서술합니다.
2. 근접 오답 케이스를 포함해 `description`과 트리거 예시를 다시 씁니다.
3. 잘못 놓인 세부를 규칙, 참조, 스크립트, 자산으로 옮깁니다.
4. 지침 계약을 추가하거나 갱신합니다.
5. 명시적 no-loop·loop 정책, 런타임 역량 경계, 출처·검색 가드, 위험에 비례하는 평가 표면을 더합니다.
6. 일곱 행 산출물 감사를 실행하고 결과를 기록합니다.
7. 같은 기준선과 적대적·알려진 회귀 케이스를 다시 돌리고, 추적을 살피고, `ship`, `iterate`, `caveated ship`, `block` 중 하나를 기록합니다.

## Sources

> 확인 2026-11-03.

| 주장 | 출처 |
|---|---|
| 심각도 표시가 있는 위험 등급 일곱 행, 재검토가 따르는 버전 고정 | <https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise> |
| 양쪽 조건과 증거 문자열, 그 뒤에 있는 양쪽 조건·`grading.json` 안티패턴 | <https://agentskills.io/skill-creation/evaluating-skills> |
| 스킬 폴더 밖에 두는 결과, 그 뒤에 있는 `.hyper/evidence/` 안티패턴 | <https://agentskills.io/skill-creation/evaluating-skills> |
| "에이전트가 이미 하는 일을 다시 적는" 안티패턴의 근거인 제거 시험 | <https://agentskills.io/skill-creation/best-practices> |
| 경계가 아니라 허용적 부여로서의 `allowed-tools` | <https://code.claude.com/docs/en/skills> |
| 수동 전용 스위치, 런타임 전용 확장 필드, 업로드 시 비명세 필드에 대한 하드 오류 | <https://code.claude.com/docs/en/skills> |
| `feedback.json`에 케이스별 구체적 불평으로 남기는 사람 검토 | <https://agentskills.io/skill-creation/evaluating-skills> |
| 공개 스킬 대부분이 유의미한 효과가 없다고 밝힌 짝지은 벤치마크 | <https://arxiv.org/abs/2603.15401> |
| 로드되는 앞부분에서 빼는 변동성 값 | `instructions/cache/CACHE.md` §3 |
| 바깥 루프 상한과 검사기 분리, 그래프 팬아웃 상한과 결합 형태 | `instructions/loop-engineering/LOOP_ENGINEERING.md`, `instructions/graph-engineering/GRAPH_ENGINEERING.md` |
| 최적화 중 다시 확인해야 하는 설명 길이 한도 | <https://agentskills.io/specification> |

### 증거 등급

심각도 표시는 `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