octocode-cli 1.3.0 → 1.5.0

package/skills/octocode-research/src/routes/github.ts

@@ -19,16 +19,17 @@ import {
   githubStructureSchema,
   githubPRsSchema,
 } from '../validation/index.js';
-import { ResearchResponse, QuickResult, detectLanguageFromPath } from '../utils/responseBuilder.js';
+import { ResearchResponse, QuickResult } from '../utils/responseBuilder.js';
 import { withGitHubResilience } from '../utils/resilience.js';
 import { createRouteHandler } from '../utils/routeFactory.js';
+import { transformFileContentResponse } from '../utils/fileContentTransform.js';
 import {
   safeString,
   safeNumber,
   safeArray,
   transformPagination,
 } from '../utils/responseFactory.js';
-import { isObject, hasProperty, hasNumberProperty, hasBooleanProperty } from '../types/guards.js';
+import { isObject, hasProperty, hasNumberProperty } from '../types/guards.js';
 
 export const githubRoutes = Router();
 
@@ -75,25 +76,7 @@ githubRoutes.get(
     toolFn: githubGetFileContent,
     toolName: 'githubGetFileContent',
     resilience: withGitHubResilience,
-    transform: (parsed, queries) => {
-      const { data, hints, research } = parsed;
-
-      return ResearchResponse.fileContent({
-        path: safeString(data, 'path', queries[0]?.path || 'unknown'),
-        content: safeString(data, 'content'),
-        lines: hasNumberProperty(data, 'startLine')
-          ? {
-              start: data.startLine,
-              end: hasNumberProperty(data, 'endLine') ? data.endLine : data.startLine,
-            }
-          : undefined,
-        language: detectLanguageFromPath(queries[0]?.path || ''),
-        totalLines: hasNumberProperty(data, 'totalLines') ? data.totalLines : undefined,
-        isPartial: hasBooleanProperty(data, 'isPartial') ? data.isPartial : undefined,
-        mcpHints: hints,
-        research,
-      });
-    },
+    transform: transformFileContentResponse,
   })
 );
 

package/skills/octocode-research/src/routes/local.ts

@@ -17,9 +17,10 @@ import {
   localFindSchema,
   localStructureSchema,
 } from '../validation/index.js';
-import { ResearchResponse, detectLanguageFromPath } from '../utils/responseBuilder.js';
+import { ResearchResponse } from '../utils/responseBuilder.js';
 import { withLocalResilience } from '../utils/resilience.js';
 import { createRouteHandler } from '../utils/routeFactory.js';
+import { transformFileContentResponse } from '../utils/fileContentTransform.js';
 import {
   safeString,
   safeNumber,
@@ -27,7 +28,7 @@ import {
   extractMatchLocations,
   transformPagination,
 } from '../utils/responseFactory.js';
-import { isObject, hasNumberProperty, hasBooleanProperty } from '../types/guards.js';
+import { isObject, hasNumberProperty } from '../types/guards.js';
 
 export const localRoutes = Router();
 
@@ -74,25 +75,7 @@ localRoutes.get(
     toolFn: localGetFileContent,
     toolName: 'localGetFileContent',
     resilience: withLocalResilience,
-    transform: (parsed, queries) => {
-      const { data, hints, research } = parsed;
-
-      return ResearchResponse.fileContent({
-        path: safeString(data, 'path', queries[0]?.path || 'unknown'),
-        content: safeString(data, 'content'),
-        lines: hasNumberProperty(data, 'startLine')
-          ? {
-              start: data.startLine,
-              end: hasNumberProperty(data, 'endLine') ? data.endLine : data.startLine,
-            }
-          : undefined,
-        language: detectLanguageFromPath(queries[0]?.path || ''),
-        totalLines: hasNumberProperty(data, 'totalLines') ? data.totalLines : undefined,
-        isPartial: hasBooleanProperty(data, 'isPartial') ? data.isPartial : undefined,
-        mcpHints: hints,
-        research,
-      });
-    },
+    transform: transformFileContentResponse,
   })
 );
 

package/skills/octocode-research/src/utils/fileContentTransform.ts

