octocode-cli 1.3.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) hide show
  1. package/README.md +129 -28
  2. package/out/chunks/chunk-7476PETK.js +309 -0
  3. package/out/chunks/chunk-CVNNNSMQ.js +26 -0
  4. package/out/chunks/chunk-OQBJTZWK.js +60 -0
  5. package/out/chunks/chunk-UCZCF3BQ.js +9 -0
  6. package/out/chunks/command-help-specs-JZXVSLZ5.js +8 -0
  7. package/out/chunks/commands-XBFPLHSQ.js +8 -0
  8. package/out/chunks/help-P7TCOYAJ.js +10 -0
  9. package/out/chunks/main-help-ULF5PAQY.js +10 -0
  10. package/out/chunks/prompts-5E6VKRX5.js +8 -0
  11. package/out/chunks/spinner-URV2OX6O.js +8 -0
  12. package/out/chunks/tool-command-M6VA7P2F.js +8 -0
  13. package/out/octocode-cli.js +1 -1
  14. package/package.json +5 -3
  15. package/skills/README.md +60 -58
  16. package/skills/agentic-flow-best-practices/SKILL.md +280 -0
  17. package/skills/agentic-flow-best-practices/references/agent-collaboration-patterns.md +75 -0
  18. package/skills/agentic-flow-best-practices/references/pr-review-agent-example.md +47 -0
  19. package/skills/agentic-flow-best-practices/references/resources.md +112 -0
  20. package/skills/octocode-brainstorming/.env.example +11 -0
  21. package/skills/octocode-brainstorming/SKILL.md +262 -0
  22. package/skills/octocode-brainstorming/scripts/tavily-search.mjs +138 -0
  23. package/skills/octocode-chrome-devtools/README.md +541 -0
  24. package/skills/octocode-chrome-devtools/SKILL.md +197 -0
  25. package/skills/octocode-chrome-devtools/agents/openai.yaml +7 -0
  26. package/skills/octocode-chrome-devtools/references/CDP_AGENT_REFERENCE.md +401 -0
  27. package/skills/octocode-chrome-devtools/references/CHROME_FLAGS.md +234 -0
  28. package/skills/octocode-chrome-devtools/references/INTENTS.md +108 -0
  29. package/skills/octocode-chrome-devtools/references/INTENTS_AUTH.md +179 -0
  30. package/skills/octocode-chrome-devtools/references/INTENTS_AUTOMATION.md +214 -0
  31. package/skills/octocode-chrome-devtools/references/INTENTS_DEBUG.md +329 -0
  32. package/skills/octocode-chrome-devtools/references/INTENTS_ENVIRONMENT.md +237 -0
  33. package/skills/octocode-chrome-devtools/references/INTENTS_INSPECT.md +263 -0
  34. package/skills/octocode-chrome-devtools/references/INTENTS_STORAGE_CONSENT.md +214 -0
  35. package/skills/octocode-chrome-devtools/references/RECOVERY.md +39 -0
  36. package/skills/octocode-chrome-devtools/references/SCRIPT_PATTERNS.md +43 -0
  37. package/skills/octocode-chrome-devtools/references/SCRIPT_PATTERNS_ASYNC_WORKERS.md +345 -0
  38. package/skills/octocode-chrome-devtools/references/SCRIPT_PATTERNS_BROWSER.md +403 -0
  39. package/skills/octocode-chrome-devtools/references/SCRIPT_PATTERNS_OBSERVE.md +275 -0
  40. package/skills/octocode-chrome-devtools/references/SCRIPT_PATTERNS_SPECIAL.md +18 -0
  41. package/skills/octocode-chrome-devtools/scripts/cdp-runner.mjs +503 -0
  42. package/skills/octocode-chrome-devtools/scripts/cdp-sandbox.mjs +123 -0
  43. package/skills/octocode-chrome-devtools/scripts/cdp-template.mjs +81 -0
  44. package/skills/octocode-chrome-devtools/scripts/octocode-chrome-devtools.vpn.example.json +8 -0
  45. package/skills/octocode-chrome-devtools/scripts/open-browser.mjs +362 -0
  46. package/skills/octocode-chrome-devtools/scripts/sourcemap-resolver.mjs +193 -0
  47. package/skills/octocode-chrome-devtools/scripts/undercover.mjs +226 -0
  48. package/skills/octocode-design/README.md +2 -2
  49. package/skills/octocode-documentation-writer/README.md +1 -1
  50. package/skills/octocode-engineer/README.md +1 -1
  51. package/skills/octocode-engineer/SKILL.md +137 -306
  52. package/skills/octocode-engineer/references/cli-reference.md +13 -0
  53. package/skills/octocode-engineer/references/output-files.md +3 -3
  54. package/skills/octocode-engineer/scripts/run.js +146 -146
  55. package/skills/octocode-engineer/src/pipeline/main.ts +1 -17
  56. package/skills/octocode-engineer/src/pipeline/progress.ts +4 -0
  57. package/skills/octocode-engineer/src/reporting/summary-md.test.ts +48 -0
  58. package/skills/octocode-engineer/src/reporting/summary-md.ts +43 -2
  59. package/skills/octocode-install/SKILL.md +1 -1
  60. package/skills/octocode-pull-request-reviewer/README.md +5 -5
  61. package/skills/octocode-pull-request-reviewer/SKILL.md +1 -1
  62. package/skills/octocode-research/AGENTS.md +1 -1
  63. package/skills/octocode-research/README.md +2 -2
  64. package/skills/octocode-research/docs/ARCHITECTURE.md +1 -1
  65. package/skills/octocode-research/scripts/server.js +184 -239
  66. package/skills/octocode-research/src/routes/github.ts +4 -21
  67. package/skills/octocode-research/src/routes/local.ts +4 -21
  68. package/skills/octocode-research/src/utils/fileContentTransform.ts +44 -0
  69. package/skills/octocode-search-skill/SKILL.md +337 -0
  70. package/skills/octocode-search-skill/references/agent-skills-guide.md +177 -0
  71. package/skills/octocode-search-skill/references/discovery-surfaces.md +162 -0
  72. package/skills/octocode-search-skill/references/fetch-and-create-locally.md +57 -0
  73. package/skills/octocode-search-skill/references/install-reference.md +130 -0
  74. package/skills/octocode-search-skill/references/references-template.md +27 -0
  75. package/skills/octocode-search-skill/references/references.md +62 -0
  76. package/skills/octocode-slides/README.md +307 -0
  77. package/skills/octocode-slides/SKILL.md +410 -0
  78. package/skills/octocode-slides/references/01-brief.md +156 -0
  79. package/skills/octocode-slides/references/02-research.md +149 -0
  80. package/skills/octocode-slides/references/03-outline.md +172 -0
  81. package/skills/octocode-slides/references/04-design.md +301 -0
  82. package/skills/octocode-slides/references/05-implementation.md +213 -0
  83. package/skills/octocode-slides/references/06-review.md +258 -0
  84. package/skills/octocode-slides/references/animation.md +281 -0
  85. package/skills/octocode-slides/references/design-system.md +316 -0
  86. package/skills/octocode-slides/references/html-templates.md +673 -0
  87. package/skills/octocode-slides/references/image-generation.md +448 -0
  88. package/skills/octocode-slides/references/resources.md +840 -0
  89. package/skills/octocode-slides/references/slide-rules.md +541 -0
  90. package/skills/octocode-slides/references/wireframes.md +727 -0
  91. package/skills/octocode-slides/scripts/animation.js +182 -0
  92. package/skills/octocode-slides/scripts/base.css +353 -0
  93. package/skills/octocode-slides/scripts/base.html +655 -0
  94. package/skills/octocode-slides/scripts/generate_image.py +221 -0
  95. package/skills/octocode-slides/scripts/navbridge.js +79 -0
  96. package/skills/octocode-slides/scripts/presenter.js +316 -0
  97. package/skills/octocode-slides/scripts/slide.html +248 -0
  98. package/skills/octocode-stats/SKILL.md +73 -0
  99. package/skills/octocode-stats/assets/template.html +1332 -0
  100. package/skills/octocode-stats/scripts/build_dashboard.mjs +407 -0
  101. package/out/chunks/chunk-LH4AZJPA.js +0 -389
  102. package/out/chunks/command-help-specs-CQ3RBLP6.js +0 -8
  103. package/out/chunks/commands-M3QTWKWE.js +0 -51
  104. package/out/chunks/help-XPXP46ZT.js +0 -10
  105. package/out/chunks/main-help-HXFAFHPG.js +0 -10
  106. package/out/chunks/tool-command-VHFLPIHY.js +0 -8
