---
name: octocode-skills
description: "Use when working on Agent Skills (SKILL.md folders): find, compare, rate, review, create, improve, repair, install, or sync skills from local workspaces, registries, or remote sources. For wording-only prompt polish without folder ops, use octocode-prompt-optimizer."
---

# Octocode Skills

Operate on standalone Agent Skill folders: `SKILL.md` plus optional references, scripts, and assets.
Flow: `UNDERSTAND → DISCOVER → INSPECT → JUDGE → RECOMMEND → USER GATE → ACT → CLEANUP → REVIEW → VERIFY`.

## Lobby rules
- `SKILL.md` owns workflows, hard gates, and routes; each reference owns one concept and never restates the flow.
- The lobby lists every reference and every script with when and how to use it, plus the workflows — no chunk is discoverable only by opening another file.
- MUST read and navigate between routed reference files to understand the complete flow; this skill is intentionally simplified into reference units for efficiency, including reference-to-reference handoffs.
- Inspect the real `SKILL.md` before quoting, judging, or installing; identify candidates by path and gate every write.
- Stop when one fit is clear, two High candidates need a winner, three angles add nothing, or user/auth approval is pending.
- Ship a standalone folder with one owner per concept; prune dead or duplicated material before done. Assume no sibling skill is installed: name a sibling to load, never depend on its files.

## Smart routes — load only what the current step needs
- When discovering, load `references/search-playbook.md`; choose a source with `references/discovery-surfaces.md`, parse manifests with `references/discovery-manifests.md`, and recover with `references/recovery.md` — search broadly enough without inventing candidates.
- When judging, load `references/quality-rubric.md` for content fit and `references/quality-signals.md` for adoption/recency; when recommending, present through `references/output-format.md` — rank evidence, not popularity alone.
- When designing structure, load `references/skill-anatomy.md`; write with `references/skill-authoring.md`, extract deterministic work with `references/skill-scripts.md`, and tune activation with `references/description-tuning.md` — keep the lobby lean and triggers strong.
- When improving, load `references/skill-improve.md`; choose review/refactor mode with `references/self-improvement.md`, clean with `references/skill-cleanup.md`, and use `references/improve-loop.md` only if `octocode-graph-eval` is unavailable — preserve intent and require measurable acceptance.
- Before done, load `references/skill-review.md`; interpret findings with `references/skill-review-rules.md` — enforce structure, navigation (lobby shows every chunk, routes state when/why, chunks declare entry and next hop, flow phases routed), prose, and standalone-folder gates.
- When reviewing lifecycle automation, load `references/hooks.md`; when adding it, load `references/hooks-add.md` and use `assets/hooks/` — map the correct host event and avoid silent no-ops.
- When installing, load `references/install-gates.md`, then `references/install-destinations.md`; remote sources use `references/fetch-remote.md`, local creation uses `references/create-local-skill.md`, and vendor links use `references/skill-sync.md` — secure approval, destination, and provenance before writes.
- When evidence needs code/package/repository research, load `references/octocode.md` — delegate research mechanics instead of duplicating them.
- When tracing source provenance, load `references/references.md`; when authoring a source appendix, start from `references/references-template.md` — keep claims auditable without bloating instructions.

## Related routes
- Use `octocode-research` to verify candidates; `octocode-prompt-optimizer` to improve wording; `octocode-graph-eval` to measure behavior.
- Use `octocode-rfc-generator` before a large skill-system redesign.

## Scripts and done gate
- Run `scripts/skill-review.mjs` after any create/edit — zero ERROR is required.
- Run `scripts/skill-sync.mjs` only after a dry-run and human approval — synchronize one source safely.
- `scripts/skill-lint.mjs` is an alias for `scripts/skill-review.mjs` — same gate under the older name.
- A skill script needing Octocode home or env imports `./octocode-config.mjs`, a build artifact injected by `packages/octocode-config` into every skill that imports it relatively — never import `@octocodeai/config` from a skill, or the folder breaks once installed alone.
- When wiring a hook, copy `assets/hooks/example-hook.sh` into `scripts/hooks/` and route it from frontmatter.

## Installation
When creating or installing, follow the routed approval and destination gates, then run the review before reporting done.