skills-agents 0.1.0

package/README.md

@@ -0,0 +1,43 @@
+# skills-agents
+
+One command for both halves of an agent-capability catalog: **skills**
+(`SKILL.md` — read by Claude Code, Codex, and Cursor) and **subagents**
+(`AGENT.md` — read by Claude Code). Works anywhere Node does, Windows
+included.
+
+```sh
+# a whole build stage — every skill AND agent in it
+npx skills-agents add https://docs.codehance.com/stage/start -g -y
+
+# one subagent
+npx skills-agents add https://docs.codehance.com --agent idea-researcher -g
+
+# one skill, pinned to a tool
+npx skills-agents add https://docs.codehance.com --skill idea -g --tool claude-code
+```
+
+## How it works
+
+A **source** is any URL serving the standard well-known indexes:
+`/.well-known/skills/index.json` and/or `/.well-known/agents/index.json`.
+
+- **Skills** are delegated to the [`skills`](https://www.npmjs.com/package/skills)
+  CLI, so multi-tool targeting (Claude Code, Codex, Cursor), lockfiles, and
+  `npx skills update` all keep working.
+- **Subagents** are downloaded into the agents folder —
+  `~/.claude/agents/` with `-g`, `./.claude/agents/` without. Subagents are
+  currently a Claude Code concept; other tools get them when they support
+  subagent definitions.
+
+## Flags
+
+| Flag | Meaning |
+| --- | --- |
+| `-g, --global` | Install at user level (available in every project) |
+| `-y, --yes` | Skip confirmation prompts |
+| `--skill <name>` | Install only this skill (repeatable) |
+| `--agent <name>` | Install only this subagent (repeatable) |
+| `--tool <tool>` | Target tool(s) for skills: `claude-code`, `codex`, `cursor` (default: auto-detect) |
+
+With no `--skill`/`--agent`, everything the source lists is installed —
+that's what makes stage sources one-command.

package/bin.mjs

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+// skills-agents — one command for both halves of a well-known source:
+// skills (SKILL.md, installed via the `skills` CLI so Claude Code, Codex,
+// and Cursor targeting keeps working) and subagents (AGENT.md, downloaded
+// into the agents folder — currently a Claude Code concept).
+//
+//   npx skills-agents add <source> [flags]
+//
+// A source is any site serving /.well-known/skills/index.json and/or
+// /.well-known/agents/index.json (e.g. https://docs.codehance.com or a
+// stage source like https://docs.codehance.com/stage/start).
+
+import { spawnSync } from 'node:child_process'
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const VERSION = '0.1.0'
+
+const HELP = `skills-agents ${VERSION} — install skills and subagents from a well-known source
+
+Usage:
+  npx skills-agents add <source> [flags]
+
+Source:
+  Any URL serving /.well-known/skills/index.json and/or
+  /.well-known/agents/index.json, e.g.
+    https://docs.codehance.com                (whole catalog)
+    https://docs.codehance.com/stage/start    (one build stage)
+
+Flags:
+  -g, --global         Install at user level (works in every project)
+  -y, --yes            Skip confirmation prompts
+  --skill <name>       Install only this skill (repeatable)
+  --agent <name>       Install only this subagent (repeatable)
+  --tool <tool>        Target coding tool(s) for skills: claude-code, codex,
+                       cursor (repeatable; default: auto-detect). Subagents
+                       are currently Claude Code-only.
+  -h, --help           Show this help
+  -v, --version        Show version
+
+Examples:
+  npx skills-agents add https://docs.codehance.com/stage/start -g -y
+  npx skills-agents add https://docs.codehance.com --agent idea-researcher -g
+  npx skills-agents add https://docs.codehance.com --skill idea -g --tool claude-code
+`
+
+function fail(message) {
+  console.error(`skills-agents: ${message}`)
+  process.exit(1)
+}
+
+function parseArgs(argv) {
+  const opts = {
+    command: null,
+    source: null,
+    global: false,
+    yes: false,
+    skills: [],
+    agents: [],
+    tools: [],
+  }
+  const takeValue = (flag, i) => {
+    if (i + 1 >= argv.length) fail(`${flag} needs a value`)
+    return argv[i + 1]
+  }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    switch (arg) {
+      case '-h':
+      case '--help':
+        console.log(HELP)
+        process.exit(0)
+      case '-v':
+      case '--version':
+        console.log(VERSION)
+        process.exit(0)
+      case '-g':
+      case '--global':
+        opts.global = true
+        break
+      case '-y':
+      case '--yes':
+        opts.yes = true
+        break
+      case '--skill':
+        opts.skills.push(takeValue(arg, i))
+        i++
+        break
+      case '--agent':
+        opts.agents.push(takeValue(arg, i))
+        i++
+        break
+      case '--tool':
+        opts.tools.push(takeValue(arg, i))
+        i++
+        break
+      default:
+        if (arg.startsWith('-')) fail(`unknown flag '${arg}' (see --help)`)
+        if (!opts.command) opts.command = arg
+        else if (!opts.source) opts.source = arg
+        else fail(`unexpected argument '${arg}'`)
+    }
+  }
+  return opts
+}
+
+async function fetchIndex(source, kind) {
+  const url = `${source.replace(/\/$/, '')}/.well-known/${kind}/index.json`
+  let res
+  try {
+    res = await fetch(url)
+  } catch (err) {
+    fail(`could not reach ${url} (${err.message})`)
+  }
+  if (res.status === 404) return null // source has no <kind> half — fine
+  if (!res.ok) fail(`${url} responded ${res.status}`)
+  try {
+    const body = await res.json()
+    const entries = body[kind]
+    return Array.isArray(entries) ? entries : null
+  } catch {
+    fail(`${url} is not a valid index`)
+  }
+}
+
+// Skills install delegates to the `skills` CLI — it already handles
+// multi-tool targeting (Claude Code, Codex, Cursor), lockfiles, and
+// updates. Its --agent flag means "target tool"; ours is --tool.
+function installSkills(opts) {
+  const args = ['--yes', 'skills', 'add', opts.source]
+  for (const s of opts.skills) args.push('-s', s)
+  for (const t of opts.tools) args.push('--agent', t)
+  if (opts.global) args.push('-g')
+  if (opts.yes) args.push('-y')
+  const result = spawnSync('npx', args, {
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+  })
+  if (result.error) fail(`could not run the skills CLI: ${result.error.message}`)
+  return result.status ?? 1
+}
+
+async function installAgents(opts, entries) {
+  const wanted = opts.agents.length
+    ? entries.filter((e) => opts.agents.includes(e.name))
+    : entries
+  if (opts.agents.length) {
+    const found = new Set(wanted.map((e) => e.name))
+    const missing = opts.agents.filter((n) => !found.has(n))
+    if (missing.length) {
+      fail(
+        `agent${missing.length > 1 ? 's' : ''} not found at this source: ${missing.join(', ')}\n` +
+          `available: ${entries.map((e) => e.name).join(', ') || '(none)'}`
+      )
+    }
+  }
+  if (!wanted.length) return
+
+  // Subagents are a Claude Code concept today; other tools get them when
+  // they support subagent definitions.
+  if (opts.tools.length && !opts.tools.includes('claude-code')) {
+    console.log('skills-agents: skipping subagents (only claude-code reads them)')
+    return
+  }
+
+  const dir = opts.global
+    ? join(homedir(), '.claude', 'agents')
+    : join('.claude', 'agents')
+  mkdirSync(dir, { recursive: true })
+
+  const base = opts.source.replace(/\/$/, '')
+  for (const entry of wanted) {
+    const file = entry.files?.[0] ?? 'AGENT.md'
+    const url = `${base}/.well-known/agents/${entry.name}/${file}`
+    const res = await fetch(url)
+    if (!res.ok) fail(`download failed (${res.status}): ${url}`)
+    const target = join(dir, `${entry.name}.md`)
+    writeFileSync(target, Buffer.from(await res.arrayBuffer()))
+    console.log(`✓ agent ${entry.name} → ${target}`)
+  }
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2))
+  if (!opts.command) {
+    console.log(HELP)
+    process.exit(1)
+  }
+  if (opts.command !== 'add') fail(`unknown command '${opts.command}' (only 'add' is supported)`)
+  if (!opts.source) fail('add needs a source URL (see --help)')
+  if (!/^https?:\/\//.test(opts.source)) fail(`source must be an http(s) URL, got '${opts.source}'`)
+
+  // --skill only → skills half; --agent only → agents half; neither → both.
+  const wantSkills = opts.skills.length > 0 || opts.agents.length === 0
+  const wantAgents = opts.agents.length > 0 || opts.skills.length === 0
+
+  let exitCode = 0
+
+  if (wantSkills) {
+    const skillsIndex = await fetchIndex(opts.source, 'skills')
+    if (skillsIndex?.length) {
+      exitCode = installSkills(opts)
+    } else if (opts.skills.length) {
+      fail('this source lists no skills')
+    }
+  }
+
+  if (wantAgents && exitCode === 0) {
+    const agentsIndex = await fetchIndex(opts.source, 'agents')
+    if (agentsIndex?.length) {
+      await installAgents(opts, agentsIndex)
+    } else if (opts.agents.length) {
+      fail('this source lists no agents')
+    }
+  }
+
+  process.exit(exitCode)
+}
+
+main().catch((err) => fail(err.message))

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "skills-agents",
+  "version": "0.1.0",
+  "description": "Install agent skills (SKILL.md) and subagents (AGENT.md) from any well-known source with one command — skills for Claude Code, Codex, and Cursor via the skills CLI; subagents downloaded natively.",
+  "keywords": [
+    "skills",
+    "agents",
+    "subagents",
+    "claude-code",
+    "codex",
+    "cursor",
+    "agent-skills"
+  ],
+  "license": "MIT",
+  "author": "Codehance <claude@codehance.com>",
+  "homepage": "https://docs.codehance.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CodehanceHQ/docs.git",
+    "directory": "cli"
+  },
+  "type": "module",
+  "bin": {
+    "skills-agents": "bin.mjs"
+  },
+  "files": [
+    "bin.mjs"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  }
+}