@@ -0,0 +1,162 @@
1
+ # Discovery Surfaces
2
+
3
+ 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).
4
+
5
+ ## Quick Routing
6
+
7
+ | User goal | Best first surface |
8
+ |-----------|--------------------|
9
+ | "Search skills by keyword or topic" | skills.sh Registry API (`/api/search?q=...`) — sort by `installs` |
10
+ | "Is skill X published / battle-tested?" | `https://www.skills.sh/<owner>/<repo>/<skill-name>` |
11
+ | "What are the most-installed skills right now?" | `https://www.skills.sh` leaderboard |
12
+ | "Find a Claude Code plugin" | `claude-plugins.dev` (REST + UI) |
13
+ | "Browse curated skills across agents" | `agentskills.me`, `agentskills.io` |
14
+ | "Capability-based search (e.g. web_search, summarization)" | `aiskillstore.io/v1/agent/search?capability=` |
15
+ | "Subscribe to new skills" | `aiskillstore.io/feed/new-skills.json` (JSON Feed) or `.rss` |
16
+ | "Microsoft / Azure ecosystem skills" | `microsoft.github.io/skills` + its `llms-full.txt` |
17
+ | "Claude marketplaces aggregated" | `claudemarketplaces.com`, `mcpmarket.com/tools/skills` |
18
+
19
+ ## Per-Skill Check
20
+
21
+ Before recommending a remote skill, confirm it on at least one public index:
22
+
23
+ ```text
24
+ https://www.skills.sh/<owner>/<repo>/<skill-name>
25
+ ```
26
+
27
+ When the repo is the canonical `skills` repo, the URL collapses to:
28
+
29
+ ```text
30
+ https://www.skills.sh/<org>/skills/<skill-name>
31
+ ```
32
+
33
+ Examples:
34
+
35
+ - `https://www.skills.sh/anthropics/skills/skill-creator`
36
+ - `https://www.skills.sh/vercel-labs/skills/find-skills`
37
+ - `https://www.skills.sh/obra/superpowers/brainstorming`
38
+
39
+ What that page tells you (use as quality signals, not stars):
40
+
41
+ - Install count (battle-test signal stronger than GitHub stars).
42
+ - One-line install command (`npx skills add <repo> --skill <name>`).
43
+ - Security audit status (e.g. "Gen Agent Trust Hub: Pass").
44
+ - Related skills + sibling skills from the same repo.
45
+ - First-seen date and source repository link.
46
+
47
+ 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.
48
+
49
+ ## Marketplace Surfaces
50
+
51
+ Each surface is provider-agnostic unless noted. Treat install counts and audit badges as self-reported by the registry.
52
+
53
+ ### `agentskills.io`
54
+
55
+ - Open standard hub originated by Anthropic.
56
+ - `/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.
57
+ - Agent-readable index: `agentskills.io/llms.txt`.
58
+
59
+ ### `skills.sh` (Vercel Labs)
60
+
61
+ - Public install-count leaderboard.
62
+ - Search box, agent filter ("available for these agents"), per-skill page (see Per-Skill Check above).
63
+ - Install pattern: `npx skills add <github-url> --skill <skill-name>`.
64
+ - **Registry search API** (MUST use for public skill searches, in parallel with GitHub):
65
+ ```bash
66
+ curl 'https://www.skills.sh/api/search?q={{SEARCH_KEY}}&limit=100' \
67
+ --compressed \
68
+ -H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:150.0) Gecko/20100101 Firefox/150.0'
69
+ ```
70
+ Response: `{"skills": [{"id": "owner/repo/skillId", "skillId": string, "name": string, "installs": number, "source": "owner/repo"}], "count": number}`
71
+ Sort results by `installs` descending; top entries are the most battle-tested candidates.
72
+ Do NOT use for org-specific or private searches — Octocode tools only for those.
73
+
74
+ ### `claude-plugins.dev` (Kamalnrf)
75
+
76
+ - Auto-indexes every public Claude Code plugin and `SKILL.md` on GitHub.
77
+ - Web UI + REST API + interactive `npx skills-installer search`.
78
+ - Sortable: Relevance / Most Downloads / Most Stars; filterable by "With Skills".
79
+
80
+ ### `agentskills.me`
81
+
82
+ - Curated 492+ skills directory across Claude Code, Cursor, OpenCode, Codex CLI, Gemini CLI.
83
+ - Sortable: Most Popular / Most Stars / Editor's Pick.
84
+ - Per-tool subpages.
85
+
86
+ ### `aiskillstore.io` (USK v1.0)
87
+
88
+ - Universal Skill Kit registry with full agent-facing REST API.
89
+ - Capability tag search: `/v1/agent/search?capability=<tag>` (e.g. `web_search`, `text_summarization`).
90
+ - Platform filter: OpenClaw / ClaudeCode / Cursor / GeminiCLI / CodexCLI.
91
+ - Trust levels: verified / community / sandbox.
92
+ - BM25 FTS5 full-text search.
93
+ - Similar skills: `/v1/agent/skills/{id}/similar`.
94
+ - Pre-flight: `/v1/skills/{id}/validate` for platform/Python compatibility.
95
+ - Demand signal: `/v1/demand/most-wanted` (zero-result queries — what does not exist yet).
96
+ - Subscriptions: `/feed/new-skills.json` (JSON Feed 1.1), `/feed/new-skills.rss`.
97
+ - Spec: `aiskillstore.io/llms.txt`.
98
+
99
+ ### `microsoft.github.io/skills` + `microsoft/skills`
100
+
101
+ - 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).
102
+ - "Sensei" frontmatter scoring rubric (Low / Medium / High based on triggers + anti-triggers + compatibility).
103
+ - Auto-generated `llms.txt` and `llms-full.txt` (daily-regenerated GitHub Pages).
104
+
105
+ ### Aggregator directories (`moderate` confidence — verify each entry)
106
+
107
+ - `claudemarketplaces.com` — auto-updated directory of Claude marketplaces.
108
+ - `mcpmarket.com/tools/skills` — per-skill install snippets.
109
+ - `cursor.directory/plugins` — Cursor-native plugin/prompt directory.
110
+ - `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).
111
+
112
+ ## Manifest Formats
113
+
114
+ | Format | Where | Use |
115
+ |--------|-------|-----|
116
+ | `agentskills.io/llms.txt` | Standard hub | Agent-readable doc index |
117
+ | `aiskillstore.io/llms.txt` | USK registry | Full v1.0 spec + endpoint catalog |
118
+ | `microsoft.github.io/skills/llms.txt` + `llms-full.txt` | Microsoft catalog | Daily catalog snapshot |
119
+ | `.claude-plugin/marketplace.json` | Per-marketplace repo | Anthropic native marketplace manifest |
120
+ | `.claude-plugin/plugin.json` | Per-plugin repo | Per-plugin manifest |
121
+ | `marketplace.json` (community) | Per-publisher repo | Community publish workflows |
122
+ | `feed/new-skills.json` | aiskillstore.io | JSON Feed 1.1 — new-skill firehose |
123
+ | `feed/new-skills.rss` | aiskillstore.io | RSS 2.0 alternative |
124
+ | 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` |
125
+
126
+ ## CLI Installers
127
+
128
+ These tools combine discovery and install. Always run a safety scan on the source before allowing install.
129
+
130
+ | CLI | Install command | Notes |
131
+ |-----|-----------------|-------|
132
+ | `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`. |
133
+ | `npx skills-installer` (Kamalnrf) | `npx skills-installer install @owner/repo/skill --client <claude-code\|cursor\|vscode>` | Pairs with `claude-plugins.dev`; interactive `search` TUI. |
134
+ | `npx claude-plugins` | `npx claude-plugins install/list/enable/disable` | Plugin marketplace mgmt. |
135
+ | `arctl` (Solo.io agentregistry) | `arctl skill init/publish/pull` | Registry stores skills as Docker Hub images. |
136
+ | `twg skills install` (Atlassian) | `twg skills install --global --agent claude` | Bundles to `~/.agents/skills` + per-agent dirs. |
137
+ | Anthropic native | `/plugin marketplace add owner/repo` then `/plugin install <name>@<marketplace>` | Canonical Claude Code surface. |
138
+ | `bunx skills add` (xixu-me) | `bunx skills add` | Alternate package-manager-style. |
139
+
140
+ ## Quality Signals Beyond Stars
141
+
142
+ - **Install count** (skills.sh leaderboard) — surfaces battle-tested skills the GitHub-stars view misses (e.g. `find-skills`, Lark/Feishu suite).
143
+ - **Recency** — skip skills with no commits in the last 12 months unless the user explicitly wants archival.
144
+ - **Audit badges** — skills.sh shows "Gen Agent Trust Hub" pass/fail; Microsoft uses Sensei scoring.
145
+ - **`match_reasons` + `downloads_7d` + `days_since_update`** — fields exposed by aiskillstore.io for ranking.
146
+ - **Capability overlap** — `aiskillstore.io/v1/agent/skills/{id}/similar` ranks alternatives by tag/category overlap.
147
+
148
+ ## Meta-Skills For Self-Bootstrapping
149
+
150
+ These let an agent search and install skills mid-session without a human:
151
+
152
+ - `find-skills` — discover and install from skills.sh inside an agent session.
153
+ - `agent-skill-discovery` / `skills-discovery` — local discovery helpers.
154
+ - `skill-creator` — Anthropic's create-and-iterate skill (anthropics/skills/skill-creator).
155
+
156
+ ## Recovery
157
+
158
+ - Per-skill URL 404s on skills.sh: the skill is not in the public index. Fall back to the source repo and lower confidence.
159
+ - Registry REST API rate-limits or 5xx: switch to `llms.txt` snapshot or to GitHub topic search.
160
+ - 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.
161
+ - 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.
162
+ - Manifest file expected but missing (`marketplace.json`, `llms.txt`): note the gap as a quality signal and continue from raw `SKILL.md` evidence.
@@ -0,0 +1,57 @@
1
+ # Fetch And Create Locally
2
+
3
+ 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.
4
+
5
+ ## When To Use
6
+
7
+ - User says "install this skill", "add this skill", "fetch this skill", "save this locally", "copy this skill into my project".
8
+ - User wants to adapt a remote skill into their own (`Create A Local Skill From Research` path in `SKILL.md`).
9
+ - User wants to inspect a remote skill's full folder locally before deciding.
10
+
11
+ ## Inputs
12
+
13
+ Normalize one of these into `(owner, repo, branch, source-path, skill-name)`:
14
+
15
+ ```text
16
+ owner/repo/path/to/skill
17
+ owner/repo/path/to/skill/SKILL.md
18
+ https://github.com/<owner>/<repo>/tree/<branch>/<path>
19
+ https://github.com/<owner>/<repo>/blob/<branch>/<path>/SKILL.md
20
+ ```
21
+
22
+ - Strip trailing `SKILL.md` to get the folder.
23
+ - `skill-name` defaults to the final folder segment; allow the user to override.
24
+
25
+ ## Flow
26
+
27
+ 1. Confirm intent with the user: install verbatim, or adapt into a new local skill?
28
+ 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.
29
+ 3. Fetch the source folder with Octocode:
30
+ - Default: `githubGetFileContent` in directory mode for a single skill folder.
31
+ - Use `githubCloneRepo` when the skill has many sibling assets or the user wants the whole repo for context.
32
+ - 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.
33
+ 4. Validate the download: the folder contains `SKILL.md` with valid `name` and `description` frontmatter.
34
+ 5. Safety scan: read `SKILL.md`, then any `scripts/`, install hooks, or executable helpers. Flag risky behavior to the user before writing.
35
+ 6. If adapting (not verbatim):
36
+ - Build a research synthesis (see §Create A Local Skill From Research in `SKILL.md`).
37
+ - Draft a new `SKILL.md` with the user's own framing and triggers; reuse only patterns the license allows.
38
+ - Cite the source skill in the new skill's footer or initial commit message.
39
+ 7. Conflict check per destination using `references/install-reference.md` rules; apply the user's per-destination choice (`Overwrite`, `Skip`, `Rename`, `Diff`, `Cancel`).
40
+ 8. Write into each destination. Prefer atomic copy. Never symlink a fetched download — symlinks are for stable local sources only.
41
+ 9. Verify each destination: `ls "<destination>/<skill-name>/SKILL.md"` succeeds.
42
+ 10. Report per-destination success or failure, and how the active runtime picks up the new skill (restart, reload, or auto-scan).
43
+
44
+ ## Cautions
45
+
46
+ - Do not write fetched `scripts/` or install hooks to disk silently. Flag them to the user before step 8.
47
+ - Do not silently rename the skill folder; if the source name conflicts, ask the user.
48
+ - If the source license is missing or restrictive, surface that before installing or adapting.
49
+ - For adaptations, never copy another skill wholesale unless license and user explicitly allow it.
50
+
51
+ ## Recovery
52
+
53
+ - Partial download: re-fetch once; if still partial, list missing files and stop.
54
+ - Frontmatter invalid after fetch: do not install; report the gap and ask whether to fix locally before writing.
55
+ - Permission denied on write: ask whether to switch scope (e.g. project to user) or pick a user-writable destination.
56
+ - 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.
57
+ - Source moved or 404: re-resolve the path; the skill may have been renamed or moved into a `skills/` subfolder.
@@ -0,0 +1,130 @@
1
+ # Install Reference
2
+
3
+ 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.
4
+
5
+ ## What An Install Is
6
+
7
+ 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.
8
+
9
+ ## Inputs Accepted
10
+
11
+ Normalize any of these to `(source-folder, skill-name)`:
12
+
13
+ ```text
14
+ owner/repo/path/to/skill
15
+ owner/repo/path/to/skill/SKILL.md
16
+ https://github.com/<owner>/<repo>/tree/<branch>/<path>
17
+ https://github.com/<owner>/<repo>/blob/<branch>/<path>/SKILL.md
18
+ /absolute/path/to/skill[/SKILL.md]
19
+ ./relative/path/to/skill[/SKILL.md]
20
+ ```
21
+
22
+ Rules:
23
+
24
+ - Strip trailing `SKILL.md` to get the folder.
25
+ - `skill-name` = final folder segment, unless the user overrides it.
26
+ - If frontmatter `name` differs from folder name, surface the mismatch and ask.
27
+
28
+ ## Destinations: Provider Scopes
29
+
30
+ 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.
31
+
32
+ Use this matrix as a default — verify with the active runtime when the user is unsure.
33
+
34
+ | Provider | User scope (global) | Project scope (per-repo) | Custom override |
35
+ |----------------|------------------------------------------------|----------------------------|------------------------------------|
36
+ | claude-code | `~/.claude/skills/` | `<repo>/.claude/skills/` | env or config `skillsDestDir` |
37
+ | claude-desktop | `~/.claude-desktop/skills/` | n/a | runtime config dir |
38
+ | cursor | `~/.cursor/skills/` | `<repo>/.cursor/skills/` | runtime config |
39
+ | codex | `~/.codex/skills/` | `<repo>/.codex/skills/` | runtime config |
40
+ | opencode | `~/.opencode/skills/` | `<repo>/.opencode/skills/` | runtime config |
41
+ | other / custom | any directory the runtime scans | any in-repo path | user-supplied absolute path |
42
+
43
+ Windows equivalents replace `~` with `%USERPROFILE%` (or `%APPDATA%` for desktop apps). Project-scope paths are identical relative to the repo root.
44
+
45
+ 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.
46
+
47
+ ## Required User Gates
48
+
49
+ Before any write, ask the user the four destination questions. Skip a question only when the user has already answered it in this turn.
50
+
51
+ 1. Which provider(s)? — one, several, or "all agents". Multi-select is allowed; each target may end up in a different folder.
52
+ 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.
53
+ 3. If project scope: which project root? — confirm the absolute path; never guess from `cwd` alone if the workspace is ambiguous.
54
+ 4. Install mode? — copy (default) or symlink (only when the source is a stable local folder the user controls).
55
+
56
+ If the source has `scripts/`, install hooks, postinstall logic, or executable helpers, also ask: "Inspect scripts before install?" Default yes for third-party sources.
57
+
58
+ Recommended structured ask when the runtime provides one:
59
+
60
+ ```text
61
+ Where do you want to install <skill-name>?
62
+
63
+ Provider(s):
64
+ - claude-code
65
+ - claude-desktop
66
+ - cursor
67
+ - codex
68
+ - opencode
69
+ - custom path
70
+
71
+ Scope (per provider):
72
+ - User (global) — applies everywhere
73
+ - Project (this repo) — applies only here; provide repo root
74
+ - Custom — provide absolute path
75
+
76
+ Install mode:
77
+ - Copy (recommended)
78
+ - Symlink (only for stable local sources)
79
+ ```
80
+
81
+ ## Conflict Handling
82
+
83
+ For every resolved destination, check for an existing folder before writing:
84
+
85
+ ```bash
86
+ ls "<destination>/<skill-name>" 2>/dev/null
87
+ ```
88
+
89
+ Ask per-destination when a conflict is found:
90
+
91
+ - `Overwrite` — replace the existing folder.
92
+ - `Skip` — leave existing in place, skip this destination only.
93
+ - `Rename` — install under a different `skill-name` (e.g. `<skill-name>-2`).
94
+ - `Diff` — show what differs before deciding.
95
+ - `Cancel` — abort the whole install.
96
+
97
+ Never silently overwrite. Never assume one conflict choice applies to all destinations.
98
+
99
+ ## Install Checklist
100
+
101
+ Run only the items that fit the situation; do not force every step.
102
+
103
+ - Source resolved: folder contains a valid `SKILL.md` with `name` and `description` frontmatter.
104
+ - Safety scan: read `SKILL.md` and any `scripts/`, install hooks, or executable helpers; flag risky behavior to the user.
105
+ - Destinations confirmed: provider(s), scope(s), and final absolute path(s) shown to the user.
106
+ - Conflict check: per destination.
107
+ - Approval: explicit user confirmation to proceed.
108
+ - 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.
109
+ - Write: copy (or symlink) into each destination. Prefer atomic copy when supported.
110
+ - Verify: `ls "<destination>/<skill-name>/SKILL.md"` for every destination; report per-destination success or failure.
111
+ - Post-install hint (optional): tell the user how the active agent picks up new skills (restart, reload, or auto-scan).
112
+
113
+ ## Symlink Notes
114
+
115
+ Use symlinks only when all of these hold:
116
+
117
+ - Source is a stable local path the user controls (not a temp clone, not a remote download).
118
+ - User explicitly wants edits in source to reflect immediately.
119
+ - Destination runtime supports symlinked skill folders.
120
+
121
+ Otherwise, prefer copy.
122
+
123
+ ## Recovery
124
+
125
+ - Destination does not exist yet: create the parent directory after explicit approval; do not auto-create deep custom paths.
126
+ - Permission denied: report the path and ask whether to try a different scope or a user-writable destination.
127
+ - Partial multi-target install: report which destinations succeeded and which failed; never roll back other targets without asking.
128
+ - Remote download incomplete: re-fetch once; if still incomplete, stop and report missing files.
129
+ - Frontmatter invalid: do not install; explain the gap.
130
+ - Unknown provider: treat as `custom path`; ask for an absolute destination and confirm the runtime scans it.
@@ -0,0 +1,27 @@
1
+ # References
2
+
3
+ Sources consulted to research and create this skill.
4
+
5
+ ## Skills.sh API Results
6
+ <!-- Top candidates from skills.sh API search, sorted by installs descending -->
7
+ | Skill | Source | Installs | Used for |
8
+ |-------|--------|----------|----------|
9
+ | <skillId> | <owner/repo> | <installs> | <what pattern was borrowed or why inspected> |
10
+
11
+ ## GitHub Sources Inspected
12
+ <!-- SKILL.md files read via Octocode -->
13
+ | File | Owner/Repo | Path | Quality | Notes |
14
+ |------|-----------|------|---------|-------|
15
+ | <name> | <owner/repo> | <path> | High/Medium/Low | <what was taken or rejected> |
16
+
17
+ ## Registry and Marketplace Surfaces
18
+ <!-- Other surfaces consulted -->
19
+ | Surface | URL or Query | Finding |
20
+ |---------|-------------|---------|
21
+ | <surface name> | <url or query used> | <what was found> |
22
+
23
+ ## Local Sources
24
+ <!-- Local files or skills consulted -->
25
+ | File | Path | Notes |
26
+ |------|------|-------|
27
+ | <name> | <absolute path> | <what was used> |
@@ -0,0 +1,62 @@
1
+ # References
2
+
3
+ Sources actually consulted to research and create the `octocode-search-skill`.
4
+
5
+ ## Skills.sh API Results
6
+
7
+ Live queries run during creation, sorted by installs descending.
8
+
9
+ **Query: `code review`** (used to validate API response shape)
10
+
11
+ | Skill | Source | Installs | Used for |
12
+ |-------|--------|----------|----------|
13
+ | requesting-code-review | obra/superpowers | 88,768 | Gate and output UX patterns |
14
+ | receiving-code-review | obra/superpowers | 70,328 | Workflow step structure |
15
+ | code-review-excellence | wshobson/agents | 18,559 | Card output format reference |
16
+
17
+ **Query: `skill search agent`** (used to survey the discovery-skill landscape)
18
+
19
+ | Skill | Source | Installs | Used for |
20
+ |-------|--------|----------|----------|
21
+ | parallel-deep-research | parallel-web/parallel-agent-skills | 8,186 | Parallel research pattern |
22
+ | parallel-web-search | parallel-web/parallel-agent-skills | 7,844 | Parallel search pattern |
23
+ | skills-search | daymade/claude-code-skills | 398 | Direct competitor — inspected for gap analysis |
24
+
25
+ **Query: `find skills install`** (used to find meta-skill patterns)
26
+
27
+ | Skill | Source | Installs | Used for |
28
+ |-------|--------|----------|----------|
29
+ | find-skills | bytedance/deer-flow | 1,349 | Meta-skill discovery pattern (duplicate of vercel-labs canonical) |
30
+ | installing-skills | oaustegard/claude-skills | 40 | Install flow reference |
31
+
32
+ ## GitHub Sources Inspected
33
+
34
+ SKILL.md files read via Octocode during design.
35
+
36
+ | File | Owner/Repo | Path | Quality | Notes |
37
+ |------|-----------|------|---------|-------|
38
+ | find-skills | vercel-labs/skills | skills/find-skills/SKILL.md | High | Discovery workflow and gate UX patterns |
39
+ | skill-creator | anthropics/skills | skills/skill-creator/SKILL.md | High | Creation flow and resource structure |
40
+ | brainstorming | obra/superpowers | brainstorming/SKILL.md | High | Research synthesis and recommend pattern |
41
+ | skills-search | daymade/claude-code-skills | skills-search/SKILL.md | Medium | Gap analysis — minimal workflow, no gates |
42
+
43
+ ## Registry and Marketplace Surfaces
44
+
45
+ | Surface | Query or URL | Finding |
46
+ |---------|-------------|---------|
47
+ | skills.sh API | `/api/search?q=code+review&limit=10` | Confirmed response shape: `{"skills":[...], "count": N}` with `installs`, `source`, `skillId` |
48
+ | skills.sh API | `/api/search?q=skill+search+agent&limit=20` | Identified `daymade/claude-code-skills/skills-search` as closest existing competitor |
49
+ | skills.sh API | `/api/search?q=find+skills+install&limit=20` | Confirmed `find-skills` pattern; canonical at vercel-labs, widely forked |
50
+ | agentskills.io | `agentskills.io/llms.txt` | Agent-readable catalog format; confirmed compatible-agents list |
51
+ | aiskillstore.io | `aiskillstore.io/llms.txt` | USK v1.0 spec; capability tag taxonomy and API surface |
52
+ | claude-plugins.dev | Web UI | Auto-indexed GitHub SKILL.md discovery; confirm-before-install pattern |
53
+ | microsoft.github.io/skills | `llms-full.txt` | Sensei scoring rubric (triggers + anti-triggers + compatibility) |
54
+
55
+ ## Local Sources
56
+
57
+ | File | Path | Notes |
58
+ |------|------|-------|
59
+ | agent-skills-guide.md | references/agent-skills-guide.md | Quality rubric, progressive disclosure pattern, description optimization |
60
+ | discovery-surfaces.md | references/discovery-surfaces.md | Marketplace surface catalog; routing table |
61
+ | install-reference.md | references/install-reference.md | 4-gate install protocol; provider matrix |
62
+ | fetch-and-create-locally.md | references/fetch-and-create-locally.md | Remote-to-local fetch and adapt workflow |