rolecraft 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Samet ÇELİKBIÇAK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+<div align="center">
+ <img src="assets/rolecraft_logo.png" alt="Logo" width="256" height="256">
+
+# RoleCraft — Simple Skill Installer for AI
+
+ </div>
+
+**Zero-dependency** CLI to install AI agent skills as roles & behaviors from any source. No marketplace, no registry, no signup — just point it at a local folder or a GitHub repo and it works.
+
+Works with **opencode**, **claude-code**, **cursor**, and all spec-compliant agents.
+
+## Why rolecraft?
+
+| Feature                           | rolecraft        | `npx add-skill` | `@agentskill.sh/cli` |
+| --------------------------------- | ---------------- | --------------- | -------------------- |
+| Zero dependencies                 | ✅               | ✅              | ❌ (2)               |
+| Local path install                | ✅ **1st class** | ❌ GitHub only  | ❌ marketplace only  |
+| GitHub repo install               | ✅               | ✅              | ❌                   |
+| Offline capable                   | ✅               | ❌              | ❌                   |
+| agentskill.sh lockfile compatible | ✅               | ✅              | ✅                   |
+| Project-level install             | ✅               | ✅              | ✅                   |
+| File size                         | ~3 KB            | ~500 KB+        | ~84 KB               |
+
+## Install
+
+```bash
+npm install -g rolecraft
+# or
+npx rolecraft install <source>
+```
+
+## Usage
+
+```bash
+rolecraft install ./path/to/my-skill          # install from local folder
+rolecraft install sametcelikbicak/task-decomposer  # install from GitHub
+rolecraft list                                 # list installed skills
+rolecraft remove <slug>                        # remove a skill
+```
+
+### Install scope
+
+When you run `rolecraft install <source>` without flags, it asks where to install:
+
+```
+Where do you want to install this skill?
+  1) Global (~/.agents/skills/) [default]
+  2) Project (./.agents/skills/)
+  3) Both
+```
+
+Use flags to skip the prompt:
+
+```bash
+rolecraft install ./my-skill --global    # ~/.agents/skills/
+rolecraft install ./my-skill --project   # ./.agents/skills/
+rolecraft install ./my-skill --claude    # also ~/.claude/skills/
+rolecraft install ./my-skill --all       # all locations
+```
+
+### Source types
+
+**Local path** — any directory containing `SKILL.md`:
+
+```bash
+rolecraft install ./my-skill
+rolecraft install ~/projects/my-skill
+rolecraft install /absolute/path/to/skill
+```
+
+**GitHub repo** — shorthand `owner/repo`:
+
+```bash
+rolecraft install sametcelikbicak/task-decomposer
+rolecraft install sametcelikbicak/coverage-guard
+```
+
+The CLI clones with `--depth 1`, finds `SKILL.md` recursively, installs it, and cleans up.
+
+## What it does
+
+1. Reads `SKILL.md` from the source and parses metadata (slug, name, owner)
+2. Copies all files alongside `SKILL.md` (references, configs, assets) to the target directory
+3. Updates `~/.agents/.skill-lock.json` so agents can discover the skill
+4. Compatible with skills installed by `@agentskill.sh/cli`, `add-skill`, or manual installs
+
+## How agents discover skills
+
+| Agent       | Directory                                  |
+| ----------- | ------------------------------------------ |
+| opencode    | `~/.agents/skills/` or `./.agents/skills/` |
+| claude-code | `~/.claude/skills/` or `./.claude/skills/` |
+| cursor      | `~/.cursor/skills/` or `./.cursor/skills/` |
+
+## Commands
+
+| Command                      | Description                       |
+| ---------------------------- | --------------------------------- |
+| `rolecraft install <source>` | Install a skill (local or GitHub) |
+| `rolecraft list`             | Show all installed skills         |
+| `rolecraft remove <slug>`    | Uninstall a skill                 |
+| `rolecraft help`             | Show this help                    |
+
+## Project structure
+
+```
+rolecraft/
+├── bin/rolecraft.js          # CLI entry point
+├── src/
+│   ├── commands/
+│   │   ├── install.js        # install logic + interactive scope
+│   │   ├── list.js           # list installed skills
+│   │   └── remove.js         # remove skill + lockfile cleanup
+│   └── utils/
+│       ├── resolver.js       # source resolver (local / GitHub)
+│       ├── installer.js      # copy files to target dirs
+│       └── lockfile.js       # read/write .skill-lock.json
+├── package.json
+└── README.md
+```
+
+## License
+
+MIT

