octocode-cli 1.3.1 → 1.5.1

package/skills/octocode-search-skill/references/agent-skills-guide.md

@@ -0,0 +1,177 @@
+# Agent Skills Guide
+
+Use this reference when evaluating, improving, or creating Agent Skills. Keep `SKILL.md` focused on activation-critical instructions and load this file only when the task is about skill quality, structure, descriptions, scripts, or progressive disclosure.
+
+## What Agent Skills Are
+
+Agent Skills are a lightweight, open folder format for extending AI agents with specialized knowledge and workflows.
+
+At minimum, a skill is a folder containing `SKILL.md`. That file includes frontmatter metadata (`name` and `description`) plus instructions for a specific class of tasks. Skills may also bundle scripts, reference materials, templates, and other resources.
+
+```text
+my-skill/
+|-- SKILL.md          # Required: metadata + instructions
+|-- scripts/          # Optional: executable code
+|-- references/       # Optional: documentation
+|-- assets/           # Optional: templates, resources
+`-- ...               # Optional additional files or directories
+```
+
+## Why Skills Help Agents
+
+Skills package procedural knowledge and team-, company-, user-, or domain-specific context into portable, version-controlled folders that agents load on demand.
+
+High-value skills provide:
+
+- Domain expertise: specialized knowledge the model would not reliably know by default.
+- Repeatable workflows: multi-step procedures with consistent, auditable execution.
+- Cross-product reuse: one skill can work across skills-compatible agents.
+
+## Progressive Disclosure
+
+Agents load skills in three stages:
+
+1. Discovery: at startup, the agent sees only each skill's `name` and `description`.
+2. Activation: when the user task matches the description, the agent reads full `SKILL.md`.
+3. Execution: the agent follows `SKILL.md`, loading bundled resources or running scripts only when needed.
+
+Design implication: every token in `SKILL.md` competes with conversation and system context. Put always-needed instructions in `SKILL.md`; move conditional details to `references/`, `scripts/`, or `assets/` and state when to load them.
+
+## Source Material For Good Skills
+
+Start from real expertise, not generic best practices.
+
+Strong sources:
+
+- Real completed tasks and the sequence that worked.
+- User corrections and preferences from hands-on runs.
+- Input/output examples and expected formats.
+- Internal docs, runbooks, style guides, schemas, API specs, and configuration files.
+- Code review comments, issue trackers, incident reports, and fixes from version control history.
+- Real-world failure cases and their resolutions.
+
+Avoid skills that only say vague things like "handle errors appropriately" or "follow auth best practices." Replace generic advice with concrete tools, commands, edge cases, and recovery procedures.
+
+## Context Discipline
+
+Add what the agent lacks; omit what the agent already knows.
+
+Ask for each instruction: "Would the agent likely get this wrong without the skill?" If not, cut it. If unsure, test it. If the agent already performs the task well without the skill, the skill may not add value.
+
+Good skills are coherent units of work. Avoid scopes that are too narrow and force many skills to load, or too broad and trigger imprecisely.
+
+Aim for moderate detail: concise, stepwise guidance with a working example usually beats exhaustive documentation. Keep `SKILL.md` under 500 lines and 5,000 tokens; for most skills, prefer under 300 lines when practical.
+
+## Progressive Reference Files
+
+Move long or conditional material into `references/` when it is not needed on every activation.
+
+Every reference link in `SKILL.md` must say when to load it, for example:
+
+```text
+Read `references/api-errors.md` if the API returns a non-200 response.
+```
+
+A generic "see references/" is too weak because the agent may not know which file matters.
+
+Keep non-obvious gotchas in `SKILL.md` if the agent must know them before it can recognize the trigger. Otherwise put them in a reference file with an explicit load condition.
+
+## Calibrating Control
+
+Match specificity to task fragility.
+
+Use flexible guidance when several approaches are valid and the task tolerates variation. Explain why the rule exists so the agent can adapt.
+
+Use prescriptive instructions when operations are fragile, safety-sensitive, destructive, or order-dependent. For fragile operations, provide exact commands and say not to modify them.
+
+Provide defaults, not menus. Pick the default tool or approach, then mention alternatives only as escape hatches.
+
+Favor reusable procedures over one-off answers. A skill should teach an approach for a class of tasks, while still including concrete formats, constraints, and tool rules where they matter.
+
+## Effective Instruction Patterns
+
+Use gotchas for environment-specific facts that correct likely agent mistakes:
+
+- Naming differences that refer to the same object.
+- Health checks that give misleading success.
+- Soft-delete filters or required query conditions.
+- Tool behavior that violates common assumptions.
+
+Use templates when output shape matters. Short templates can live in `SKILL.md`; long or conditional templates belong in `assets/` with explicit load instructions.
+
+Use checklists for dependent multi-step workflows. Include validation gates so the agent can track progress and avoid skipping steps.
+
+Use validation loops:
+
+1. Do the work.
+2. Run a validator, script, reference checklist, or self-check.
+3. Fix issues if validation fails.
+4. Repeat until validation passes.
+5. Proceed only after validation passes.
+
+Use plan-validate-execute for batch, stateful, or destructive operations. The plan must be checked against a source of truth before execution.
+
+## Bundling Scripts
+
+Use one-off commands when an existing tool already does the job and the command is simple. Pin versions when reproducibility matters, and state prerequisites.
+
+Move complex or repeatedly reinvented logic into `scripts/`. A good script for agents:
+
+- Accepts input via flags, environment variables, files, or stdin.
+- Never requires interactive prompts.
+- Provides concise `--help` output with examples.
+- Emits helpful errors that say what was wrong, what was expected, and what to try.
+- Sends structured data to stdout and diagnostics to stderr.
+- Is idempotent or safe to retry.
+- Rejects ambiguous input instead of guessing.
+- Supports `--dry-run` for destructive or stateful operations.
+- Uses meaningful exit codes when useful.
+- Keeps output bounded or supports pagination/output-file flags.
+
+Reference scripts from `SKILL.md` with paths relative to the skill root, for example `scripts/validate.sh`.
+
+## Description Optimization
+
+The `description` field is the primary trigger. At startup, agents see only `name` and `description`, so the description must tell the agent when to load the skill.
+
+Good descriptions:
+
+- Use imperative phrasing: "Use this skill when..."
+- Focus on user intent, not implementation internals.
+- Include non-obvious trigger situations where the user may not name the domain directly.
+- Stay concise and under the 1024-character limit.
+- Avoid being so broad that near-miss prompts trigger the skill.
+
+Test descriptions with realistic eval queries:
+
+- Should-trigger prompts: vary phrasing, typos, explicitness, detail, and task complexity.
+- Should-not-trigger prompts: include near-misses that share keywords but need a different skill.
+- Use train/validation splits so edits do not overfit to the test prompts.
+- Run multiple times when behavior is nondeterministic and compare trigger rates.
+
+Optimization loop:
+
+1. Evaluate current description on train and validation sets.
+2. Identify train failures: missed triggers and false triggers.
+3. Revise for the general category of failure, not exact query keywords.
+4. Keep the description under 1024 characters.
+5. Select the best iteration by validation pass rate.
+6. Sanity-check with fresh queries that were not used during optimization.
+
+## Quality Signals Beyond Stars
+
+When ranking candidates, prefer evidence-based signals over raw star count:
+
+- **Install count via search API** — query `https://www.skills.sh/api/search?q=<topic>&limit=100` (see `discovery-surfaces.md` for the full curl command), sort results by `installs` descending. High install count with modest GitHub stars is usually a stronger battle-tested signal than the reverse.
+- **Per-skill index page** — check `https://www.skills.sh/<owner>/<repo>/<skill-name>` (or `https://www.skills.sh/<org>/skills/<skill-name>` when the repo is named `skills`) for install count, install command, audit badge, and related skills.
+- **Leaderboard** — `https://www.skills.sh` shows install-count ranked skills across all agents; useful for spotting dominant skills in a domain without knowing names in advance.
+- **Recency** — `pushed:>YYYY-MM-DD` on GitHub. Skip skills with no commits in the last 12 months unless the user wants archival.
+- **Audit badges** — skills.sh exposes Gen Agent Trust Hub pass/fail; Microsoft uses the Sensei rubric (triggers + anti-triggers + compatibility scored Low/Medium/High).
+- **Registry-side fields** — `aiskillstore.io` exposes `match_reasons`, `downloads_7d`, `days_since_update`, and a `/similar` endpoint for overlap-ranked alternatives.
+- **Demand signal** — `aiskillstore.io/v1/demand/most-wanted` shows what users searched for and did not find; useful when deciding whether to adapt vs create.
+
+For full registry details, manifest formats, and CLI installers, load `discovery-surfaces.md`.
+
+## External Documentation Index
+
+The full documentation index is available at `https://agentskills.io/llms.txt`. Use that index only when external web access is allowed and current upstream details matter.

