/octocode-skills

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.