package/bin/rolecraft.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+import { installCommand } from '../src/commands/install.js'
+import { listCommand } from '../src/commands/list.js'
+import { removeCommand } from '../src/commands/remove.js'
+
+function usage() {
+  console.log(`
+rolecraft — Install AI agent skills like roles & behaviors
+
+Zero dependencies, no marketplace required.
+Works with opencode, claude-code, cursor, and all spec-compliant agents.
+
+Usage:
+  rolecraft install <source>     Install a skill (local path or owner/repo)
+  rolecraft list                 List installed skills
+  rolecraft remove <slug>        Remove a skill
+  rolecraft help                 Show this help
+
+Options for install:
+  --global     Install to ~/.agents/skills/ (default)
+  --claude     Also install to ~/.claude/skills/
+  --project    Install to ./.agents/skills/
+  --all        Install to all locations
+
+Examples:
+  rolecraft install ./my-skill
+  rolecraft install sametcelikbicak/task-decomposer
+  rolecraft install ./skills/my-skill --claude
+  rolecraft list
+  rolecraft remove task-decomposer
+`)
+}
+
+export async function main() {
+  const [,, cmd, ...args] = process.argv
+  switch (cmd) {
+    case 'install': {
+      const source = args[0]
+      if (!source) {
+        console.error('Usage: rolecraft install <source>')
+        console.error('Source can be a local path (./, /, ~) or a GitHub ref (owner/repo)')
+        process.exit(1)
+      }
+
+      const flags = args.slice(1)
+      const hasAnyFlag = flags.some(f => ['--global', '--project', '--claude', '--all'].includes(f))
+      const options = hasAnyFlag ? {
+        global: flags.includes('--global') || flags.includes('--all'),
+        claude: flags.includes('--claude') || flags.includes('--all'),
+        project: flags.includes('--project') || flags.includes('--all'),
+      } : {}
+
+      await installCommand(source, options)
+      break
+    }
+
+    case 'list':
+      await listCommand()
+      break
+
+    case 'remove': {
+      const slug = args[0]
+      if (!slug) {
+        console.error('Usage: rolecraft remove <slug>')
+        process.exit(1)
+      }
+      await removeCommand(slug)
+      break
+    }
+
+    case 'help':
+    case '--help':
+    case '-h':
+    default:
+      usage()
+      break
+  }
+}
+
+import { fileURLToPath } from 'node:url'
+import { realpathSync } from 'node:fs'
+
+export async function run() {
+  try {
+    await main()
+  } catch (err) {
+    console.error(`Error: ${err.message}`)
+    process.exit(1)
+  }
+}
+
+const isEntryPoint = process.argv[1]
+  && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+
+if (isEntryPoint) {
+  run()
+}

package/bin/rolecraft.test.js

