Hyperskills Contributor Guide

Read this before adding or changing a skill. Hyperskills supplies non-obvious procedural knowledge for capable agents. Model names and tool versions change; useful constraints, evidence, and operational failure modes should survive them.

Design Contract

A skill earns its place when it changes a decision the model would otherwise get wrong. Keep fragile operation ordering, meaningful decision criteria, and reusable checks. Remove generic tutorials, repeated host policy, unsupported performance claims, and historical anecdotes presented as universal rules.

User instructions take precedence over skill guidelines. Skills preserve the requested scope and existing authorization; they do not invent approval gates, silently expand external actions, or bypass host permissions. Use the current tool schema for dispatch, waits, and capabilities.

Treat the repository as shared space. Check status before edits, inspect existing diffs, and own explicit paths. Follow the user's commit and publishing policy. Do not modify installed user configuration as a side effect of editing a skill.

Repository Map

hyperskills/
├── .claude-plugin/
│   ├── marketplace.json
│   └── plugin.json
├── .github/
│   └── workflows/
│       ├── ci.yml
│       ├── prepare-release.yml
│       └── release.yml
├── .gitignore
├── .markdownlint.json
├── .prettierignore
├── .prettierrc
├── AGENTS.md
├── CHANGELOG.md
├── CLAUDE.md
├── LICENSE
├── Makefile
├── README.md
├── docs/
│   ├── library-review-2026-09.md
│   ├── library-review-2026-10.md
│   └── releases.md
├── evals/
│   ├── PROTOCOL.md
│   ├── README.md
│   ├── RUNNING.md
│   ├── cases/
│   │   ├── README.md
│   │   ├── atomic-export/
│   │   │   ├── fixture/
│   │   │   │   ├── exporter.py
│   │   │   │   └── notes.txt
│   │   │   └── prompt.md
│   │   ├── atomic_worker.py
│   │   ├── grade.py
│   │   ├── oracle_adapter.py
│   │   ├── prose-preservation/
│   │   │   ├── fixture/
│   │   │   │   └── draft.md
│   │   │   └── prompt.md
│   │   ├── research-release/
│   │   │   ├── fixture/
│   │   │   │   ├── news.md
│   │   │   │   └── releases.json
│   │   │   └── prompt.md
│   │   ├── review-boundary/
│   │   │   ├── fixture/
│   │   │   │   ├── cache.py
│   │   │   │   └── unique.py
│   │   │   └── prompt.md
│   │   └── test_graders.py
│   └── pilot.json
├── release.json
├── scripts/
│   ├── eval_claude.py
│   ├── open_release_pr.py
│   ├── release.py
│   ├── skill_eval.py
│   ├── sync_metadata.py
│   └── validate_skills.py
├── skills/
│   ├── brainstorm/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── evidence.md
│   ├── codex-imagegen/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── evidence.md
│   ├── cross-model-review/
│   │   ├── SKILL.md
│   │   ├── references/
│   │   │   ├── cli-flags.md
│   │   │   ├── evidence.md
│   │   │   ├── failure-recovery.md
│   │   │   ├── observable-reviews.md
│   │   │   └── prompts.md
│   │   ├── scripts/
│   │   │   ├── review_status.py
│   │   │   └── run_claude_review.py
│   │   └── tests/
│   │       └── test_observable_review.py
│   ├── demo-reel/
│   │   ├── SKILL.md
│   │   ├── assets/
│   │   │   ├── card.html
│   │   │   └── timer.html
│   │   ├── references/
│   │   │   ├── agent-on-camera.md
│   │   │   ├── capture.md
│   │   │   ├── demo-world.md
│   │   │   ├── edit-render.md
│   │   │   ├── examples.md
│   │   │   ├── gotchas.md
│   │   │   ├── method.md
│   │   │   └── verify.md
│   │   └── scripts/
│   │       ├── agent-take.sh
│   │       ├── capture-web.mjs
│   │       ├── contact-sheet.sh
│   │       ├── doctor.sh
│   │       ├── selftest.sh
│   │       └── verify-mp4.sh
│   ├── deslop/
│   │   ├── SKILL.md
│   │   ├── references/
│   │   │   ├── craft-moves.md
│   │   │   ├── evidence.md
│   │   │   ├── fixtures/
│   │   │   │   ├── clean.md
│   │   │   │   ├── protected.md
│   │   │   │   └── slop.md
│   │   │   ├── pattern-catalog.md
│   │   │   └── surface-profiles.md
│   │   └── scripts/
│   │       ├── selftest.sh
│   │       └── slopscan.pl
│   ├── dream/
│   │   ├── SKILL.md
│   │   └── references/
│   │       ├── conversation-formats.md
│   │       └── extraction-guide.md
│   ├── git/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── evidence.md
│   ├── hyper-pr-review/
│   │   ├── SKILL.md
│   │   └── references/
│   │       ├── evidence.md
│   │       ├── lenses.md
│   │       ├── report-examples.md
│   │       └── thermonuclear.md
│   ├── implement/
│   │   ├── SKILL.md
│   │   └── references/
│   │       ├── benchmarks.md
│   │       ├── evidence.md
│   │       └── recovery.md
│   ├── orchestrate/
│   │   ├── SKILL.md
│   │   └── references/
│   │       ├── dispatch-briefs.md
│   │       └── evidence.md
│   ├── plan/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── evidence.md
│   ├── research/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── evidence.md
│   ├── super-good-pr/
│   │   ├── SKILL.md
│   │   └── references/
│   │       ├── evidence.md
│   │       └── worked-examples.md
│   └── tui-design/
│       ├── SKILL.md
│       └── references/
│           ├── app-patterns.md
│           ├── evidence.md
│           └── visual-catalog.md
└── tests/
    ├── test_eval_claude.py
    ├── test_open_release_pr.py
    ├── test_release.py
    ├── test_skill_eval.py
    ├── test_sync_metadata.py
    └── test_validate_skills.py

