octocode-search-skill

What this skill does

# Octocode Search Skill

Find, evaluate, improve, install, or synthesize Agent Skills by inspecting real skill files, comparing workflow quality, and gating every write or install action.

Agent Skills are folders with required `SKILL.md` frontmatter (`name`, `description`) plus instructions. They may include `scripts/`, `references/`, `assets/`, or other support files. Agents load them by progressive disclosure: metadata first, full `SKILL.md` on activation, bundled resources only when needed.

## Operating Model

Default flow:

```text
UNDERSTAND -> DISCOVER -> INSPECT -> JUDGE -> RECOMMEND -> USER GATE -> ACT -> VERIFY
```

Compress steps when the user names a specific source (`owner/repo path-to-SKILL.md` or a local path). Repeat steps when discovery returns weak or conflicting candidates.

Hard rules:

Recommend
- MUST recommend by task fit, workflow quality, safety gates, and portability; use `installs` count or GitHub stars only as a tiebreaker when two candidates are otherwise equal.
- MUST identify every remote candidate by `(owner/repo, path-to-SKILL.md)` and every local candidate by absolute or workspace-relative path.

Inspect
- MUST inspect actual `SKILL.md` content before recommending, adapting, installing, or quoting a candidate as a pattern.
- MUST inspect referenced files that affect behavior for strong, risky, or unclear candidates.
- MUST skip candidates lacking valid `name` and `description` frontmatter.

Gate
- MUST gate installs, file writes, local skill creation, target selection, config changes, overwrite decisions, and symlink decisions.

Forbidden
- FORBIDDEN: handing the user a raw search dump to rank. Filter first, explain tradeoffs, recommend a next step.
- FORBIDDEN: copying another skill wholesale unless the license and the user explicitly allow it.

Stop when any of these is true:

- One recommendation is justified by inspected content.
- Two or more High-quality candidates have been inspected and task fit is confirmed for the top pick.
- Three search angles have returned no new candidates not already examined.
- A user gate is awaiting an answer.

## Tool Routing

Use Octocode MCP for all research — locally and externally — and let user intent decide which side leads. Octocode MCP already documents its own tools and query schemas; rely on the active descriptors instead of duplicating them here.

- Lead local when the question is about the user's workspace: existing skills, custom paths, draft skills, repo conventions.
- Lead GitHub when the user is shopping for a skill, comparing options, or asking about something not present locally.
- Read code or files: `localGetFileContent` or `githubGetFileContent`.
- Download a remote skill folder before writing it locally: `githubGetFileContent(type="directory")` or `githubCloneRepo`.
- Web search: for every PUBLIC skill query, MUST also run the runtime's web search tool (e.g. `WebSearch`) in parallel with Octocode/GitHub and the skills.sh API. It catches skills surfaced in articles, awesome-lists, release notes, and registries outside the known set. Treat web-only mentions as LEADS, not recommendations — always resolve the real `(owner/repo, path-to-SKILL.md)` and confirm the actual `SKILL.md` via Octocode (`githubGetFileContent`) before recommending. Skip only for local-only or org/private scopes (Octocode tools only there).

Fallbacks:

- IF the runtime lacks Octocode MCP, map each verb (search, read, list, download) to the equivalent runtime tool and continue.
- IF GitHub research is required and unavailable, stop and ask whether to use a public web fallback.
- IF a marketplace surface (`skills.sh`, `claude-plugins.dev`, `aiskillstore.io`, `agentskills.me`) is unreachable or rate-limited, switch to GitHub topic search and `llms.txt` catalog snapshots (see `references/discovery-surfaces.md`); lower confidence and continue.
- IF the user requested local-only work, do not query remote sources.

## Local References

All reference material lives under `references/`.

- Read `references/agent-skills-guide.md` when evaluating, improving, rating, or creating a skill, optimizing a description, deciding what belongs in `SKILL.md`, designing progressive references, or adding scripts/assets.
- Read `references/discovery-surfaces.md` when the user wants to shop for skills beyond raw GitHub search — marketplaces, leaderboards, registry REST APIs, manifest formats, and CLI installers.
- Read `references/install-reference.md` when the user chooses to install a skill or asks about install targets, destinations, scopes, or conflict behavior.
- Read `references/fetch-and-create-locally.md` when fetching a remote skill via Octocode into a local folder — whether to install verbatim or to adapt into a new local skill.

## Understand

Extract these facts before searching or editing:

- User goal: find, compare, preview, install, deep-dive, rate, improve, or create.
- Task/domain: coding, docs, data, design, security, research, planning, review, operations, or other.
- Target ecosystem: Claude Code, Claude Desktop, Cursor, Codex, OpenCode, custom agent, or unspecified.
- Source scope: local folders, named repo, marketplace, broad public search, or user-provided skill path.
- Constraints: language, framework, IDE, license, local-only, security posture, install target, no-web, org/repo limits.
- Quality preference: battle-tested, small, script-backed, enterprise-safe, example-rich, low-dependency, or strict-gated.

Ask one focused question only when the answer changes search scope, target ecosystem, or write/install behavior. Otherwise proceed with stated assumptions.

## Discover And Inspect

Set depth before searching:

- Quick answer: inspect enough to recommend one best candidate with caveats.
- Research request: compare broadly, preserve confirmed sources, stop when more search is unlikely to change the recommendation.
- Install request: inspect source, support files, target destinations, and conflict behavior before asking for approval.
- Improve, rate, or create request: inspect the target skill, adjacent local examples, and `references/agent-skills-guide.md` before writing.
- Weak results: broaden once, then report the gap and the next best action.

For every public skill query, fan out across three surfaces IN PARALLEL, then merge and dedupe by `(owner/repo, skill name)`:

1. Octocode/GitHub — code and path search for `SKILL.md` (see "Useful GitHub patterns").
2. skills.sh Registry API — install-ranked candidates (see "Skills.sh Registry API").
3. Web search — runtime web search tool (e.g. `WebSearch`) for the topic + "agent skill"/"claude skill"/"SKILL.md", to catch skills outside the known registries. Confirm each web lead's real `SKILL.md` via Octocode before recommending.

Search angles:

- Name: exact phrase, lowercase, hyphenated folder name, aliases.
- Subject: core domain terms.
- Workflow verbs: analyze, review, migrate, generate, install, optimize, debug, audit, benchmark, plan.
- Ecosystem: agent, IDE, language, framework, MCP server, CLI, or platform named by the user.
- Safety: gate, validation, rollback, verify, tests, prompt, scripts, permissions.

Useful GitHub patterns:

- Search body and frontmatter with `filename: "SKILL.md"` and `match: "file"`.
- Search likely folder names with `filename: "SKILL.md"` and `match: "path"`.
- Search composite filenames `*.skill.md` for skills that do not use the canonical `SKILL.md` name.
- Search frontmatter content with `filename: "SKILL.md" "name:" "description:"` to bias toward well-formatted skills.
- Discover repos via topics: `topicsToSearch: ["agent-skills"]`, `["claude-code-skills"]`, `["claude-skill"]`, `["cursor-skills"]`, `["codex-skills"]`. Combine with keywords like `agent`, `skills`, and `SKILL.md`.
- Inspect likely paths: `skills/<name>/SKILL.md`, `skills/<category>/<name>/SKILL.md`, `<name>/SKILL.md`, `.claude/skills/<name>/SKILL.md`, `.cursor/skills/<name>/SKILL.md`, `.codex/skills/<name>/SKILL.md`, `.opencode/skills/<