@@ -0,0 +1,174 @@
+import { describe, it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
+import { mkdir, rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+
+let tempDir, rolecraftModule, origArgv, origExit
+
+before(async () => {
+  tempDir = mkdtempSync(join(tmpdir(), 'rolecraft-cli-test-'))
+  process.env.HOME = tempDir
+  await mkdir(join(tempDir, '.agents'), { recursive: true })
+
+  origArgv = process.argv
+  origExit = process.exit
+  rolecraftModule = await import('./rolecraft.js')
+})
+
+after(async () => {
+  process.exit = origExit
+  process.argv = origArgv
+  await rm(tempDir, { recursive: true, force: true })
+})
+
+function capture(name, obj = console) {
+  const logs = []
+  const orig = obj[name]
+  obj[name] = (...args) => {
+    if (args.length) logs.push(String(args[0]))
+  }
+  return { logs, restore: () => { obj[name] = orig } }
+}
+
+function mockExit() {
+  const orig = process.exit
+  process.exit = (code) => { throw new Error(`exit:${code}`) }
+  return () => { process.exit = orig }
+}
+
+describe('rolecraft CLI', () => {
+  it('shows usage for help command', async () => {
+    process.argv = ['node', 'rolecraft', 'help']
+    const { logs, restore } = capture('log')
+
+    await rolecraftModule.main()
+
+    assert.ok(logs.some(l => l.includes('rolecraft')))
+    restore()
+  })
+
+  it('shows usage for --help flag', async () => {
+    process.argv = ['node', 'rolecraft', '--help']
+    const { logs, restore } = capture('log')
+
+    await rolecraftModule.main()
+
+    assert.ok(logs.some(l => l.includes('rolecraft')))
+    restore()
+  })
+
+  it('shows usage for unknown command', async () => {
+    process.argv = ['node', 'rolecraft', 'unknown']
+    const { logs, restore } = capture('log')
+
+    await rolecraftModule.main()
+
+    assert.ok(logs.some(l => l.includes('rolecraft')))
+    restore()
+  })
+
+  it('errors when install has no source', async () => {
+    process.argv = ['node', 'rolecraft', 'install']
+    const { logs: errors, restore: restoreErr } = capture('error')
+    const restoreExit = mockExit()
+
+    try {
+      await rolecraftModule.main()
+    } catch (e) {
+      assert.ok(e.message.includes('exit:1'))
+    }
+
+    assert.ok(errors.some(e => e.includes('Usage: rolecraft install <source>')))
+    restoreErr()
+    restoreExit()
+  })
+
+  it('runs install with --global flag', async () => {
+    const skillDir = join(tempDir, 'my-cli-skill')
+    mkdirSync(skillDir, { recursive: true })
+    writeFileSync(join(skillDir, 'SKILL.md'), '# slug: cli/cli-skill\nname: cli-skill\nContent')
+
+    process.argv = ['node', 'rolecraft', 'install', skillDir, '--global']
+    const { logs, restore } = capture('log')
+
+    await rolecraftModule.main()
+
+    assert.ok(logs.some(l => l.includes('Installed')))
+    restore()
+  })
+
+  it('errors when remove has no slug', async () => {
+    process.argv = ['node', 'rolecraft', 'remove']
+    const { logs: errors, restore: restoreErr } = capture('error')
+    const restoreExit = mockExit()
+
+    try {
+      await rolecraftModule.main()
+    } catch (e) {
+      assert.ok(e.message.includes('exit:1'))
+    }
+
+    assert.ok(errors.some(e => e.includes('Usage: rolecraft remove <slug>')))
+    restoreErr()
+    restoreExit()
+  })
+
+  it('dispatches list command without errors', async () => {
+    process.argv = ['node', 'rolecraft', 'list']
+
+    await rolecraftModule.main()
+
+    assert.ok(true)
+  })
+
+  it('runs remove command with existing skill', async () => {
+    const skillDir = join(tempDir, 'removable-skill')
+    mkdirSync(skillDir, { recursive: true })
+    writeFileSync(join(skillDir, 'SKILL.md'), '# slug: test/removable\nname: removable\nContent')
+
+    process.argv = ['node', 'rolecraft', 'install', skillDir, '--global']
+    await rolecraftModule.main()
+
+    process.argv = ['node', 'rolecraft', 'remove', 'test/removable']
+    const { logs, restore } = capture('log')
+
+    await rolecraftModule.main()
+
+    assert.ok(logs.some(l => l.includes('Removed')))
+    restore()
+  })
+
+  it('runs remove command with nonexistent skill', async () => {
+    process.argv = ['node', 'rolecraft', 'remove', 'nonexistent']
+    const { logs: errors, restore: restoreErr } = capture('error')
+    const restoreExit = mockExit()
+
+    try {
+      await rolecraftModule.main()
+    } catch (e) {
+      assert.ok(e.message.includes('exit:1'))
+    }
+
+    assert.ok(errors.some(e => e.includes('not found')))
+    restoreErr()
+    restoreExit()
+  })
+
+  it('run() catches errors', async () => {
+    process.argv = ['node', 'rolecraft', 'install']
+    const { logs: errors, restore: restoreErr } = capture('error')
+    const restoreExit = mockExit()
+
+    try {
+      await rolecraftModule.run()
+    } catch (e) {
+      assert.ok(e.message.includes('exit:1'))
+    }
+
+    assert.ok(errors.some(e => e.includes('Usage: rolecraft install <source>')))
+    restoreErr()
+    restoreExit()
+  })
+})

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "rolecraft",
+  "version": "0.1.0",
+  "description": "Install AI agent skills as roles & behaviors directly from any source — zero-dependency CLI for opencode, claude-code, cursor, and more",
+  "type": "module",
+  "bin": {
+    "rolecraft": "bin/rolecraft.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "preferGlobal": true,
+  "keywords": [
+    "skill",
+    "skills",
+    "role",
+    "cli",
+    "agent",
+    "ai",
+    "rolecraft",
+    "opencode",
+    "claude-code",
+    "cursor",
+    "agentskill",
+    "zero-dependency"
+  ],
+  "author": "Samet ÇELİKBIÇAK",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sametcelikbicak/rolecraft.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sametcelikbicak/rolecraft/issues"
+  },
+  "homepage": "https://github.com/sametcelikbicak/rolecraft#readme",
+  "scripts": {
+    "test": "node --test",
+    "test:coverage": "node --experimental-test-coverage --test"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/commands/install.js

@@ -0,0 +1,55 @@
+import { createInterface } from 'node:readline'
+import { stdin as input, stdout as output } from 'node:process'
+import { resolveSource } from '../utils/resolver.js'
+import { installSkill } from '../utils/installer.js'
+
+function askQuestion(query) {
+  const rl = createInterface({ input, output })
+  return new Promise(resolve => {
+    rl.question(query, answer => {
+      rl.close()
+      resolve(answer.trim().toLowerCase())
+    })
+  })
+}
+
+async function askScope() {
+  console.log('\nWhere do you want to install this skill?\n')
+  console.log('  1) Global (~/.agents/skills/) [default]')
+  console.log('  2) Project (./.agents/skills/)')
+  console.log('  3) Both\n')
+
+  const answer = await askQuestion('Choice [1/2/3] (default: 1): ')
+
+  switch (answer) {
+    case '2': return { global: false, project: true, claude: false }
+    case '3': return { global: true, project: true, claude: false }
+    default:  return { global: true, project: false, claude: false }
+  }
+}
+
+export async function installCommand(source, options) {
+  const hasScopeFlags = options.global || options.project || options.claude
+  const scope = hasScopeFlags ? options : await askScope()
+
+  console.log(`\n🔍 Resolving skill from: ${source}`)
+  const resolved = await resolveSource(source)
+
+  console.log(`\n📦 Found skill: ${resolved.name}`)
+  console.log(`   Slug:     ${resolved.slug}`)
+  console.log(`   Owner:    ${resolved.owner}`)
+  console.log(`   Files:    ${resolved.files.join(', ')}`)
+  console.log()
+
+  const targets = []
+  if (scope.global) targets.push('agents')
+  if (scope.claude) targets.push('claude')
+  if (scope.project) targets.push('project')
+
+  const results = await installSkill(resolved, targets)
+
+  console.log('✅ Installed successfully:\n')
+  for (const r of results) {
+    console.log(`   ${r.label} → ${r.path}`)
+  }
+}

package/src/commands/install.test.js

@@ -0,0 +1,90 @@
+import { describe, it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
+import { mkdir, rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+
+let tempDir, installModule
+
+before(async () => {
+  tempDir = mkdtempSync(join(tmpdir(), 'rolecraft-install-cmd-test-'))
+  process.env.HOME = tempDir
+
+  const skillDir = join(tempDir, 'test-skill')
+  mkdirSync(skillDir, { recursive: true })
+  writeFileSync(join(skillDir, 'SKILL.md'), '# slug: ns/test-cmd\nname: test-cmd\n# owner: tester\nContent')
+  writeFileSync(join(skillDir, 'extra.js'), 'x')
+
+  await mkdir(join(tempDir, '.agents'), { recursive: true })
+
+  installModule = await import('./install.js')
+})
+
+after(async () => {
+  await rm(tempDir, { recursive: true, force: true })
+})
+
+function capture(name) {
+  const orig = console[name]
+  const logs = []
+  console[name] = (...args) => {
+    if (args.length) logs.push(String(args[0]))
+  }
+  return { logs, restore: () => { console[name] = orig } }
+}
+
+describe('install command', () => {
+  it('installs with --global flag', async () => {
+    const { logs, restore } = capture('log')
+
+    await installModule.installCommand(join(tempDir, 'test-skill'), { global: true })
+
+    assert.ok(logs.some(l => l.includes('Installed')))
+    restore()
+  })
+
+  it('installs with --project flag', async () => {
+    const origCwd = process.cwd
+    process.cwd = () => tempDir
+    const { logs, restore } = capture('log')
+
+    await installModule.installCommand(join(tempDir, 'test-skill'), { project: true })
+
+    assert.ok(logs.some(l => l.includes('Installed')))
+    restore()
+    process.cwd = origCwd
+  })
+
+  it('installs with --claude flag', async () => {
+    const { logs, restore } = capture('log')
+
+    await installModule.installCommand(join(tempDir, 'test-skill'), { claude: true })
+
+    assert.ok(logs.some(l => l.includes('Installed')))
+    restore()
+  })
+
+  it('installs with default scope (global) when no flags given', async () => {
+    const { logs, restore } = capture('log')
+
+    await installModule.installCommand(join(tempDir, 'test-skill'), {})
+
+    assert.ok(logs.some(l => l.includes('Installed')))
+    restore()
+  })
+
+  it('installs with --all scope', async () => {
+    const origCwd = process.cwd
+    process.cwd = () => tempDir
+    const { logs, restore } = capture('log')
+
+    await installModule.installCommand(join(tempDir, 'test-skill'), {
+      global: true, project: true, claude: true,
+    })
+
+    assert.ok(logs.some(l => l.includes('Installed')))
+    restore()
+    process.cwd = origCwd
+  })
+})

package/src/commands/list.js

@@ -0,0 +1,26 @@
+import { readLock } from '../utils/lockfile.js'
+
+export async function listCommand() {
+  const lock = await readLock()
+  const skills = Object.entries(lock.skills)
+
+  if (skills.length === 0) {
+    console.log('No skills installed.')
+    return
+  }
+
+  console.log('Installed skills:\n')
+  for (const [slug, entry] of skills) {
+    const date = entry.installedAt
+      ? new Date(entry.installedAt).toLocaleDateString()
+      : 'unknown'
+    console.log(`   ${slug}`)
+    console.log(`   ├─ Installed: ${date}`)
+    if (entry.source) console.log(`   ├─ Source: ${entry.source}`)
+    if (entry.sourceType) console.log(`   └─ Type: ${entry.sourceType}`)
+    console.log()
+  }
+
+  const count = skills.length
+  console.log(`${count} skill(s) total.`)
+}