Skill Inventory

Reference counts include every Git-visible file under references/, including fixtures.

Process skills cover approaches to work: brainstorm, plan, research, orchestrate, implement, cross-model-review, hyper-pr-review, codex-imagegen, super-good-pr, deslop, dream, and demo-reel.

Domain skills cover specialized operational knowledge: git and tui-design. Ordinary package management, linting, and type checking use current tool help and official documentation; the former Astral and Tilt skills are retired.

Authoring

Every skill directory contains SKILL.md with valid YAML frontmatter:

---
name: skill-name
description: Use this skill when a specific workflow needs its specialized guidance. Activates on concrete task language.
---

The name matches its directory, uses lowercase letters, digits, and single hyphens, and is at most 64 characters. The description is a nonempty string of at most 1,024 characters. Describe the capability and realistic triggers; add exclusions when they prevent likely misrouting. Keyword counts are not a quality measure.

Keep the entrypoint as short as the task permits. Under 5,000 words is the repository ceiling, not a target. Put conditional detail in references/ as soon as it helps retrieval. Link each supporting file where it becomes useful. A self-contained skill needs no reference directory.

Write imperative guidance for the non-obvious moves. Use tables for comparisons and decisions, prose for connected reasoning, and examples for fragile mechanics. Include relevant anti-patterns and a clear scope boundary, conventionally titled "What This Skill is NOT". Graphviz dot is the default for internal workflow diagrams; choose a diagram only when it explains something prose cannot efficiently show.

Label local conventions, observed incidents, and external evidence distinctly. A research claim needs a source, date or version where relevant, and limits. Dated sources and their limits live in the skill's references/evidence.md; the entrypoint keeps one line pointing there, so citations never load at invocation. Do not generalize one model's benchmark into a permanent agent-count, token, confidence, or review-round quota. If a new model makes a workaround unnecessary, retire it after checking the behavior it protected. A rule phrased as a prohibition is usually a constraint written for an older model; its current form is the criterion the model applies, such as matching the surrounding comment style rather than never writing a multi-line comment. An example earns its place when it teaches a mechanic the model gets wrong (a quoting trap, an exact flag); an example of an answer's shape is a constraint the model copies. When a line exists because an older model misbehaved, the test for keeping it is whether the current model still fails without it.

Scripts belong in scripts/ when deterministic execution improves reliability. Explain dependencies and side effects. Never present generated files or a model's self-report as proof without inspecting the actual output.

Validation and Evaluation

Run make check for manifests, parsed YAML, required metadata, size limits, and concrete bundled references. The validator inspects all skill directories, including new untracked skills. Run make test for validator, scanner, observable review runner, and demo-reel regressions. The checks use uv to run isolated Python with PyYAML, plus Bash, Perl, and ffmpeg.

For a workflow change, select realistic cases from evals/README.md or add a case for a newly discovered failure. Evaluate the produced artifact and actions, not whether the response repeats a heading or phrase. Include a negative routing case when changing discovery metadata. A task requiring additional live access or publishing uses an isolated fixture or stops at a reviewable artifact.

For broad changes, obtain independent verification on the final scope. A contributor's self-check is useful evidence but is not independent review. Record unavailable checks as unavailable. Do not report a model-performance improvement without a comparable baseline, repeat trials, and an outcome-based grader.

Publishing Metadata

Run make sync-metadata when files or skills change. The generated regions own the repository tree, skill inventory, reference counts, and README skill badge. Edit surrounding prose when a skill materially changes scope. Update the canonical plugin description and keywords when the public surface changes; synchronization copies the description into the marketplace entry. Keep CLAUDE.md as a symlink to this guide.

Version changes follow the user-facing surface:

Ordinary skill PRs leave the version unchanged. The release workflow prepares the version, changelog, and release record together from explicit release intent. Merging its release PR publishes the verified merged commit. Local preparation only changes files; it does not authorize tagging or publishing. Keep temporary research notes and private session material out of commits. A requested public review report is a deliverable; an internal planning scratchpad is not.

Maintenance Questions

Before adding another instruction, ask what failure it prevents, whether that failure still occurs, and whether a tool or test can enforce the invariant better. Check the new instruction against the other skills that commonly compose with it. Prefer one clear owner for a procedure over several almost-identical copies.

The Agent Skills specification defines the metadata format. OpenAI's Astra guidance explains why conflicting skill instructions deserve attention. Both were checked on 2026-09-04; current host behavior remains authoritative for execution details.