package/skills/octocode-search-skill/references/discovery-surfaces.md

@@ -0,0 +1,162 @@
+# Discovery Surfaces
+
+Use when the user wants to shop for skills beyond raw GitHub code search — marketplaces, registries, leaderboards, manifest formats, and CLI installers. Cross-check at least two surfaces before recommending a candidate, and prefer surfaces that show evidence of activity (installs, recent updates, audit status).
+
+## Quick Routing
+
+| User goal | Best first surface |
+|-----------|--------------------|
+| "Search skills by keyword or topic" | skills.sh Registry API (`/api/search?q=...`) — sort by `installs` |
+| "Is skill X published / battle-tested?" | `https://www.skills.sh/<owner>/<repo>/<skill-name>` |
+| "What are the most-installed skills right now?" | `https://www.skills.sh` leaderboard |
+| "Find a Claude Code plugin" | `claude-plugins.dev` (REST + UI) |
+| "Browse curated skills across agents" | `agentskills.me`, `agentskills.io` |
+| "Capability-based search (e.g. web_search, summarization)" | `aiskillstore.io/v1/agent/search?capability=` |
+| "Subscribe to new skills" | `aiskillstore.io/feed/new-skills.json` (JSON Feed) or `.rss` |
+| "Microsoft / Azure ecosystem skills" | `microsoft.github.io/skills` + its `llms-full.txt` |
+| "Claude marketplaces aggregated" | `claudemarketplaces.com`, `mcpmarket.com/tools/skills` |
+
+## Per-Skill Check
+
+Before recommending a remote skill, confirm it on at least one public index:
+
+```text
+https://www.skills.sh/<owner>/<repo>/<skill-name>
+```
+
+When the repo is the canonical `skills` repo, the URL collapses to:
+
+```text
+https://www.skills.sh/<org>/skills/<skill-name>
+```
+
+Examples:
+
+- `https://www.skills.sh/anthropics/skills/skill-creator`
+- `https://www.skills.sh/vercel-labs/skills/find-skills`
+- `https://www.skills.sh/obra/superpowers/brainstorming`
+
+What that page tells you (use as quality signals, not stars):
+
+- Install count (battle-test signal stronger than GitHub stars).
+- One-line install command (`npx skills add <repo> --skill <name>`).
+- Security audit status (e.g. "Gen Agent Trust Hub: Pass").
+- Related skills + sibling skills from the same repo.
+- First-seen date and source repository link.
+
+If the URL 404s, the skill is not in the public skills.sh index — fall back to the source repo, search alternative registries, and lower confidence.
+
+## Marketplace Surfaces
+
+Each surface is provider-agnostic unless noted. Treat install counts and audit badges as self-reported by the registry.
+
+### `agentskills.io`
+
+- Open standard hub originated by Anthropic.
+- `/clients` enumerates ~40 compatible agents (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Goose, Copilot, Junie, Amp, Roo, Kiro, etc.) with `instructionsUrl` and source repo per agent.
+- Agent-readable index: `agentskills.io/llms.txt`.
+
+### `skills.sh` (Vercel Labs)
+
+- Public install-count leaderboard.
+- Search box, agent filter ("available for these agents"), per-skill page (see Per-Skill Check above).
+- Install pattern: `npx skills add <github-url> --skill <skill-name>`.
+- **Registry search API** (MUST use for public skill searches, in parallel with GitHub):
+  ```bash
+  curl 'https://www.skills.sh/api/search?q={{SEARCH_KEY}}&limit=100' \
+    --compressed \
+    -H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:150.0) Gecko/20100101 Firefox/150.0'
+  ```
+  Response: `{"skills": [{"id": "owner/repo/skillId", "skillId": string, "name": string, "installs": number, "source": "owner/repo"}], "count": number}`
+  Sort results by `installs` descending; top entries are the most battle-tested candidates.
+  Do NOT use for org-specific or private searches — Octocode tools only for those.
+
+### `claude-plugins.dev` (Kamalnrf)
+
+- Auto-indexes every public Claude Code plugin and `SKILL.md` on GitHub.
+- Web UI + REST API + interactive `npx skills-installer search`.
+- Sortable: Relevance / Most Downloads / Most Stars; filterable by "With Skills".
+
+### `agentskills.me`
+
+- Curated 492+ skills directory across Claude Code, Cursor, OpenCode, Codex CLI, Gemini CLI.
+- Sortable: Most Popular / Most Stars / Editor's Pick.
+- Per-tool subpages.
+
+### `aiskillstore.io` (USK v1.0)
+
+- Universal Skill Kit registry with full agent-facing REST API.
+- Capability tag search: `/v1/agent/search?capability=<tag>` (e.g. `web_search`, `text_summarization`).
+- Platform filter: OpenClaw / ClaudeCode / Cursor / GeminiCLI / CodexCLI.
+- Trust levels: verified / community / sandbox.
+- BM25 FTS5 full-text search.
+- Similar skills: `/v1/agent/skills/{id}/similar`.
+- Pre-flight: `/v1/skills/{id}/validate` for platform/Python compatibility.
+- Demand signal: `/v1/demand/most-wanted` (zero-result queries — what does not exist yet).
+- Subscriptions: `/feed/new-skills.json` (JSON Feed 1.1), `/feed/new-skills.rss`.
+- Spec: `aiskillstore.io/llms.txt`.
+
+### `microsoft.github.io/skills` + `microsoft/skills`
+
+- Microsoft's curated skills index for Copilot CLI / VS Code; heavy on Azure SDK skills (Python, .NET, TS, Java, foundry, data, messaging, monitoring, entra, integration, compute, m365).
+- "Sensei" frontmatter scoring rubric (Low / Medium / High based on triggers + anti-triggers + compatibility).
+- Auto-generated `llms.txt` and `llms-full.txt` (daily-regenerated GitHub Pages).
+
+### Aggregator directories (`moderate` confidence — verify each entry)
+
+- `claudemarketplaces.com` — auto-updated directory of Claude marketplaces.
+- `mcpmarket.com/tools/skills` — per-skill install snippets.
+- `cursor.directory/plugins` — Cursor-native plugin/prompt directory.
+- `LobeHub Skills Marketplace` — multi-language UI. Note: install pattern asks the agent to `curl` the skill and self-install; treat as discovery only, not a trusted install path (prompt-injection adjacent).
+
+## Manifest Formats
+
+| Format | Where | Use |
+|--------|-------|-----|
+| `agentskills.io/llms.txt` | Standard hub | Agent-readable doc index |
+| `aiskillstore.io/llms.txt` | USK registry | Full v1.0 spec + endpoint catalog |
+| `microsoft.github.io/skills/llms.txt` + `llms-full.txt` | Microsoft catalog | Daily catalog snapshot |
+| `.claude-plugin/marketplace.json` | Per-marketplace repo | Anthropic native marketplace manifest |
+| `.claude-plugin/plugin.json` | Per-plugin repo | Per-plugin manifest |
+| `marketplace.json` (community) | Per-publisher repo | Community publish workflows |
+| `feed/new-skills.json` | aiskillstore.io | JSON Feed 1.1 — new-skill firehose |
+| `feed/new-skills.rss` | aiskillstore.io | RSS 2.0 alternative |
+| YAML frontmatter (USK v3) | Inside `SKILL.md` | `name`, `description`, `license`, `compatibility`, `metadata.version`, `allowed-tools`, `interface`, `input_schema`, `output_schema`, `capabilities`, `permissions`, `platform_compatibility`, `tags` |
+
+## CLI Installers
+
+These tools combine discovery and install. Always run a safety scan on the source before allowing install.
+
+| CLI | Install command | Notes |
+|-----|-----------------|-------|
+| `npx skills add` (Vercel Labs / `vercel-labs/skills`) | `npx skills add <gh-url> --agent <claude\|cursor\|codex\|opencode\|...> --skill <name>` | Symlink-by-default cross-agent installer. Reads `.claude-plugin/marketplace.json`. |
+| `npx skills-installer` (Kamalnrf) | `npx skills-installer install @owner/repo/skill --client <claude-code\|cursor\|vscode>` | Pairs with `claude-plugins.dev`; interactive `search` TUI. |
+| `npx claude-plugins` | `npx claude-plugins install/list/enable/disable` | Plugin marketplace mgmt. |
+| `arctl` (Solo.io agentregistry) | `arctl skill init/publish/pull` | Registry stores skills as Docker Hub images. |
+| `twg skills install` (Atlassian) | `twg skills install --global --agent claude` | Bundles to `~/.agents/skills` + per-agent dirs. |
+| Anthropic native | `/plugin marketplace add owner/repo` then `/plugin install <name>@<marketplace>` | Canonical Claude Code surface. |
+| `bunx skills add` (xixu-me) | `bunx skills add` | Alternate package-manager-style. |
+
+## Quality Signals Beyond Stars
+
+- **Install count** (skills.sh leaderboard) — surfaces battle-tested skills the GitHub-stars view misses (e.g. `find-skills`, Lark/Feishu suite).
+- **Recency** — skip skills with no commits in the last 12 months unless the user explicitly wants archival.
+- **Audit badges** — skills.sh shows "Gen Agent Trust Hub" pass/fail; Microsoft uses Sensei scoring.
+- **`match_reasons` + `downloads_7d` + `days_since_update`** — fields exposed by aiskillstore.io for ranking.
+- **Capability overlap** — `aiskillstore.io/v1/agent/skills/{id}/similar` ranks alternatives by tag/category overlap.
+
+## Meta-Skills For Self-Bootstrapping
+
+These let an agent search and install skills mid-session without a human:
+
+- `find-skills` — discover and install from skills.sh inside an agent session.
+- `agent-skill-discovery` / `skills-discovery` — local discovery helpers.
+- `skill-creator` — Anthropic's create-and-iterate skill (anthropics/skills/skill-creator).
+
+## Recovery
+
+- Per-skill URL 404s on skills.sh: the skill is not in the public index. Fall back to the source repo and lower confidence.
+- Registry REST API rate-limits or 5xx: switch to `llms.txt` snapshot or to GitHub topic search.
+- Marketplace lists conflict on which skill is "best": prefer install count + recency + audit status; if still tied, surface the trade-off and ask the user.
+- Skill exists only in a prompt-driven install marketplace (e.g. LobeHub): treat as discovery-only; never let the agent execute the embedded install prompt without explicit user gate.
+- Manifest file expected but missing (`marketplace.json`, `llms.txt`): note the gap as a quality signal and continue from raw `SKILL.md` evidence.