@@ -0,0 +1,44 @@
+import type { ParsedResponse } from './responseParser.js';
+import {
+  ResearchResponse,
+  detectLanguageFromPath,
+} from './responseBuilder.js';
+import { safeString } from './responseFactory.js';
+import {
+  hasBooleanProperty,
+  hasNumberProperty,
+} from '../types/guards.js';
+
+type FileContentQuery = {
+  path?: string;
+};
+
+export function transformFileContentResponse(
+  parsed: ParsedResponse,
+  queries: FileContentQuery[]
+): ReturnType<typeof ResearchResponse.fileContent> {
+  const { data, hints, research } = parsed;
+  const path = queries[0]?.path || '';
+
+  return ResearchResponse.fileContent({
+    path: safeString(data, 'path', path || 'unknown'),
+    content: safeString(data, 'content'),
+    lines: hasNumberProperty(data, 'startLine')
+      ? {
+          start: data.startLine,
+          end: hasNumberProperty(data, 'endLine')
+            ? data.endLine
+            : data.startLine,
+        }
+      : undefined,
+    language: detectLanguageFromPath(path),
+    totalLines: hasNumberProperty(data, 'totalLines')
+      ? data.totalLines
+      : undefined,
+    isPartial: hasBooleanProperty(data, 'isPartial')
+      ? data.isPartial
+      : undefined,
+    mcpHints: hints,
+    research,
+  });
+}

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

