skillshark 0.1.0 → 0.3.0

package/README.md

@@ -1,5 +1,7 @@
 # SkillShark 🦈
 
+**[holy-coders.github.io/skillshark](https://holy-coders.github.io/skillshark/)** · [npm](https://www.npmjs.com/package/skillshark)
+
 **Share an agent skill like you'd share a file.** SkillShark packages a Claude Code skill (or command) into a secret GitHub gist and hands you an unlisted, self-verifying link; the receiver installs it with one command and zero setup — no GitHub account, no server, no registry.
 
 > ⚠️ **Secret gists are unlisted, NOT private — anyone with the link can read them.**
@@ -9,29 +11,40 @@
 
 ## Install
 
-Zero-install:
+Zero-install (stable, from npm):
 
 ```sh
 npx skillshark install <link>
 ```
 
-Or globally:
+Want the **beta** — whatever is on `main` right now, ahead of the npm release?
+
+```sh
+npx github:Holy-Coders/skillshark install <link>
+```
+
+Both forms take the exact same commands and flags; the `github:` one just builds from the repo's latest commit instead of the published package. Or install globally:
 
 ```sh
-npm install -g skillshark
+npm install -g skillshark      # stable
+npm install -g github:Holy-Coders/skillshark   # beta from main
 ```
 
+Once it's on your PATH, running bare **`skillshark`** opens an interactive session — pick a local skill to share from a menu, paste a link to install, inspect, or revoke, all guided with previews and spinners. Every flag-driven form below works too (and is what you want in scripts/CI).
+
 Requirements: Node ≥ 20. **Senders** also need the [GitHub CLI](https://cli.github.com) authenticated (`gh auth login`). **Receivers need nothing** — public links are fetched over plain anonymous HTTPS.
 
 ## The four commands
 
-**share** — package a skill and get an unlisted link (auto-copied to your clipboard):
+**share** — package a skill and get an unlisted link. Your clipboard receives the full **paste-and-go install one-liner**, so the receiver just pastes it into any terminal:
 
 ```sh
 skillshark share /j
-# → https://gist.github.com/8a1bc94ef23d4b6a9c01e57f8d2a4b3c#fp=3f9a7c21
+# clipboard → npx skillshark install 'https://gist.github.com/8a1bc94…#fp=3f9a7c21'
 ```
 
+(`-q` still prints the bare URL for scripts; `--json` includes both `url` and `installCommand`.)
+
 Accepts a name (`j`, `/j` — resolved across `./.claude/skills`, `./.claude/commands`, and their `~/` equivalents) or any path. Useful flags: `--expires 30m|6h|24h|7d|30d` (advisory, default 7d), `--dry-run`, `--name`, `--force`, `--no-clipboard`, `-q` (print only the URL).
 
 **install** — download, verify, preview, confirm, copy:
@@ -42,7 +55,10 @@ skillshark install <gist-id>                               # bare id works too
 skillshark install gh:acme/skills/review@main              # any public repo path
 ```
 
-Skills land in `.claude/skills/<name>/`, commands in `.claude/commands/<name>.md` (project scope when the cwd has `.claude/` or `.git`, else `--project`/`--global`/`--dir`). Useful flags: `--yes`, `--force`, `--allow-exec`, `--dir <path>`.
+Skills land in `.claude/skills/<name>/`, commands in `.claude/commands/<name>.md` (project scope when the cwd looks like a project, else `--project`/`--global`/`--dir`). Useful flags: `--yes`, `--force`, `--allow-exec`, `--dir <path>`, and:
+
+- `--name <name>` — install under a different name. The directory/filename changes and the artifact's frontmatter `name:` is rewritten to match, so two variants of the same skill can live side by side.
+- `--agent <id>` — install for a different tool entirely (see below).
 
 **inspect** — look before you leap (writes nothing):
 
@@ -62,6 +78,49 @@ The gist dies immediately; anyone holding the link gets "deleted by the sender."
 (GitHub's anonymous API cache can serve a just-deleted gist for up to ~a minute
 before the 404 propagates everywhere.)
 
+## Cross-agent sharing (v0.2)
+
+SkillShark speaks seven tools' on-disk dialects. You can **share from** any of them (bare names resolve across all of these locations) and **install to** any of them with `--agent <id>`:
+
+| `--agent` | Artifacts | Where they land |
+|---|---|---|
+| `claude-code` | skills, commands | `.claude/skills/<n>/`, `.claude/commands/<n>.md` (project or `~/`) |
+| `cursor` | rules, commands | `.cursor/rules/<n>.mdc` (project), `.cursor/commands/<n>.md` |
+| `codex` | prompts | `~/.codex/prompts/<n>.md` (Codex only reads global) |
+| `copilot` | prompt files | `.github/prompts/<n>.prompt.md` (project) |
+| `windsurf` | rules, workflows | `.windsurf/rules/<n>.md`, `.windsurf/workflows/<n>.md` (project) |
+| `gemini` | commands | `.gemini/commands/<n>.toml` (TOML, project or `~/`) |
+| `opencode` | commands | `.opencode/command/<n>.md`, `~/.config/opencode/command/<n>.md` |
+
+```sh
+skillshark share draftpr                  # found in ~/.codex/prompts/draftpr.md
+skillshark install <link> --agent cursor  # lands as .cursor/commands/draftpr.md
+```
+
+Crossing agents **converts** the artifact: the instructions (frontmatter + body) are re-rendered in the target's dialect — YAML frontmatter for Claude/Copilot/opencode, `.mdc` for Cursor rules, TOML `prompt`/`description` for Gemini, plain markdown where the tool wants it. Two honest limits, stated loudly at install time:
+
+- **Bundled files don't cross.** A Claude skill's `scripts/` and reference files have no equivalent elsewhere; converting installs the instructions only and names every file left behind.
+- **Conversion is best-effort.** A skill written for one tool may assume features another doesn't have. Read the result.
+
+Same-agent installs are always byte-verbatim — conversion only happens when you cross.
+
+## GitHub Enterprise (v0.3)
+
+If your company runs GitHub Enterprise (GHES or `*.ghe.com`), SkillShark works entirely inside it — nothing touches public github.com:
+
+```sh
+gh auth login --hostname ghe.corp.com        # once, sender and receivers alike
+skillshark share j --host ghe.corp.com       # gist lives on YOUR GitHub
+skillshark install 'https://ghe.corp.com/gist/<id>#fp=<hex>'
+```
+
+- **Links carry their host.** Receivers don't need `--host` — an enterprise URL routes itself. `GH_HOST` (or `SKILLSHARK_HOST`) sets the default for bare ids and `gh:owner/repo` sources.
+- **The privacy property:** enterprise links are fetched exclusively through the receiver's own `gh` auth. No anonymous request ever leaves for an enterprise host (enforced by tests), and unauthenticated users get a clear `gh auth login --hostname …` pointer instead of a leak.
+- **One honest limit:** the gists API truncates inline content at ~1 MB and enterprise receivers can't fetch around it anonymously, so enterprise *gist* shares are capped at ~900 KB encoded. Bigger skills: put them in a repo on your GHES and share `gh:owner/repo/path` with `--host`.
+- `revoke` remembers which host a share went to and deletes it there.
+
+Public github.com behavior is completely unchanged: receivers still need no account and the receive path still never invokes `gh`.
+
 ## Security model
 
 - **SkillShark never executes package content.** Install = copy files. No postinstall hooks, no scripts, ever.

package/bin/skillshark.js

@@ -5,15 +5,17 @@ import os from 'node:os';
 import { CliError } from '../src/errors.js';
 import { VERSION } from '../src/version.js';
 import { getConfigDir } from '../src/config.js';
-import { makeUi, realPrompts } from '../src/ui.js';
+import { makeUi, realPrompts, attachSpinner } from '../src/ui.js';
 import { makeGhApi } from '../src/gh.js';
 import { copyToClipboard } from '../src/clipboard.js';
 import { runShare, runRevoke } from '../src/share.js';
 import { runInstall, runInspect } from '../src/install.js';
+import { runInteractive } from '../src/interactive.js';
 
 const HELP = `skillshark — share agent skills like files
 
 USAGE
+  skillshark                 interactive session (pick, share, install — guided)
   skillshark <command> [options]
 
 COMMANDS
@@ -31,17 +33,34 @@ GLOBAL OPTIONS
   -y, --yes        Skip prompts (non-interactive)
   -q, --quiet      Print only the essential result (URL or path)
       --json       Machine-readable output
+      --host <h>   GitHub Enterprise hostname (default github.com; also
+                   honors GH_HOST). Enterprise links carry their host, so
+                   receivers usually don't need this flag.
       --no-color   Disable color (NO_COLOR is also honored)
   -h, --help       Show help (try: skillshark help <command>)
   -V, --version    Show version
 
+ENTERPRISE (privacy)
+  skillshark share j --host ghe.corp.com    share on your GHES — never leaves it
+  Enterprise links are fetched through YOUR gh auth (gh auth login --hostname
+  ghe.corp.com); no anonymous request ever touches an enterprise host.
+
 EXAMPLES
+  skillshark                                interactive: menus for everything below
   skillshark share /j                       share the "j" skill (secret gist)
   skillshark install <gist-url|id>          install a shared skill
+  skillshark install <link> --name jmp      install under a different name
+  skillshark install <link> --agent codex   convert for another tool
   skillshark install gh:acme/skills/review  install straight from a repo path
   skillshark inspect <gist-url> --cat SKILL.md
   skillshark revoke j                       delete the share
 
+AGENTS (share from and install to)
+  claude-code (skills, commands) · cursor (rules, commands) · codex (prompts)
+  copilot (prompt files) · windsurf (rules, workflows) · gemini (commands)
+  opencode (commands). Cross-agent installs convert the instructions to the
+  target's dialect; a skill's bundled scripts can't follow it (warned loudly).
+
 Secret gists are unlisted, NOT private — anyone with the link can read them.
 SkillShark never executes package content; install only copies files.`;
 
@@ -62,10 +81,16 @@ unlisted, not private: anyone holding it can read the gist. Undo with
   install: `skillshark install <source> — download, verify, preview, confirm, copy
 
   -y, --yes             Install without prompting (documented as dangerous)
-      --project         Install into ./.claude/... (default when cwd is a project)
-      --global          Install into ~/.claude/... (all projects)
-      --dir <path>      Install into an explicit directory (required for
-                        prompt/bundle packages; overrides agent detection)
+      --name <name>     Install under a different name (renames the artifact
+                        and updates its frontmatter name)
+      --agent <id>      Target agent: claude-code | cursor | codex | copilot |
+                        windsurf | gemini | opencode. Crossing agents converts
+                        the artifact's instructions to the target's dialect —
+                        bundled support files can't come along (warned).
+      --project         Install at project scope (where the agent supports it)
+      --global          Install at user/global scope
+      --dir <path>      Install verbatim into an explicit directory (required
+                        for bundle packages; skips agent conventions)
       --force           Overwrite an existing, differing artifact
       --allow-exec      Keep executable bits (stripped by default)
   -q, --quiet           Print only the installed path
@@ -94,6 +119,7 @@ const GLOBAL_FLAGS = {
   yes: { short: 'y', key: 'yes' },
   quiet: { short: 'q', key: 'quiet' },
   json: { key: 'json' },
+  host: { takesValue: true, key: 'host' },
   'no-color': { key: 'noColor' },
   help: { short: 'h', key: 'help' },
   version: { short: 'V', key: 'version' },
@@ -113,6 +139,7 @@ const COMMAND_FLAGS = {
     dir: { takesValue: true, key: 'dir' },
     'allow-exec': { key: 'allowExec' },
     agent: { takesValue: true, key: 'agent' },
+    name: { takesValue: true, key: 'name' },
   },
   inspect: {
     cat: { takesValue: true, key: 'cat' },
@@ -123,7 +150,8 @@ const COMMAND_FLAGS = {
 
 function parseArgv(argv) {
   const [first, ...rest] = argv;
-  if (!first || first === 'help') {
+  if (!first) return { command: 'interactive', opts: {}, positionals: [] };
+  if (first === 'help') {
     return { command: 'help', topic: rest[0] ?? null, opts: {}, positionals: [] };
   }
   if (first === '--help' || first === '-h') return { command: 'help', topic: null, opts: {}, positionals: [] };
@@ -192,19 +220,10 @@ async function main() {
     return 0;
   }
 
-  const known = new Set(['share', 'install', 'inspect', 'revoke']);
+  const known = new Set(['share', 'install', 'inspect', 'revoke', 'interactive']);
   if (!known.has(parsed.command)) {
     throw new CliError(`Unknown command "${parsed.command}". Commands: share, install, inspect, revoke. Try: skillshark --help`, 2);
   }
-  if (parsed.opts.agent && parsed.opts.agent !== 'claude-code') {
-    throw new CliError(`Only --agent claude-code is supported in v0.1 (got "${parsed.opts.agent}").`, 2);
-  }
-
-  const arg = parsed.positionals[0];
-  if (!arg) {
-    const noun = parsed.command === 'share' ? '<path|name>' : parsed.command === 'revoke' ? '<id|name>' : '<source>';
-    throw new CliError(`Usage: skillshark ${parsed.command} ${noun}. Try: skillshark help ${parsed.command}`, 2);
-  }
   if (parsed.positionals.length > 1) {
     throw new CliError(`Too many arguments: ${parsed.positionals.slice(1).join(' ')}`, 2);
   }
@@ -223,6 +242,24 @@ async function main() {
     ghApi: makeGhApi(),
     clipboard: (text) => copyToClipboard(text),
   };
+  if (effectiveTTY) await attachSpinner(ui);
+
+  // no command (TTY) → the interactive session; piped → help text
+  if (parsed.command === 'interactive') {
+    if (!effectiveTTY) {
+      ui.out(HELP);
+      return 0;
+    }
+    return runInteractive(deps);
+  }
+
+  const arg = parsed.positionals[0];
+  if (!arg) {
+    // bare subcommand in a TTY → that command's wizard; piped → usage error
+    if (effectiveTTY) return runInteractive(deps, parsed.command);
+    const noun = parsed.command === 'share' ? '<path|name>' : parsed.command === 'revoke' ? '<id|name>' : '<source>';
+    throw new CliError(`Usage: skillshark ${parsed.command} ${noun}. Try: skillshark help ${parsed.command}`, 2);
+  }
 
   switch (parsed.command) {
     case 'share':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillshark",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Share agent skills like files — secret gists out, safe verified installs in. No server; GitHub is the backend.",
   "type": "module",
   "bin": {
@@ -11,6 +11,14 @@
     "src",
     "README.md"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Holy-Coders/skillshark.git"
+  },
+  "homepage": "https://holy-coders.github.io/skillshark/",
+  "bugs": {
+    "url": "https://github.com/Holy-Coders/skillshark/issues"
+  },
   "keywords": [
     "claude-code",
     "agent-skills",
@@ -19,7 +27,7 @@
     "cli",
     "sharing"
   ],
-  "author": "Aaron Turkel",
+  "author": "Holy Coders",
   "engines": {
     "node": ">=20"
   },

package/src/agents.js

@@ -0,0 +1,336 @@
+// The adapter registry: the ONLY place agent-specific knowledge lives.
+// Each adapter encodes one tool's on-disk conventions (verified against the
+// tools' docs, June 2026) and how to render a canonical artifact into its
+// dialect. Cross-agent installs are honest best-effort conversions: markdown
+// instructions travel; bundled support files cannot leave a Claude skill.
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { CliError } from './errors.js';
+
+export const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+// canonical = { name, description, body } — body is the primary document
+// with its source-dialect frontmatter stripped.
+
+// --- dialect helpers ---------------------------------------------------------
+
+function yamlFront(fields) {
+  const lines = Object.entries(fields)
+    .filter(([, v]) => v !== undefined && v !== null && v !== '')
+    .map(([k, v]) => `${k}: ${String(v)}`);
+  if (!lines.length) return '';
+  return `---\n${lines.join('\n')}\n---\n\n`;
+}
+
+// TOML basic strings: escape backslashes and quotes so the parsed prompt is
+// byte-identical to the source body.
+function tomlBasicString(s) {
+  return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+function tomlMultiline(s) {
+  const escaped = s.replace(/\\/g, '\\\\').replace(/"""/g, '""\\"');
+  return `"""\n${escaped}\n"""`;
+}
+
+export function renderGeminiToml({ description, body }) {
+  let out = '';
+  if (description) out += `description = ${tomlBasicString(description)}\n\n`;
+  out += `prompt = ${tomlMultiline(body.replace(/\n$/, ''))}\n`;
+  return out;
+}
+
+// Parse the gemini TOML dialect (our generated shape + the common hand-written
+// variants: basic/literal multiline strings and single-line prompts).
+export function parseGeminiToml(text) {
+  const out = { description: '', body: null };
+  const desc = text.match(/^[ \t]*description[ \t]*=[ \t]*"((?:[^"\\]|\\.)*)"[ \t]*$/m);
+  if (desc) out.description = desc[1].replace(/\\(["\\])/g, '$1');
+
+  let m = text.match(/^[ \t]*prompt[ \t]*=[ \t]*"""\n?([\s\S]*?)"""[ \t]*$/m);
+  if (m) {
+    out.body = m[1].replace(/""\\"/g, '"""').replace(/\\\\/g, '\\').replace(/\n$/, '');
+    return out;
+  }
+  m = text.match(/^[ \t]*prompt[ \t]*=[ \t]*'''\n?([\s\S]*?)'''[ \t]*$/m);
+  if (m) {
+    out.body = m[1].replace(/\n$/, '');
+    return out;
+  }
+  m = text.match(/^[ \t]*prompt[ \t]*=[ \t]*"((?:[^"\\]|\\.)*)"[ \t]*$/m);
+  if (m) {
+    out.body = m[1].replace(/\\n/g, '\n').replace(/\\t/g, '\t').replace(/\\(["\\])/g, '$1');
+    return out;
+  }
+  return out; // body null → caller decides how honest to be
+}
+
+// Rewrite (or leave alone) the `name:` value in a YAML frontmatter block.
+export function rewriteFrontmatterName(text, newName) {
+  if (!text.startsWith('---')) return text;
+  const end = text.indexOf('\n---', 3);
+  if (end === -1) return text;
+  const head = text.slice(0, end);
+  if (!/^name[ \t]*:/m.test(head.slice(4))) return text;
+  const newHead = head.replace(/^(name[ \t]*:[ \t]*).*$/m, `$1${newName}`);
+  return newHead + text.slice(end);
+}
+
+// --- the registry -------------------------------------------------------------
+
+// Adapter shape:
+//   label                       human name
+//   detect({cwd, home})         is this tool present here?
+//   locations                   share-side lookup spots for a bare <name>
+//     { kind, scope, rel(name) }   rel is relative to cwd (project) or home (global)
+//   mapKind(type)               incoming artifact type → this agent's kind (null = can't)
+//   scopes(kind)                'both' | 'project' | 'global'
+//   targetRel(kind, name)       install path segments, relative to the scope root
+//   container(kind)             'dir' | 'file'
+//   render(kind, canonical)     content for a converted install
+//   parse(content, ext)         native file → { description, body } (canonical-ish)
+const mdParse = (content) => {
+  // lazy import avoided: tiny local frontmatter read
+  const fm = {};
+  let body = content;
+  if (content.startsWith('---')) {
+    const end = content.indexOf('\n---', 3);
+    if (end !== -1) {
+      for (const line of content.slice(4, end).split('\n')) {
+        const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (m) fm[m[1]] = m[2].trim().replace(/^["']|["']$/g, '');
+      }
+      body = content.slice(end + 4).replace(/^\n/, '');
+    }
+  }
+  return { name: fm.name, description: fm.description ?? '', body };
+};
+
+export const AGENTS = {
+  'claude-code': {
+    label: 'Claude Code',
+    detect: ({ cwd, home }) =>
+      existsSync(path.join(cwd, '.claude')) || existsSync(path.join(home, '.claude')),
+    locations: [
+      { kind: 'skill', scope: 'project', container: 'dir', rel: (n) => ['.claude', 'skills', n] },
+      { kind: 'command', scope: 'project', container: 'file', rel: (n) => ['.claude', 'commands', `${n}.md`] },
+      { kind: 'skill', scope: 'global', container: 'dir', rel: (n) => ['.claude', 'skills', n] },
+      { kind: 'command', scope: 'global', container: 'file', rel: (n) => ['.claude', 'commands', `${n}.md`] },
+    ],
+    mapKind: (type) => (type === 'skill' || type === 'rule' ? 'skill' : type === 'bundle' ? null : 'command'),
+    scopes: () => 'both',
+    container: (kind) => (kind === 'skill' ? 'dir' : 'file'),
+    targetRel: (kind, name) =>
+      kind === 'skill' ? ['.claude', 'skills', name] : ['.claude', 'commands', `${name}.md`],
+    render: (kind, { name, description, body }) => {
+      if (kind === 'skill') {
+        return { filename: 'SKILL.md', content: yamlFront({ name, description }) + body };
+      }
+      return { filename: `${name}.md`, content: yamlFront({ description }) + body };
+    },
+    parse: mdParse,
+  },
+
+  cursor: {
+    label: 'Cursor',
+    detect: ({ cwd, home }) =>
+      existsSync(path.join(cwd, '.cursor')) || existsSync(path.join(home, '.cursor')),
+    locations: [
+      { kind: 'rule', scope: 'project', container: 'file', rel: (n) => ['.cursor', 'rules', `${n}.mdc`] },
+      { kind: 'command', scope: 'project', container: 'file', rel: (n) => ['.cursor', 'commands', `${n}.md`] },
+      { kind: 'command', scope: 'global', container: 'file', rel: (n) => ['.cursor', 'commands', `${n}.md`] },
+    ],
+    mapKind: (type) => (type === 'bundle' ? null : type === 'rule' ? 'rule' : 'command'),
+    scopes: (kind) => (kind === 'rule' ? 'project' : 'both'),
+    container: () => 'file',
+    targetRel: (kind, name) =>
+      kind === 'rule' ? ['.cursor', 'rules', `${name}.mdc`] : ['.cursor', 'commands', `${name}.md`],
+    render: (kind, { name, description, body }) => {
+      if (kind === 'rule') {
+        return { filename: `${name}.mdc`, content: yamlFront({ description, alwaysApply: 'false' }) + body };
+      }
+      return { filename: `${name}.md`, content: body };
+    },
+    parse: mdParse,
+  },
+
+  codex: {
+    label: 'Codex CLI',
+    detect: ({ cwd, home }) =>
+      existsSync(path.join(cwd, '.codex')) || existsSync(path.join(home, '.codex')),
+    locations: [
+      { kind: 'prompt', scope: 'global', container: 'file', rel: (n) => ['.codex', 'prompts', `${n}.md`] },
+    ],
+    mapKind: (type) => (type === 'bundle' ? null : 'prompt'),
+    scopes: () => 'global', // Codex scans only ~/.codex/prompts (top-level)
+    container: () => 'file',
+    targetRel: (kind, name) => ['.codex', 'prompts', `${name}.md`],
+    render: (kind, { description, body, name }) => ({
+      filename: `${name}.md`,
+      content: yamlFront({ description }) + body,
+    }),
+    parse: mdParse,
+  },
+
+  copilot: {
+    label: 'GitHub Copilot',
+    detect: ({ cwd }) =>
+      existsSync(path.join(cwd, '.github', 'prompts')) ||
+      existsSync(path.join(cwd, '.github', 'copilot-instructions.md')) ||
+      existsSync(path.join(cwd, '.github', 'instructions')),
+    locations: [
+      { kind: 'prompt', scope: 'project', container: 'file', rel: (n) => ['.github', 'prompts', `${n}.prompt.md`] },
+    ],
+    mapKind: (type) => (type === 'bundle' ? null : 'prompt'),
+    scopes: () => 'project',
+    container: () => 'file',
+    targetRel: (kind, name) => ['.github', 'prompts', `${name}.prompt.md`],
+    render: (kind, { description, body, name }) => ({
+      filename: `${name}.prompt.md`,
+      content: yamlFront({ description }) + body,
+    }),
+    parse: mdParse,
+  },
+
+  windsurf: {
+    label: 'Windsurf',
+    detect: ({ cwd, home }) =>
+      existsSync(path.join(cwd, '.windsurf')) ||
+      existsSync(path.join(home, '.codeium', 'windsurf')),
+    locations: [
+      { kind: 'rule', scope: 'project', container: 'file', rel: (n) => ['.windsurf', 'rules', `${n}.md`] },
+      { kind: 'workflow', scope: 'project', container: 'file', rel: (n) => ['.windsurf', 'workflows', `${n}.md`] },
+    ],
+    mapKind: (type) => (type === 'bundle' ? null : type === 'rule' ? 'rule' : 'workflow'),
+    scopes: () => 'project',
+    container: () => 'file',
+    targetRel: (kind, name) =>
+      kind === 'rule' ? ['.windsurf', 'rules', `${name}.md`] : ['.windsurf', 'workflows', `${name}.md`],
+    render: (kind, { description, body, name }) => {
+      if (kind === 'rule') return { filename: `${name}.md`, content: body };
+      return { filename: `${name}.md`, content: yamlFront({ description }) + body };
+    },
+    parse: mdParse,
+  },
+
+  gemini: {
+    label: 'Gemini CLI',
+    detect: ({ cwd, home }) =>
+      existsSync(path.join(cwd, '.gemini')) || existsSync(path.join(home, '.gemini')),
+    locations: [
+      { kind: 'command', scope: 'project', container: 'file', rel: (n) => ['.gemini', 'commands', `${n}.toml`] },
+      { kind: 'command', scope: 'global', container: 'file', rel: (n) => ['.gemini', 'commands', `${n}.toml`] },
+    ],
+    mapKind: (type) => (type === 'bundle' ? null : 'command'),
+    scopes: () => 'both',
+    container: () => 'file',
+    targetRel: (kind, name) => ['.gemini', 'commands', `${name}.toml`],
+    render: (kind, canonical) => ({
+      filename: `${canonical.name}.toml`,
+      content: renderGeminiToml(canonical),
+    }),
+    parse: (content, ext) => {
+      if (ext === '.toml') {
+        const parsed = parseGeminiToml(content);
+        if (parsed.body === null) {
+          throw new CliError(
+            "Couldn't read a prompt out of this Gemini command — install it unconverted with --agent gemini.",
+            1,
+          );
+        }
+        return { description: parsed.description, body: parsed.body };
+      }
+      return mdParse(content);
+    },
+  },
+
+  opencode: {
+    label: 'opencode',
+    detect: ({ cwd, home }) =>
+      existsSync(path.join(cwd, '.opencode')) ||
+      existsSync(path.join(home, '.config', 'opencode')),
+    locations: [
+      { kind: 'command', scope: 'project', container: 'file', rel: (n) => ['.opencode', 'command', `${n}.md`] },
+      { kind: 'command', scope: 'global', container: 'file', rel: (n) => ['.config', 'opencode', 'command', `${n}.md`] },
+    ],
+    mapKind: (type) => (type === 'bundle' ? null : 'command'),
+    scopes: () => 'both',
+    container: () => 'file',
+    targetRel: (kind, name, scope) =>
+      scope === 'global'
+        ? ['.config', 'opencode', 'command', `${name}.md`]
+        : ['.opencode', 'command', `${name}.md`],
+    render: (kind, { description, body, name }) => ({
+      filename: `${name}.md`,
+      content: yamlFront({ description }) + body,
+    }),
+    parse: mdParse,
+  },
+};
+
+export const AGENT_IDS = Object.keys(AGENTS);
+
+export function getAgent(id) {
+  const a = AGENTS[id];
+  if (!a) {
+    throw new CliError(`Unknown agent "${id}". Supported: ${AGENT_IDS.join(', ')}.`, 2);
+  }
+  return a;
+}
+
+export function detectAgents(ctx) {
+  return AGENT_IDS.filter((id) => AGENTS[id].detect(ctx));
+}
+
+// Explicit-path classification: which agent convention does this path follow?
+export function classifyByConvention(absPath, isDir) {
+  const norm = absPath.split(path.sep).join('/');
+  const rules = [
+    [/\/\.claude\/skills\/[^/]+$/, true, 'skill', 'claude-code'],
+    [/\/\.claude\/commands\/[^/]+\.md$/, false, 'command', 'claude-code'],
+    [/\/\.cursor\/rules\/[^/]+\.mdc$/, false, 'rule', 'cursor'],
+    [/\/\.cursor\/commands\/[^/]+\.md$/, false, 'command', 'cursor'],
+    [/\/\.codex\/prompts\/[^/]+\.md$/, false, 'prompt', 'codex'],
+    [/\/\.github\/prompts\/[^/]+\.prompt\.md$/, false, 'prompt', 'copilot'],
+    [/\/\.windsurf\/rules\/[^/]+\.md$/, false, 'rule', 'windsurf'],
+    [/\/\.windsurf\/workflows\/[^/]+\.md$/, false, 'workflow', 'windsurf'],
+    [/\/\.gemini\/commands\/[^/]+\.toml$/, false, 'command', 'gemini'],
+    [/\/(\.opencode|opencode)\/command\/[^/]+\.md$/, false, 'command', 'opencode'],
+  ];
+  for (const [re, wantDir, type, agent] of rules) {
+    if (wantDir === isDir && re.test(norm)) return { type, agent };
+  }
+  return null;
+}
+
+// Strip an artifact filename down to its bare name (handles ".prompt.md").
+export function artifactBaseName(filename) {
+  return filename.replace(/\.prompt\.md$/, '').replace(/\.[^.]+$/, '');
+}
+
+// Extract the canonical document from a verified package: the primary doc,
+// parsed with the SOURCE agent's dialect.
+export function extractCanonical(manifest, readFileSyncish) {
+  const files = manifest.files;
+  let primary =
+    files.find((f) => f.path === 'SKILL.md') ??
+    (files.length === 1 ? files[0] : files.find((f) => /\.(md|mdc|toml)$/.test(f.path) && !f.path.includes('/')));
+  if (!primary) {
+    throw new CliError(
+      `This package has no convertible primary document. Install it natively${manifest.agent ? ` (--agent ${manifest.agent})` : ''} or with --dir.`,
+      2,
+    );
+  }
+  const content = readFileSyncish(primary.path);
+  const ext = path.extname(primary.path);
+  const sourceAgent = AGENTS[manifest.agent] ?? AGENTS['claude-code'];
+  const parsed = sourceAgent.parse(content, ext);
+  const dropped = files.filter((f) => f.path !== primary.path).map((f) => f.path);
+  return {
+    name: manifest.name,
+    description: (parsed.description || manifest.description || '').trim(),
+    body: parsed.body.replace(/^\n+/, ''),
+    primaryPath: primary.path,
+    dropped,
+  };
+}