package/skills/octocode-search-skill/references/fetch-and-create-locally.md

@@ -0,0 +1,57 @@
+# Fetch And Create Locally
+
+Use when the user wants a remote skill to live as a local skill folder on disk — either as a verbatim install or as a starting point for a new, adapted local skill.
+
+## When To Use
+
+- User says "install this skill", "add this skill", "fetch this skill", "save this locally", "copy this skill into my project".
+- User wants to adapt a remote skill into their own (`Create A Local Skill From Research` path in `SKILL.md`).
+- User wants to inspect a remote skill's full folder locally before deciding.
+
+## Inputs
+
+Normalize one of these into `(owner, repo, branch, source-path, skill-name)`:
+
+```text
+owner/repo/path/to/skill
+owner/repo/path/to/skill/SKILL.md
+https://github.com/<owner>/<repo>/tree/<branch>/<path>
+https://github.com/<owner>/<repo>/blob/<branch>/<path>/SKILL.md
+```
+
+- Strip trailing `SKILL.md` to get the folder.
+- `skill-name` defaults to the final folder segment; allow the user to override.
+
+## Flow
+
+1. Confirm intent with the user: install verbatim, or adapt into a new local skill?
+2. Resolve destination(s) using `references/install-reference.md` — provider(s), scope (user vs project vs custom path), project root if project-scoped, and install mode.
+3. Fetch the source folder with Octocode:
+   - Default: `githubGetFileContent` in directory mode for a single skill folder.
+   - Use `githubCloneRepo` when the skill has many sibling assets or the user wants the whole repo for context.
+   - Stage downloads under a scratch path the user controls (e.g. `/tmp/skill-fetch/<skill-name>/` or a directory the user names); do not write directly into final destinations yet.
+4. Validate the download: the folder contains `SKILL.md` with valid `name` and `description` frontmatter.
+5. Safety scan: read `SKILL.md`, then any `scripts/`, install hooks, or executable helpers. Flag risky behavior to the user before writing.
+6. If adapting (not verbatim):
+   - Build a research synthesis (see §Create A Local Skill From Research in `SKILL.md`).
+   - Draft a new `SKILL.md` with the user's own framing and triggers; reuse only patterns the license allows.
+   - Cite the source skill in the new skill's footer or initial commit message.
+7. Conflict check per destination using `references/install-reference.md` rules; apply the user's per-destination choice (`Overwrite`, `Skip`, `Rename`, `Diff`, `Cancel`).
+8. Write into each destination. Prefer atomic copy. Never symlink a fetched download — symlinks are for stable local sources only.
+9. Verify each destination: `ls "<destination>/<skill-name>/SKILL.md"` succeeds.
+10. Report per-destination success or failure, and how the active runtime picks up the new skill (restart, reload, or auto-scan).
+
+## Cautions
+
+- Do not write fetched `scripts/` or install hooks to disk silently. Flag them to the user before step 8.
+- Do not silently rename the skill folder; if the source name conflicts, ask the user.
+- If the source license is missing or restrictive, surface that before installing or adapting.
+- For adaptations, never copy another skill wholesale unless license and user explicitly allow it.
+
+## Recovery
+
+- Partial download: re-fetch once; if still partial, list missing files and stop.
+- Frontmatter invalid after fetch: do not install; report the gap and ask whether to fix locally before writing.
+- Permission denied on write: ask whether to switch scope (e.g. project to user) or pick a user-writable destination.
+- User changes intent mid-flow (verbatim to adapt, or vice versa): keep the staged download in the scratch path and resume from step 5 or 6.
+- Source moved or 404: re-resolve the path; the skill may have been renamed or moved into a `skills/` subfolder.

