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.