@fakhrulraharjo/opencode-skill-creator 0.3.0

package/README.md

@@ -0,0 +1,343 @@
+# opencode-skill-creator
+
+[![npm](https://img.shields.io/npm/v/opencode-skill-creator)](https://www.npmjs.com/package/opencode-skill-creator)
+
+A **skill + plugin** for [OpenCode](https://opencode.ai) that helps you create, test, and optimize other OpenCode skills.
+
+This is a faithful adaptation of Anthropic's official [skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator) for Claude Code, fully rewritten to work with OpenCode's extensibility mechanisms. The Python scripts from the original have been ported to TypeScript and packaged as an OpenCode plugin with custom tools.
+
+## Install
+
+Package: https://www.npmjs.com/package/opencode-skill-creator
+
+### Pick your option
+
+| If you are... | Use this |
+|---|---|
+| New to OpenCode / non-developer | **Option A (Recommended)** |
+| Already using other plugins | **Option B** |
+| Setting up all projects on your computer | **Option C (Global config)** |
+| Setting up only one project | **Option D (Project config)** |
+| Cannot use npm / offline environment | **Option E (Manual install)** |
+
+### Option A (Recommended): easiest setup for most users
+
+Run one command (global install, recommended):
+
+```bash
+npx opencode-skill-creator install --global
+```
+
+Optional checks:
+
+```bash
+npx opencode-skill-creator --version
+npx opencode-skill-creator --help
+npx opencode-skill-creator --about
+```
+
+What this command does:
+
+1. Creates/updates `~/.config/opencode/opencode.json`
+2. Adds `"opencode-skill-creator"` to the `plugin` array
+3. Leaves your existing plugins untouched
+
+Then:
+
+4. Restart OpenCode
+5. Ask OpenCode: `Create a skill that helps with Docker compose files`
+
+That's it.
+
+Manual equivalent for the same result:
+
+1. Open (or create) `~/.config/opencode/opencode.json`
+2. Paste this:
+
+```json
+{
+  "plugin": ["opencode-skill-creator"]
+}
+```
+
+3. Restart OpenCode.
+
+If you want project-only install instead, use:
+
+```bash
+npx opencode-skill-creator install --project
+```
+
+### Option B: you already have plugins
+
+If your file already has plugins, append this package to the list:
+
+```json
+{
+  "plugin": [
+    "your-existing-plugin",
+    "opencode-skill-creator"
+  ]
+}
+```
+
+Do not remove your existing plugins.
+
+### Option C: global config (works in all projects)
+
+Use global config when you want this plugin available everywhere.
+
+Command version:
+
+```bash
+npx opencode-skill-creator install --global
+```
+
+1. Open (or create) `~/.config/opencode/opencode.json`
+2. Add:
+
+```json
+{
+  "plugin": ["opencode-skill-creator"]
+}
+```
+
+3. Restart OpenCode.
+
+### Option D: project config (only one project)
+
+Use project config when you want this plugin only for one repo.
+
+Command version:
+
+```bash
+npx opencode-skill-creator install --project
+```
+
+1. Open (or create) `opencode.json` in that project root
+2. Add:
+
+```json
+{
+  "plugin": ["opencode-skill-creator"]
+}
+```
+
+3. Restart OpenCode in that project.
+
+### Option E: manual install (no npm)
+
+```bash
+git clone https://github.com/antongulin/opencode-skill-creator.git
+cd opencode-skill-creator
+
+# Install the skill (global)
+cp -r opencode-skill-creator/ ~/.config/opencode/skills/opencode-skill-creator/
+
+# Install the plugin (global)
+cp -r plugin/ ~/.config/opencode/plugins/skill-creator/
+```
+
+Then create `~/.config/opencode/package.json` if needed:
+
+```json
+{
+  "dependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  }
+}
+```
+
+### What happens after install
+
+After you add `opencode-skill-creator` and restart OpenCode:
+
+1. OpenCode installs the plugin from npm automatically.
+2. The npm package loads compiled JavaScript from `dist/skill-creator.js`.
+3. On first plugin startup, it auto-copies skill files to `~/.config/opencode/skills/opencode-skill-creator/`.
+4. Restart OpenCode after changing config because plugin config is loaded at startup.
+
+### Verify install
+
+Check that the skill file exists:
+
+```bash
+ls ~/.config/opencode/skills/opencode-skill-creator/SKILL.md
+```
+
+Then ask OpenCode:
+
+```text
+Use opencode-skill-creator to create a skill that helps with API documentation.
+```
+
+You should see it use the opencode-skill-creator workflow/tools.
+
+### Migration from the old `skill-creator` folder
+
+Earlier versions installed the bundled skill as the generic `skill-creator` skill. That could conflict with other plugins, including Superpowers, that also provide a skill with the same name.
+
+Current versions install the bundled skill as `opencode-skill-creator` instead. On startup, if the plugin finds an old plugin-owned folder at `~/.config/opencode/skills/skill-creator/`, it moves that folder to an inactive backup such as:
+
+```text
+~/.config/opencode/skills/skill-creator.opencode-skill-creator-backup-YYYYMMDDTHHMMSS/
+```
+
+The backup preserves user files and renames `SKILL.md` to `SKILL.md.backup` so OpenCode will not keep loading the old generic skill. If the old `skill-creator` folder does not contain the plugin's `.opencode-skill-creator-version` marker, the plugin leaves it untouched because it may belong to another plugin or a manually installed skill.
+
+### Troubleshooting
+
+- `I don't have opencode.json or opencode.jsonc`: create one in project root (or use global config path).
+- `Nothing changed after edit`: fully restart OpenCode.
+- `I already had plugins`: keep them; just add `opencode-skill-creator` to the same array.
+- `I want a clean reinstall`: delete `~/.config/opencode/skills/opencode-skill-creator/` and restart OpenCode.
+- `I still see another skill-creator skill`: if `~/.config/opencode/skills/skill-creator/` has no `.opencode-skill-creator-version` marker, it is not managed by this plugin and must be reviewed separately.
+- `npx command failed`: run `npx opencode-skill-creator --help` and then use `install` or `install --global`.
+
+### Compatibility fixes
+
+- The installer supports existing `opencode.jsonc` files and preserves JSONC comments when adding the plugin entry.
+- The npm package loads compiled JavaScript from `dist/skill-creator.js` so OpenCode does not need to strip TypeScript under `node_modules`.
+- The plugin resolves bundled assets with `import.meta.url`, which works in OpenCode Desktop runtimes where `import.meta.path` is unavailable.
+- Trigger evaluations run with an explicit OpenCode agent, defaulting to `build`, to avoid false 0% scores from delegating default agents.
+- Release-safety tests now verify the compiled plugin entrypoint imports correctly and that `dist/` was built from the current TypeScript sources.
+
+### For LLMs / automation (compact)
+
+```json
+{ "plugin": ["opencode-skill-creator"] }
+```
+
+## What it does
+
+When loaded, this skill guides OpenCode through the full skill development lifecycle:
+
+1. **Analyze** the user's request and determine what kind of skill to build
+2. **Create** a well-structured skill with proper frontmatter, SKILL.md, and supporting files
+3. **Generate** an eval set of test queries (should-trigger and should-not-trigger)
+4. **Evaluate** the skill's description by testing whether it triggers correctly
+5. **Optimize** the description through iterative improvement loops
+6. **Benchmark** skill performance with variance analysis
+7. **Install** the skill to the project or global OpenCode skills directory
+
+## Plugin tools
+
+The plugin registers these custom tools that OpenCode can call:
+
+| Tool | Purpose |
+|------|---------|
+| `skill_validate` | Validate SKILL.md structure and frontmatter |
+| `skill_parse` | Parse SKILL.md and extract name/description |
+| `skill_eval` | Test trigger accuracy for eval queries |
+| `skill_improve_description` | LLM-powered description improvement |
+| `skill_optimize_loop` | Full eval->improve optimization loop |
+| `skill_aggregate_benchmark` | Aggregate grading results into statistics |
+| `skill_generate_report` | Generate HTML optimization report |
+| `skill_serve_review` | Start the eval review viewer (HTTP server) |
+| `skill_stop_review` | Stop a running review server |
+| `skill_export_static_review` | Generate standalone HTML review file |
+| `skill_add_gold_standard` | Save an exemplary skill response for future guidance |
+| `skill_list_gold_standards` | List saved gold-standard examples for a skill |
+| `skill_remove_gold_standard` | Remove a saved gold-standard example |
+| `skill_get_gold_advice` | Get guidance from saved gold-standard examples |
+
+### Review workflow guard (strict by default)
+
+The review launch tools now enforce paired comparison data by default:
+
+- `skill_serve_review` and `skill_export_static_review` require each `eval-*` directory to include:
+  - `with_skill`
+  - baseline (`without_skill` or `old_skill`)
+- If pairs are missing, the tools fail fast with a clear list of missing items.
+- Override only when intentionally reviewing partial data by passing `allowPartial: true`.
+- If `benchmarkPath` is omitted, the tools auto-generate `benchmark.json` and `benchmark.md` in the workspace.
+
+### Skill draft staging (recommended)
+
+When creating new skills, use a staging path in the system temp directory outside your current repository:
+
+- Unix/macOS draft skill path: `/tmp/opencode-skills/<skill-name>/` (or `$TMPDIR/opencode-skills/<skill-name>/`)
+- Unix/macOS eval workspace path: `/tmp/opencode-skills/<skill-name>-workspace/`
+- Windows draft/eval paths: `%TEMP%\\opencode-skills\\<skill-name>\\` and `%TEMP%\\opencode-skills\\<skill-name>-workspace\\`
+- Install only the final validated skill to:
+  - project: `.opencode/skills/<skill-name>/`
+  - global: `~/.config/opencode/skills/<skill-name>/`
+
+This keeps plugin/source repositories clean while preserving the full eval loop.
+
+## Usage
+
+Once installed, OpenCode will automatically detect the skill when you ask it to create or improve a skill. For example:
+
+- "Create a skill that helps with Docker compose files"
+- "Build me a skill for generating API documentation"
+- "Help me make a skill that assists with database migrations"
+- "Optimize the description of my existing skill"
+
+OpenCode will load the opencode-skill-creator instructions and use the plugin tools to walk through the full workflow.
+
+## Architecture
+
+This project has two components:
+
+| Component | What it is |
+|-----------|-----------|
+| **Skill** | Markdown instructions (SKILL.md + agents + templates) that tell the agent how to create, evaluate, and improve skills |
+| **Plugin** | TypeScript module that registers custom tools for validation, eval, benchmarking, and review |
+
+The skill provides the workflow knowledge; the plugin provides the executable tools the agent calls during that workflow.
+
+On first startup, the plugin automatically copies the bundled skill files to `~/.config/opencode/skills/opencode-skill-creator/`. If you need to reinstall the skill (e.g., after an update), delete that directory and restart OpenCode.
+
+## Project structure
+
+```
+opencode-skill-creator/
+├── README.md
+├── LICENSE                            # Apache 2.0
+├── opencode-skill-creator/            # The SKILL
+│   ├── SKILL.md                       # Main skill instructions
+│   ├── agents/
+│   │   ├── grader.md                  # Assertion evaluation
+│   │   ├── analyzer.md                # Benchmark analysis
+│   │   └── comparator.md              # Blind A/B comparison
+│   ├── references/
+│   │   └── schemas.md                 # JSON schema definitions
+│   └── templates/
+│       └── eval-review.html           # Eval set review/edit UI
+└── plugin/                            # The PLUGIN (npm: opencode-skill-creator)
+    ├── package.json                   # npm package metadata
+    ├── skill-creator.ts               # Entry point — registers all tools
+    ├── skill/                         # Bundled copy of skill (auto-installed)
+    ├── lib/
+    │   ├── utils.ts                   # SKILL.md frontmatter parsing
+    │   ├── validate.ts                # Skill structure validation
+    │   ├── run-eval.ts                # Trigger evaluation via opencode run
+    │   ├── improve-description.ts     # LLM-powered description improvement
+    │   ├── run-loop.ts                # Eval→improve optimization loop
+    │   ├── aggregate.ts               # Benchmark aggregation
+    │   ├── report.ts                  # HTML report generation
+    │   └── review-server.ts           # Eval review HTTP server
+    └── templates/
+        └── viewer.html                # Eval review viewer UI
+```
+
+## Differences from the Anthropic original
+
+| Area | Anthropic (Claude Code) | This repo (OpenCode) |
+|------|------------------------|---------------------|
+| CLI invocation | `claude -p "prompt"` | `opencode run "prompt"` |
+| Skill location | `.claude/commands/` | `.opencode/skills/` |
+| Automation scripts | Python (`scripts/*.py`) | TypeScript plugin (`plugin/lib/*.ts`) |
+| Script execution | `python -m scripts.run_loop` | `skill_optimize_loop` tool call |
+| Eval viewer | `python generate_review.py` | `skill_serve_review` tool call |
+| Benchmarking | `python aggregate_benchmark.py` | `skill_aggregate_benchmark` tool call |
+| Dependencies | Python 3.11+, pyyaml | Bun (via OpenCode), @opencode-ai/plugin |
+| Packaging | `.skill` zip files | npm package + skill directory |
+| Subagents | Built-in subagent concept | Task tool with `general`/`explore` types |
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE) for details.
+
+Based on [anthropics/skills](https://github.com/anthropics/skills) by Anthropic.

package/bin/opencode-skill-creator.js

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs"
+import { applyEdits, modify, parse, printParseErrorCode } from "jsonc-parser"
+import { homedir } from "os"
+import { join, dirname } from "path"
+
+const PKG_PATH = new URL("../package.json", import.meta.url)
+const PACKAGE_NAME = "@fakhrulraharjo/opencode-skill-creator"
+const PLUGIN_LOAD_ERROR_PREFIX = `Failed to load plugin ${PACKAGE_NAME}:`
+
+function getVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(PKG_PATH, "utf-8"))
+    return pkg.version || "unknown"
+  } catch {
+    return "unknown"
+  }
+}
+
+function printHelp() {
+  console.log(`${PACKAGE_NAME} installer
+
+Links:
+  npm:  https://www.npmjs.com/package/${PACKAGE_NAME}
+  repo: https://github.com/fakhrulraharjo/opencode-skill-creator
+
+Usage:
+  npx ${PACKAGE_NAME} install [--global|--project]
+  npx ${PACKAGE_NAME} [--global|--project]
+  npx ${PACKAGE_NAME} --version
+  npx ${PACKAGE_NAME} --about
+
+Options:
+  --global    Update ~/.config/opencode/opencode.jsonc if present, otherwise opencode.json (default)
+  --project   Update ./opencode.jsonc if present, otherwise opencode.json in current directory
+  -v, --version  Show installer version
+  --about     Show package links
+  -h, --help  Show help
+`)
+}
+
+function printAbout() {
+  console.log(`${PACKAGE_NAME} ${getVersion()}
+npm:  https://www.npmjs.com/package/${PACKAGE_NAME}
+repo: https://github.com/fakhrulraharjo/opencode-skill-creator`)
+}
+
+function parseArgs(argv) {
+  const input = argv.slice(2)
+  const args = new Set(input)
+
+  if (args.has("-h") || args.has("--help")) {
+    return {
+      help: true,
+      about: false,
+      version: false,
+      global: false,
+      command: "install",
+    }
+  }
+
+  if (args.has("-v") || args.has("--version")) {
+    return {
+      help: false,
+      about: false,
+      version: true,
+      global: false,
+      command: "install",
+    }
+  }
+
+  if (args.has("--about")) {
+    return {
+      help: false,
+      about: true,
+      version: false,
+      global: false,
+      command: "install",
+    }
+  }
+
+  const hasProject = args.has("--project")
+  const hasGlobal = args.has("--global")
+
+  if (hasProject && hasGlobal) {
+    throw new Error("Use either --project or --global, not both.")
+  }
+
+  const command = input.find((arg) => !arg.startsWith("-")) || "install"
+  if (command !== "install") {
+    throw new Error(`Unknown command: ${command}`)
+  }
+
+  return {
+    help: false,
+    about: false,
+    version: false,
+    global: !hasProject,
+    command,
+  }
+}
+
+function getConfigPath(globalInstall) {
+  const configDir = globalInstall
+    ? join(homedir(), ".config", "opencode")
+    : process.cwd()
+  const jsoncPath = join(configDir, "opencode.jsonc")
+
+  if (existsSync(jsoncPath)) {
+    return jsoncPath
+  }
+
+  return join(configDir, "opencode.json")
+}
+
+function clearStaleOpenCodePackageCache() {
+  const currentVersion = getVersion()
+  if (currentVersion === "unknown") return { cleared: false, error: null }
+
+  const cacheDir = process.env.XDG_CACHE_HOME || join(homedir(), ".cache")
+  const packageCacheRoot = join(
+    cacheDir,
+    "opencode",
+    "packages",
+    `${PACKAGE_NAME}@latest`
+  )
+  const cachedPackageJson = join(
+    packageCacheRoot,
+    "node_modules",
+    ...PACKAGE_NAME.split("/"),
+    "package.json"
+  )
+
+  if (!existsSync(cachedPackageJson)) return { cleared: false, error: null }
+
+  try {
+    const cachedPackage = JSON.parse(readFileSync(cachedPackageJson, "utf-8"))
+    if (cachedPackage.version === currentVersion) {
+      return { cleared: false, error: null }
+    }
+  } catch {
+    // Broken cache entries should be removed so OpenCode can recreate them.
+  }
+
+  try {
+    rmSync(packageCacheRoot, { recursive: true, force: true })
+    return { cleared: true, error: null }
+  } catch (error) {
+    return { cleared: false, error }
+  }
+}
+
+function getDesktopGlobalDataPath() {
+  if (process.platform === "darwin") {
+    return join(
+      homedir(),
+      "Library",
+      "Application Support",
+      "ai.opencode.desktop",
+      "opencode.global.dat"
+    )
+  }
+
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA || join(homedir(), "AppData", "Roaming")
+    return join(appData, "ai.opencode.desktop", "opencode.global.dat")
+  }
+
+  const configDir = process.env.XDG_CONFIG_HOME || join(homedir(), ".config")
+  return join(configDir, "ai.opencode.desktop", "opencode.global.dat")
+}
+
+function clearPluginFaultNotifications() {
+  const dataPath = getDesktopGlobalDataPath()
+  if (!existsSync(dataPath)) return 0
+
+  try {
+    const data = JSON.parse(readFileSync(dataPath, "utf-8"))
+    if (typeof data.notification !== "string") return 0
+
+    const notifications = JSON.parse(data.notification)
+    if (!Array.isArray(notifications.list)) return 0
+
+    const originalCount = notifications.list.length
+    notifications.list = notifications.list.filter((notification) => {
+      if (notification?.type !== "error") return true
+
+      const message = notification?.error?.data?.message
+      return typeof message !== "string" || !message.startsWith(PLUGIN_LOAD_ERROR_PREFIX)
+    })
+
+    const removedCount = originalCount - notifications.list.length
+    if (removedCount === 0) return 0
+
+    data.notification = JSON.stringify(notifications)
+    writeFileSync(dataPath, `${JSON.stringify(data, null, "\t")}\n`, "utf-8")
+    return removedCount
+  } catch {
+    // Desktop state cleanup is best-effort; installation should not fail here.
+    return 0
+  }
+}
+
+function loadConfig(path) {
+  if (!existsSync(path)) {
+    return {
+      raw: "{\n}\n",
+      config: {},
+    }
+  }
+
+  const raw = readFileSync(path, "utf-8")
+  if (!raw.trim()) {
+    return {
+      raw: "{\n}\n",
+      config: {},
+    }
+  }
+
+  const errors = []
+  const config = parse(raw, errors, {
+    allowTrailingComma: true,
+    disallowComments: false,
+  })
+
+  if (errors.length) {
+    const message = errors
+      .map((error) => printParseErrorCode(error.error))
+      .join(", ")
+    throw new Error(
+      `Could not parse JSONC in ${path}: ${message}. Please fix the file, then re-run this installer.`
+    )
+  }
+
+  if (!config || typeof config !== "object" || Array.isArray(config)) {
+    throw new Error(`Expected top-level config in ${path} to be an object.`)
+  }
+
+  return { raw, config }
+}
+
+function saveConfig(path, raw, config) {
+  const formattingOptions = {
+    insertSpaces: true,
+    tabSize: 2,
+  }
+
+  const edits = Array.isArray(config.plugin)
+    ? modify(raw, ["plugin", -1], PACKAGE_NAME, {
+        formattingOptions,
+      })
+    : modify(raw, ["plugin"], [PACKAGE_NAME], {
+        formattingOptions,
+      })
+
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, applyEdits(raw, edits), "utf-8")
+}
+
+function ensurePlugin(config) {
+  if (typeof config.plugin === "undefined") {
+    return true
+  }
+
+  if (!Array.isArray(config.plugin)) {
+    throw new Error('Expected "plugin" to be an array in opencode config')
+  }
+
+  return !config.plugin.includes(PACKAGE_NAME)
+}
+
+function main() {
+  const { help, about, version, global } = parseArgs(process.argv)
+  if (help) {
+    printHelp()
+    process.exit(0)
+  }
+
+  if (about) {
+    printAbout()
+    process.exit(0)
+  }
+
+  if (version) {
+    console.log(getVersion())
+    process.exit(0)
+  }
+
+  const configPath = getConfigPath(global)
+  const { raw, config } = loadConfig(configPath)
+  const changed = ensurePlugin(config)
+  if (changed) {
+    saveConfig(configPath, raw, config)
+    console.log(`Updated ${configPath}`)
+    console.log(`Added "${PACKAGE_NAME}" to the "plugin" array.`)
+  } else {
+    console.log(`No changes needed for ${configPath}`)
+    console.log(`"${PACKAGE_NAME}" is already in the "plugin" array.`)
+  }
+
+  if (global) {
+    const cacheCleanup = clearStaleOpenCodePackageCache()
+    if (cacheCleanup.cleared) {
+      console.log(`Cleared stale OpenCode package cache for ${PACKAGE_NAME}.`)
+    } else if (cacheCleanup.error) {
+      console.warn(
+        `Could not clear stale OpenCode package cache: ${cacheCleanup.error.message}`
+      )
+    }
+  }
+
+  if (global) {
+    const removedNotifications = clearPluginFaultNotifications()
+    if (removedNotifications > 0) {
+      const noun = removedNotifications === 1 ? "notification" : "notifications"
+      console.log(
+        `Removed ${removedNotifications} stale ${PACKAGE_NAME} plugin fault ${noun}.`
+      )
+    }
+  }
+
+  console.log("\nNext steps:")
+  console.log("1) Restart OpenCode")
+  console.log("2) Ask: Create a skill that helps with API documentation")
+  console.log(
+    "\nOn first startup, the plugin auto-installs skill files to ~/.config/opencode/skills/opencode-skill-creator/"
+  )
+}
+
+try {
+  main()
+} catch (error) {
+  printHelp()
+  console.error()
+  console.error(error.message)
+  process.exit(1)
+}

package/dist/build-manifest.json

@@ -0,0 +1,6 @@
+{
+  "entrypoint": "skill-creator.ts",
+  "runtimeEntrypoint": "runtime-entry.ts",
+  "sourceHash": "3218735af8e73b6ab4a501b15bf9498e44327ad74d20252fad56a769dac2dcd7",
+  "builtAt": "2026-07-07T02:43:32.112Z"
+}