package/skills/octocode-search-skill/references/install-reference.md

@@ -0,0 +1,130 @@
+# Install Reference
+
+Use only after the user chooses to install a skill. This reference is provider-agnostic and tool-agnostic. Treat the steps below as a checklist, not a script — skip what does not apply, deepen what does.
+
+## What An Install Is
+
+A skill install is: copy or symlink a folder that contains `SKILL.md` (plus any `references/`, `scripts/`, `assets/`) into a destination that an agent runtime loads at startup. There is no "official" installer. Any method that produces a valid skill folder at a destination the runtime scans is a valid install.
+
+## Inputs Accepted
+
+Normalize any of these to `(source-folder, skill-name)`:
+
+```text
+owner/repo/path/to/skill
+owner/repo/path/to/skill/SKILL.md
+https://github.com/<owner>/<repo>/tree/<branch>/<path>
+https://github.com/<owner>/<repo>/blob/<branch>/<path>/SKILL.md
+/absolute/path/to/skill[/SKILL.md]
+./relative/path/to/skill[/SKILL.md]
+```
+
+Rules:
+
+- Strip trailing `SKILL.md` to get the folder.
+- `skill-name` = final folder segment, unless the user overrides it.
+- If frontmatter `name` differs from folder name, surface the mismatch and ask.
+
+## Destinations: Provider Scopes
+
+Most agents load skills from at least two scopes: a user-level scope (applies everywhere) and a project-level scope (applies to one repo / workspace). Some agents also honor a custom path via env var or config.
+
+Use this matrix as a default — verify with the active runtime when the user is unsure.
+
+| Provider       | User scope (global)                            | Project scope (per-repo)   | Custom override                    |
+|----------------|------------------------------------------------|----------------------------|------------------------------------|
+| claude-code    | `~/.claude/skills/`                            | `<repo>/.claude/skills/`   | env or config `skillsDestDir`      |
+| claude-desktop | `~/.claude-desktop/skills/`                    | n/a                        | runtime config dir                 |
+| cursor         | `~/.cursor/skills/`                            | `<repo>/.cursor/skills/`   | runtime config                     |
+| codex          | `~/.codex/skills/`                             | `<repo>/.codex/skills/`    | runtime config                     |
+| opencode       | `~/.opencode/skills/`                          | `<repo>/.opencode/skills/` | runtime config                     |
+| other / custom | any directory the runtime scans                | any in-repo path           | user-supplied absolute path        |
+
+Windows equivalents replace `~` with `%USERPROFILE%` (or `%APPDATA%` for desktop apps). Project-scope paths are identical relative to the repo root.
+
+Project scope is the right default when the skill is repo-specific (commit conventions, codebase quirks, internal CLIs). User scope is the right default when the skill is generally useful across all your work.
+
+## Required User Gates
+
+Before any write, ask the user the four destination questions. Skip a question only when the user has already answered it in this turn.
+
+1. Which provider(s)? — one, several, or "all agents". Multi-select is allowed; each target may end up in a different folder.
+2. Which scope for each provider? — user (global) vs project (per-repo) vs custom path. Ask per provider; do not assume one answer covers all.
+3. If project scope: which project root? — confirm the absolute path; never guess from `cwd` alone if the workspace is ambiguous.
+4. Install mode? — copy (default) or symlink (only when the source is a stable local folder the user controls).
+
+If the source has `scripts/`, install hooks, postinstall logic, or executable helpers, also ask: "Inspect scripts before install?" Default yes for third-party sources.
+
+Recommended structured ask when the runtime provides one:
+
+```text
+Where do you want to install <skill-name>?
+
+Provider(s):
+- claude-code
+- claude-desktop
+- cursor
+- codex
+- opencode
+- custom path
+
+Scope (per provider):
+- User (global) — applies everywhere
+- Project (this repo) — applies only here; provide repo root
+- Custom — provide absolute path
+
+Install mode:
+- Copy (recommended)
+- Symlink (only for stable local sources)
+```
+
+## Conflict Handling
+
+For every resolved destination, check for an existing folder before writing:
+
+```bash
+ls "<destination>/<skill-name>" 2>/dev/null
+```
+
+Ask per-destination when a conflict is found:
+
+- `Overwrite` — replace the existing folder.
+- `Skip` — leave existing in place, skip this destination only.
+- `Rename` — install under a different `skill-name` (e.g. `<skill-name>-2`).
+- `Diff` — show what differs before deciding.
+- `Cancel` — abort the whole install.
+
+Never silently overwrite. Never assume one conflict choice applies to all destinations.
+
+## Install Checklist
+
+Run only the items that fit the situation; do not force every step.
+
+- Source resolved: folder contains a valid `SKILL.md` with `name` and `description` frontmatter.
+- Safety scan: read `SKILL.md` and any `scripts/`, install hooks, or executable helpers; flag risky behavior to the user.
+- Destinations confirmed: provider(s), scope(s), and final absolute path(s) shown to the user.
+- Conflict check: per destination.
+- Approval: explicit user confirmation to proceed.
+- Fetch (remote sources only): download the source folder with the directory-mode tool of the active runtime; verify `SKILL.md` is present locally before copying.
+- Write: copy (or symlink) into each destination. Prefer atomic copy when supported.
+- Verify: `ls "<destination>/<skill-name>/SKILL.md"` for every destination; report per-destination success or failure.
+- Post-install hint (optional): tell the user how the active agent picks up new skills (restart, reload, or auto-scan).
+
+## Symlink Notes
+
+Use symlinks only when all of these hold:
+
+- Source is a stable local path the user controls (not a temp clone, not a remote download).
+- User explicitly wants edits in source to reflect immediately.
+- Destination runtime supports symlinked skill folders.
+
+Otherwise, prefer copy.
+
+## Recovery
+
+- Destination does not exist yet: create the parent directory after explicit approval; do not auto-create deep custom paths.
+- Permission denied: report the path and ask whether to try a different scope or a user-writable destination.
+- Partial multi-target install: report which destinations succeeded and which failed; never roll back other targets without asking.
+- Remote download incomplete: re-fetch once; if still incomplete, stop and report missing files.
+- Frontmatter invalid: do not install; explain the gap.
+- Unknown provider: treat as `custom path`; ask for an absolute destination and confirm the runtime scans it.