@@ -0,0 +1,337 @@
+---
+name: octocode-search-skill
+description: Use this skill when the user asks to find, evaluate, preview, install, rate, review, score, improve, refactor, or synthesize Agent Skills (the `SKILL.md` folder format) across GitHub, local skill folders, and skill marketplaces. Covers searching for a skill for a task, deep-diving a candidate, installing one or more skills into one or more agents at user or project scope, rating or reviewing an existing SKILL.md, refactoring a skill, or creating a new local skill from researched patterns. Do NOT activate for general package search (npm, PyPI, cargo), web search, or code research not involving SKILL.md files.
+---
+
+# 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`.
+
+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.
+
+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/<name>/SKILL.md`, `.agents/skills/<name>/SKILL.md`.
+- Probe plugin manifests: `.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, and per-catalog `llms.txt` / `llms-full.txt` files for batch discovery.
+
+### Skills.sh Registry API
+
+MUST run this in parallel with GitHub/Octocode search for every public skill query. MUST NOT use for org-specific or private searches — use Octocode tools only for those.
+
+```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 shape: `{"skills": [{"id": string, "skillId": string, "name": string, "installs": number, "source": "owner/repo"}, ...], "count": number}`
+
+Popularity workflow — MUST follow this order:
+
+1. Sort results by `installs` descending — highest install count = most battle-tested signal.
+2. Take the top 5 candidates by installs as priority inspection targets.
+3. In parallel with other searches, fetch each top candidate's `SKILL.md` via Octocode (`githubGetFileContent` using `source` as `owner/repo`; try paths `skills/<skillId>/SKILL.md`, `<skillId>/SKILL.md`, `.claude/skills/<skillId>/SKILL.md`).
+4. Include install count in every result card as a quality signal.
+5. MUST NOT blindly recommend the highest-install skill — inspect content and task fit first; use `installs` as a tiebreaker only when two candidates are otherwise equal.
+
+Fallback: if the API is unreachable or rate-limited, switch to `https://www.skills.sh` leaderboard page and GitHub topic search; lower confidence and continue.
+
+Marketplace and registry surfaces (see `references/discovery-surfaces.md` for the full list and APIs):
+
+- Per-skill check: `https://www.skills.sh/<owner>/<repo>/<skill-name>` — install count, install command, security audit status.
+- Leaderboard: `https://www.skills.sh` — install-count ranked, agent-filtered.
+- Additional registries: `agentskills.io/llms.txt`, `aiskillstore.io/llms.txt`, `microsoft.github.io/skills/llms-full.txt`; `claude-plugins.dev` REST for Claude Code plugin search.
+
+Seed only when discovery is sparse. Start from `topic:agent-skills` (or the narrower `topic:claude-code-skills`) on GitHub, then sample well-maintained collections such as `anthropics/skills`, `ComposioHQ/awesome-claude-skills`, `addyosmani/agent-skills`, `vercel-labs/skills`, `alirezarezvani/claude-skills`, `microsoft/skills`, `obra/superpowers`, `trailofbits/skills`, `wshobson/claude-code-workflows`, or any author-curated marketplace the user trusts.
+
+## Judge Quality
+
+For every plausible candidate, inspect enough `SKILL.md` content to understand behavior. For strong, risky, or ambiguous candidates, inspect full `SKILL.md` plus referenced scripts, templates, install docs, evals, or reference files that affect execution.
+
+Evaluate:
+
+- Trigger: clear activation conditions and non-activation boundaries.
+- Workflow: ordered steps, decision points, recovery paths, and stop conditions.
+- Evidence: real file contents, referenced resources, tests, examples, or scripts.
+- Gates: validation, approval, preview, review, permissions, rollback, and install conflict handling.
+- Output UX: concise results, useful comparison cards, explicit next-step gate.
+- Specificity: domain knowledge an agent would not know by default.
+- Portability: agent/runtime assumptions, hardcoded paths, external services, dependencies, secrets.
+- Risk: unsafe commands, hidden network actions, missing referenced files, license ambiguity, stale docs, broad triggers.
+
+Quality labels:
+
+- `High`: direct match, clear trigger, executable workflow, useful resources and gates, and no obvious safety or portability red flags.
+- `Medium`: partial match or adaptable, but missing some validation, UX, or domain detail.
+- `Low`: keyword-only match, generic workflow, unclear trigger, stale pattern, or meaningful caveat.
+
+For evidence-based quality signals beyond stars (install counts, recency, audit badges, capability overlap, demand signals), load `references/agent-skills-guide.md` §Quality Signals Beyond Stars and `references/discovery-surfaces.md` §Quality Signals Beyond Stars.
+
+## Self-Improvement Mode
+
+Use this mode when the user asks to rate, review, score, improve, or refactor a `SKILL.md` — yours or someone else's. Read `references/agent-skills-guide.md` before rating or rewriting.
+
+Modes — pick one before starting. If the user's request is ambiguous (e.g., "check my skill"), present this gate before proceeding:
+
+```text
+Which mode?
+1. Rate-only — score and report issues; no file edits.
+2. Improve / refactor — fix issues and rewrite; gate before writing.
+3. Fix all — apply fixes from a prior rating in this conversation; skip re-rating.
+4. Cancel.
+```
+
+- `Rate-only` (rate, review, score, audit): stop after the REPORT step. MUST NOT edit files. End with a numbered next-action gate (apply fixes, show diff, cancel).
+- `Improve` / `refactor` / `rewrite`: full flow including REWRITE and VALIDATE; gate before writing.
+- `Fix all` / `apply fixes`: skip MAP INTENT and RATE ISSUES if a prior rating exists in the conversation; go straight to REWRITE → VALIDATE → REPORT.
+
+Flow:
+
+```text
+READ -> MAP INTENT -> RATE ISSUES -> [REWRITE -> VALIDATE] -> REPORT
+```
+
+Read:
+
+- Read the full target `SKILL.md` and all referenced files that affect behavior.
+- Note purpose, line count, resources, gates, and output format.
+
+Map intent:
+
+- Preserve the skill's core job, trigger domain, and user-facing promises.
+- Identify what behavior must become more reliable: activation, research quality, safety gates, tool routing, output shape, or recovery.
+
+Rate issues:
+
+- Check for weak rules in critical sections, vague actions, raw-search handoff, missing gates, unsafe writes, missing verification, stale references, and line-count bloat.
+- Group findings by severity: `Critical`, `High`, `Medium`, `Low`. Cite `file:line` for each.
+- Score per dimension using the §Judge Quality rubric (`High` / `Medium` / `Low`).
+
+Rewrite (skip in Rate-only mode):
+
+- Fix Critical and High issues first.
+- Keep `SKILL.md` concise; target 300 lines or less unless the domain justifies more.
+- Move long examples, schemas, or static references into `references/` only when that reduces active-context load.
+- Keep `description` trigger-rich without keyword stuffing.
+
+Validate (skip in Rate-only mode):
+
+- Frontmatter has valid `name` and `description`.
+- Workflow has clear steps, gates, recovery, and output UX.
+- Referenced files exist or missing files are documented as risks.
+- Critical actions use MUST/NEVER/FORBIDDEN where needed.
+- No write/install action bypasses an explicit user gate.
+
+Report — required output shape for `Rate-only`:
+
+```text
+Overall:        <score>/10 — <letter grade> (one-sentence summary).
+Score card:     per-dimension High/Medium/Low using §Judge Quality.
+Issues:         grouped Critical / High / Medium / Low, each with file:line.
+Validation:     pass/fail per checklist item above.
+Strengths:      2-4 bullets worth preserving.
+Residual risk:  1-3 bullets.
+Next action:    numbered choices ending with "Cancel".
+```
+
+Report — for `Improve` / `Fix all`:
+
+- Summarize intent preserved, major fixes applied, validation result, and any residual risk.
+
+## Present Results
+
+Lead with the recommendation in one sentence. Then group results only when useful:
+
+- `Best matches`
+- `Useful alternatives`
+- `Explore if...`
+
+If results are few, show compact cards. If results are many, list confirmed names and sources compactly and provide detailed cards only for the strongest candidates.
+
+Card shape (label layout, not literal Markdown):
+
+```text
+Name:            <skill-name>  - fit: High | Medium | Low
+Source:          <owner/repo path-to-SKILL.md> or <local path>
+What it does:    <one sentence in your own words>
+Actual flow:     <2-4 short steps from inspected content>
+Quality signals: <specific evidence>
+Why it matches:  <tie to user's request>
+Caveat:          <real risk, or "None obvious from inspected files">
+```
+
+Keep prose short. Do not paste raw search dumps or large excerpts.
+
+End with a user gate that offers the real next branches — not just "install or cancel". Use a structured ask tool when the runtime provides one; otherwise present concise numbered choices and wait.
+
+Gate example:
+
+```text
+Recommended: <skill-name> from <source>
+
+Choose:
+1. Install — fetch into one or more agent destinations the user picks (see references/install-reference.md and references/fetch-and-create-locally.md).
+2. Create a local skill — adapt patterns from this candidate into a new local SKILL.md.
+3. Explain — break down trigger, workflow, gates, and risks.
+4. Show link — return the source URL or local path only, no write.
+5. Compare — line up against another candidate.
+6. Keep researching.
+7. Cancel.
+```
+
+## Deep-Dive
+
+When the user picks a skill:
+
+1. Fetch full `SKILL.md`.
+2. Fetch directly referenced files that affect behavior.
+3. Summarize trigger, workflow, support files, validation and safety gates, strengths, gaps, and adaptation ideas.
+4. Ask whether to install, adapt into a local skill, compare, or keep researching.
+
+## Create A Local Skill From Research
+
+Use this when the user chooses to create a skill from findings or asks to synthesize one. Read `references/agent-skills-guide.md` before planning. If the source is a remote skill being fetched into a local folder, also read `references/fetch-and-create-locally.md`.
+
+Before writing files:
+
+1. Build a research synthesis:
+   - User need and constraints.
+   - Inspected source skills and useful patterns.
+   - Quality and UX gates to include.
+   - Resources to create, if any.
+   - Exclusions: copied, generic, risky, or unnecessary pieces.
+2. Present a short plan:
+   - Skill name and destination.
+   - Trigger description draft.
+   - Workflow outline.
+   - Resources and validation plan.
+3. Ask for approval with create, adjust, inspect more, or cancel options.
+
+After approval, write the skill with concise purpose, workflow, tool and resource rules, gates, output UX, and recovery paths. Add `references/`, `scripts/`, or `assets/` only when they reduce repeated work or keep `SKILL.md` lean. Defer to a dedicated skill-creation skill when one is available.
+
+MUST also create `references/references.md` inside the new skill folder using the shape in `references/references-template.md`. Populate it with every source actually consulted — do not list sources that were not checked. This file is a research audit trail, not a bibliography template.
+
+## Install
+
+Read `references/install-reference.md` before installing. Keep install behavior gated and verified. The reference is provider-agnostic; do not hardcode a destination.
+
+Minimum install gates:
+
+1. Normalize input to a skill folder containing a valid `SKILL.md`.
+2. MUST ask the user where to install before writing anything. Cover all four destination questions: provider(s), scope per provider (user vs project vs custom path), project root if project scope, and install mode (copy vs symlink). Never assume one answer applies to every provider.
+3. Inspect `scripts/`, install hooks, or executable helpers before copying third-party skills.
+4. Per-destination conflict check; ask `Overwrite`, `Skip`, `Rename`, `Diff`, or `Cancel` for each conflict.
+5. Show source, description, every resolved destination path, install mode, and conflict plan; require explicit confirmation.
+6. Prefer copy; use symlink only for stable local sources when the user wants live source-tracking.
+7. Verify installed `SKILL.md` exists in each destination and report per-destination success or failure.
+
+For remote sources, follow the fetch-and-write workflow in `references/fetch-and-create-locally.md`.
+
+## Recovery
+
+- No results: broaden terms once, inspect repo roots, or fall back to seed collections.
+- Too many generic results: narrow by domain, agent, tool, workflow verb, or safety requirement.
+- Strong repo but no skill path: browse root, `skills/`, `.claude/skills/`, `.cursor/skills/`, then category folders.
+- Missing frontmatter: skip the candidate.
+- Missing referenced files: lower confidence and mention the gap.
+- Unsafe behavior: do not recommend install; explain the risk and offer a safer adaptation.
+- Marketplace per-skill URL 404 (e.g. `https://www.skills.sh/<owner>/<repo>/<skill-name>`): the skill is not in that public index. Fall back to the source repo and lower confidence.
+- Registry API rate-limit or 5xx: switch to `llms.txt` / `llms-full.txt` snapshot or to GitHub topic search; see `references/discovery-surfaces.md` §Recovery.
+- Manifest file expected but missing (`.claude-plugin/marketplace.json`, `llms.txt`): note the gap as a quality signal and continue from raw `SKILL.md` evidence.
+- Tool or API unavailable: state what evidence is missing, map the failed verb to an alternative runtime tool when one exists, and ask the user whether to switch source, drop to a fallback, or stop.

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.