package/skills/octocode-search-skill/references/references-template.md

@@ -0,0 +1,27 @@
+# References
+
+Sources consulted to research and create this skill.
+
+## Skills.sh API Results
+<!-- Top candidates from skills.sh API search, sorted by installs descending -->
+| Skill | Source | Installs | Used for |
+|-------|--------|----------|----------|
+| <skillId> | <owner/repo> | <installs> | <what pattern was borrowed or why inspected> |
+
+## GitHub Sources Inspected
+<!-- SKILL.md files read via Octocode -->
+| File | Owner/Repo | Path | Quality | Notes |
+|------|-----------|------|---------|-------|
+| <name> | <owner/repo> | <path> | High/Medium/Low | <what was taken or rejected> |
+
+## Registry and Marketplace Surfaces
+<!-- Other surfaces consulted -->
+| Surface | URL or Query | Finding |
+|---------|-------------|---------|
+| <surface name> | <url or query used> | <what was found> |
+
+## Local Sources
+<!-- Local files or skills consulted -->
+| File | Path | Notes |
+|------|------|-------|
+| <name> | <absolute path> | <what was used> |

package/skills/octocode-search-skill/references/references.md

@@ -0,0 +1,62 @@
+# References
+
+Sources actually consulted to research and create the `octocode-search-skill`.
+
+## Skills.sh API Results
+
+Live queries run during creation, sorted by installs descending.
+
+**Query: `code review`** (used to validate API response shape)
+
+| Skill | Source | Installs | Used for |
+|-------|--------|----------|----------|
+| requesting-code-review | obra/superpowers | 88,768 | Gate and output UX patterns |
+| receiving-code-review | obra/superpowers | 70,328 | Workflow step structure |
+| code-review-excellence | wshobson/agents | 18,559 | Card output format reference |
+
+**Query: `skill search agent`** (used to survey the discovery-skill landscape)
+
+| Skill | Source | Installs | Used for |
+|-------|--------|----------|----------|
+| parallel-deep-research | parallel-web/parallel-agent-skills | 8,186 | Parallel research pattern |
+| parallel-web-search | parallel-web/parallel-agent-skills | 7,844 | Parallel search pattern |
+| skills-search | daymade/claude-code-skills | 398 | Direct competitor — inspected for gap analysis |
+
+**Query: `find skills install`** (used to find meta-skill patterns)
+
+| Skill | Source | Installs | Used for |
+|-------|--------|----------|----------|
+| find-skills | bytedance/deer-flow | 1,349 | Meta-skill discovery pattern (duplicate of vercel-labs canonical) |
+| installing-skills | oaustegard/claude-skills | 40 | Install flow reference |
+
+## GitHub Sources Inspected
+
+SKILL.md files read via Octocode during design.
+
+| File | Owner/Repo | Path | Quality | Notes |
+|------|-----------|------|---------|-------|
+| find-skills | vercel-labs/skills | skills/find-skills/SKILL.md | High | Discovery workflow and gate UX patterns |
+| skill-creator | anthropics/skills | skills/skill-creator/SKILL.md | High | Creation flow and resource structure |
+| brainstorming | obra/superpowers | brainstorming/SKILL.md | High | Research synthesis and recommend pattern |
+| skills-search | daymade/claude-code-skills | skills-search/SKILL.md | Medium | Gap analysis — minimal workflow, no gates |
+
+## Registry and Marketplace Surfaces
+
+| Surface | Query or URL | Finding |
+|---------|-------------|---------|
+| skills.sh API | `/api/search?q=code+review&limit=10` | Confirmed response shape: `{"skills":[...], "count": N}` with `installs`, `source`, `skillId` |
+| skills.sh API | `/api/search?q=skill+search+agent&limit=20` | Identified `daymade/claude-code-skills/skills-search` as closest existing competitor |
+| skills.sh API | `/api/search?q=find+skills+install&limit=20` | Confirmed `find-skills` pattern; canonical at vercel-labs, widely forked |
+| agentskills.io | `agentskills.io/llms.txt` | Agent-readable catalog format; confirmed compatible-agents list |
+| aiskillstore.io | `aiskillstore.io/llms.txt` | USK v1.0 spec; capability tag taxonomy and API surface |
+| claude-plugins.dev | Web UI | Auto-indexed GitHub SKILL.md discovery; confirm-before-install pattern |
+| microsoft.github.io/skills | `llms-full.txt` | Sensei scoring rubric (triggers + anti-triggers + compatibility) |
+
+## Local Sources
+
+| File | Path | Notes |
+|------|------|-------|
+| agent-skills-guide.md | references/agent-skills-guide.md | Quality rubric, progressive disclosure pattern, description optimization |
+| discovery-surfaces.md | references/discovery-surfaces.md | Marketplace surface catalog; routing table |
+| install-reference.md | references/install-reference.md | 4-gate install protocol; provider matrix |
+| fetch-and-create-locally.md | references/fetch-and-create-locally.md | Remote-to-local fetch and adapt workflow |