myskill 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sarfraz Ahmed
+
+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,141 @@
+# myskill
+
+> The Universal CLI for AI Agent Skills
+
+`myskill` is a powerful command-line tool designed to standardize the creation, management, and sharing of "Agent Skills" across the modern AI coding ecosystem. It abstracts away the differences between platforms like **Claude Code**, **OpenCode**, **OpenAI Codex**, and **Gemini CLI**, allowing developers to write skills once and deploy them anywhere.
+
+## 🚀 Key Features
+
+- **Unified Creation**: Generate valid, schema-compliant skills for any supported platform.
+- **Strict Validation**: Ensure your skills meet platform requirements (YAML frontmatter, file structure).
+- **Cross-Platform**: Works seamlessly on Windows, macOS, and Linux.
+- **Workspace Management**: Initialize skill workspaces and run experimental skills locally.
+- **Discovery**: Fuzzy find installed skills across all global and local scopes.
+- **Git Integration**: Pull and update skills directly from remote repositories.
+- **Interactive Experience**: Cancel any interactive prompt with **Escape** key or **Ctrl+C**.
+- **Configurable Paths**: Override default platform paths for custom setups.
+
+## 📦 Installation
+
+```bash
+npm install -g myskill
+```
+
+## 🛠️ Supported Platforms
+
+| Platform         | ID         | Key Features Supported                    |
+| :--------------- | :--------- | :---------------------------------------- |
+| **Claude Code**  | `claude`   | `allowed-tools`, `context: fork`, `hooks` |
+| **OpenCode**     | `opencode` | `license`, `compatibility`, `metadata`    |
+| **OpenAI Codex** | `codex`    | `short-description` metadata              |
+| **Gemini CLI**   | `gemini`   | Standard skill structure                  |
+
+## 📖 Usage Guide
+
+### Creating Skills
+
+Create a new skill interactively:
+
+```bash
+myskill create
+# Cancel anytime with Escape key or Ctrl+C
+```
+
+Or use flags for automation:
+
+```bash
+myskill create \
+  --name "git-helper" \
+  --platform claude \
+  --description "Automates complex git workflows" \
+  --scope project \
+  --non-interactive
+```
+
+### Discovering Skills
+
+List all installed skills for a platform:
+
+```bash
+myskill list --platform claude
+```
+
+Find a skill by name or description (supports fuzzy search):
+
+```bash
+myskill find "deploy"
+```
+
+Validate a skill's structure and frontmatter:
+
+```bash
+myskill validate ./git-helper
+```
+
+Run a skill script (experimental):
+
+```bash
+myskill run ./git-helper -- arg1 arg2
+```
+
+### Sharing Skills
+
+Install a local skill directory to the global platform path:
+
+```bash
+myskill install ./my-local-skill --platform claude
+```
+
+Pull (clone/update) a skill from a Git repository:
+
+```bash
+myskill pull https://github.com/username/awesome-skill.git --platform opencode
+```
+
+Convert a skill from one platform format to another:
+
+```bash
+myskill convert ./claude-skill --to opencode
+```
+
+Uninstall a skill:
+
+```bash
+myskill uninstall git-helper --platform claude
+```
+
+### Configuration & Health
+
+Override default paths (useful for custom setups):
+
+```bash
+myskill config set claude.path "/custom/path/to/skills"
+myskill config list
+```
+
+Check system health (Git, permissions, paths):
+
+```bash
+myskill doctor
+```
+
+## 🔧 Command Reference
+
+| Command     | Description                                                            | Usage                                   | Options                                                                                                                                                                                                                                                                                                                                     |
+| ----------- | ---------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `create`    | Create a new skill interactively or via flags.                         | `myskill create [options]`              | `-n, --name <name>`: Skill name (lowercase alphanumeric with hyphens)<br>`-p, --platform <platform>`: Target platform (claude, opencode, codex, gemini)<br>`-d, --description <description>`: Skill description<br>`-s, --scope <scope>`: Scope (global, project). Default: project<br>`--non-interactive`: Run without interactive prompts |
+| `list`      | List all installed skills for a platform.                              | `myskill list [options]`                | `-p, --platform <platform>`: Filter by platform                                                                                                                                                                                                                                                                                             |
+| `find`      | Find skills by name or description with fuzzy search.                  | `myskill find [query] [options]`        | `[query]`: Search query (supports fuzzy matching)<br>`-p, --platform <platform>`: Filter by platform                                                                                                                                                                                                                                        |
+| `validate`  | Validate a skill's structure and frontmatter against platform schemas. | `myskill validate [path] [options]`     | `[path]`: Path to skill directory. Default: current directory<br>`-p, --platform <platform>`: Validate against specific platform                                                                                                                                                                                                            |
+| `run`       | Run a skill script (experimental).                                     | `myskill run <skill> [args...]`         | `<skill>`: Skill name or path<br>`[args...]`: Arguments to pass to the skill script                                                                                                                                                                                                                                                         |
+| `install`   | Install a local skill directory to the global platform path.           | `myskill install <path> [options]`      | `<path>`: Path to skill directory<br>`-p, --platform <platform>`: Target platform<br>`-f, --force`: Force overwrite if already installed<br>`--non-interactive`: Run without interactive prompts                                                                                                                                            |
+| `pull`      | Pull (clone/update) a skill from a Git repository.                     | `myskill pull <repoUrl> [options]`      | `<repoUrl>`: Repository URL<br>`-p, --platform <platform>`: Target platform<br>`-n, --name <name>`: Custom skill name<br>`--non-interactive`: Skip prompts                                                                                                                                                                                  |
+| `convert`   | Convert a skill from one platform format to another.                   | `myskill convert <path> [options]`      | `<path>`: Path to source skill<br>`-t, --to <platform>`: Target platform<br>`-f, --force`: Force overwrite if output exists<br>`--non-interactive`: Reserved for future interactive features                                                                                                                                                |
+| `uninstall` | Uninstall a skill from global or local paths.                          | `myskill uninstall [name] [options]`    | `[name]`: Skill name<br>`-p, --platform <platform>`: Platform context<br>`--non-interactive`: Skip confirmation                                                                                                                                                                                                                             |
+| `config`    | Manage configuration settings (e.g., custom paths).                    | `myskill config <action> [key] [value]` | `<action>`: Action (get, set, list)<br>`[key]`: Config key (e.g., claude.path)<br>`[value]`: Config value (for set)                                                                                                                                                                                                                         |
+| `doctor`    | Check system health (Git, permissions, paths).                         | `myskill doctor`                        | None                                                                                                                                                                                                                                                                                                                                        |
+
+## 🗺️ Roadmap
+
+- [ ] **Ecosystem & Sharing**: Implement `myskill publish` to upload skills to a central registry (S3, GitHub Packages, or a custom index).
+- [ ] **Generate from Prompt**: `myskill create --prompt "A skill that checks AWS S3 buckets"`. Use an LLM API to generate the `SKILL.md` content and initial script code.

package/bin/myskill.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { createRequire } from "module";
+
+const require = createRequire(import.meta.url);
+const packageJson = require("../package.json");
+
+const program = new Command();
+
+program
+  .name("myskill")
+  .description("CLI tool for creating and managing AI agent skills")
+  .version(packageJson.version);
+
+program
+  .command("create")
+  .description("Create a new skill")
+  .option("-n, --name <name>", "Skill name")
+  .option(
+    "-p, --platform <platform>",
+    "Target platform (claude, opencode, codex, gemini)",
+  )
+  .option("-d, --description <description>", "Skill description")
+  .option("-s, --scope <scope>", "Scope (global, project)", "project")
+  .option("--non-interactive", "Run without interactive prompts")
+  .action(async (options) => {
+    const { create } = await import("../src/commands/create.js");
+    create(options);
+  });
+
+program
+  .command("validate")
+  .description("Validate a skill")
+  .argument("[path]", "Path to skill directory", ".")
+  .option("-p, --platform <platform>", "Validate against specific platform")
+  .action(async (pathStr, options) => {
+    const { validate } = await import("../src/commands/validate.js");
+    validate(pathStr, options);
+  });
+
+program
+  .command("list")
+  .description("List installed skills")
+  .option("-p, --platform <platform>", "Filter by platform")
+  .action(async (options) => {
+    const { list } = await import("../src/commands/list.js");
+    list(options);
+  });
+
+program
+  .command("install")
+  .description("Install a skill")
+  .argument("<path>", "Path to skill directory")
+  .option("-p, --platform <platform>", "Target platform")
+  .option("-f, --force", "Force overwrite if installed")
+  .option("--non-interactive", "Run without interactive prompts")
+  .action(async (pathStr, options) => {
+    const { install } = await import("../src/commands/install.js");
+    install(pathStr, options);
+  });
+
+program
+  .command("convert")
+  .description("Convert a skill to another format")
+  .argument("<path>", "Path to source skill")
+  .option("-t, --to <platform>", "Target platform")
+  .option("-f, --force", "Force overwrite if output exists")
+  .option("--non-interactive", "Fail if output exists (unless forced)")
+  .action(async (pathStr, options) => {
+    const { convert } = await import("../src/commands/convert.js");
+    convert(pathStr, options);
+  });
+
+program
+  .command("find")
+  .description("Find skills")
+  .argument("[query]", "Search query")
+  .option("-p, --platform <platform>", "Filter by platform")
+  .action(async (query, options) => {
+    const { find } = await import("../src/commands/find.js");
+    find(query, options);
+  });
+
+program
+  .command("uninstall")
+  .description("Uninstall a skill")
+  .argument("[name]", "Skill name")
+  .option("-p, --platform <platform>", "Platform context")
+  .option("--non-interactive", "Skip confirmation")
+  .action(async (name, options) => {
+    const { uninstall } = await import("../src/commands/uninstall.js");
+    uninstall(name, options);
+  });
+
+program
+  .command("config")
+  .description("Manage configuration")
+  .argument("<action>", "Action: get, set, list")
+  .argument("[key]", "Config key (e.g. claude.path)")
+  .argument("[value]", "Config value")
+  .action(async (action, key, value) => {
+    const { config } = await import("../src/commands/config.js");
+    config(action, key, value);
+  });
+
+program
+  .command("pull")
+  .description("Pull or clone a skill from a git repository")
+  .argument("<repoUrl>", "Repository URL")
+  .option("-p, --platform <platform>", "Target platform")
+  .option("-n, --name <name>", "Custom skill name")
+  .option("--non-interactive", "Skip prompts")
+  .action(async (repoUrl, options) => {
+    const { pull } = await import("../src/commands/pull.js");
+    pull(repoUrl, options);
+  });
+
+program
+  .command("doctor")
+  .description("Check system health and configuration")
+  .action(async () => {
+    const { doctor } = await import("../src/commands/doctor.js");
+    doctor();
+  });
+
+program
+  .command("run")
+  .description("Run a skill script (experimental)")
+  .argument("<skill>", "Skill name or path")
+  .argument("[args...]", "Arguments to pass to the skill script")
+  .action(async (skillName, args) => {
+    const { run } = await import("../src/commands/run.js");
+    run(skillName, args);
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "myskill",
+  "version": "1.0.0",
+  "description": "CLI tool for creating and managing AI agent skills",
+  "author": "Sarfraz Ahmed <sarfraznawaz2005@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/sarfraznawaz2005/myskill#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sarfraznawaz2005/myskill.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sarfraznawaz2005/myskill/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./bin/myskill.js",
+  "bin": {
+    "myskill": "bin/myskill.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "prettier --write \"src/**/*.js\" \"bin/**/*.js\"",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "cli",
+    "ai",
+    "skills",
+    "claude",
+    "opencode"
+  ],
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "env-paths": "^3.0.0",
+    "fs-extra": "^11.3.0",
+    "fuse.js": "^7.1.0",
+    "inquirer": "^12.4.2",
+    "js-yaml": "^4.1.0",
+    "prettier": "^3.8.0",
+    "simple-git": "^3.30.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.17"
+  }
+}

package/src/commands/config.js

@@ -0,0 +1,38 @@
+import chalk from "chalk";
+import { getConfig, setConfig } from "../utils/config.js";
+
+export async function config(action, key, value) {
+  if (action === "list") {
+    const cfg = await getConfig();
+    console.log(JSON.stringify(cfg, null, 2));
+    return;
+  }
+
+  if (action === "get") {
+    if (!key) {
+      console.error(chalk.red("Error: Key required for get"));
+      process.exit(1);
+    }
+    const cfg = await getConfig();
+    // Simple deep get support
+    const keys = key.split(".");
+    let val = cfg;
+    for (const k of keys) {
+      val = val ? val[k] : undefined;
+    }
+    console.log(val !== undefined ? val : chalk.gray("undefined"));
+    return;
+  }
+
+  if (action === "set") {
+    if (!key || !value) {
+      console.error(chalk.red("Error: Key and Value required for set"));
+      process.exit(1);
+    }
+    await setConfig(key, value);
+    console.log(chalk.green(`Set ${key} = ${value}`));
+    return;
+  }
+
+  console.error(chalk.red(`Unknown action: ${action}`));
+}

package/src/commands/convert.js

@@ -0,0 +1,111 @@
+import fs from "fs-extra";
+import path from "path";
+import chalk from "chalk";
+import yaml from "js-yaml";
+import { platforms } from "../platforms/index.js";
+import { generateSkill } from "../templates/generateSkill.js";
+
+export async function convert(sourcePath, options = {}) {
+  const resolvedSource = path.resolve(sourcePath);
+
+  if (!options.to) {
+    console.error(chalk.red("Error: Target platform (--to) is required"));
+    process.exit(1);
+  }
+
+  const targetPlatform = platforms[options.to];
+  if (!targetPlatform) {
+    console.error(chalk.red(`Error: Unknown target platform '${options.to}'`));
+    process.exit(1);
+  }
+
+  if (!(await fs.pathExists(path.join(resolvedSource, "SKILL.md")))) {
+    console.error(chalk.red(`Error: SKILL.md not found in ${resolvedSource}`));
+    process.exit(1);
+  }
+
+  const content = await fs.readFile(
+    path.join(resolvedSource, "SKILL.md"),
+    "utf8",
+  );
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+
+  if (!match) {
+    console.error(chalk.red("Error: Invalid front matter in source file"));
+    process.exit(1);
+  }
+
+  let sourceFm;
+  try {
+    sourceFm = yaml.load(match[1]);
+  } catch (e) {
+    console.error(chalk.red("Error: YAML parsing failed"));
+    process.exit(1);
+  }
+
+  const markdownBody = content.replace(/^---\n[\s\S]*?\n---/, "").trim();
+
+  const newFm = {
+    name: sourceFm.name,
+    description: sourceFm.description,
+  };
+
+  if (targetPlatform.id === "opencode") {
+    newFm.compatibility = "opencode";
+    if (sourceFm.license) newFm.license = sourceFm.license;
+
+    const standardKeys = ["name", "description", "license", "compatibility"];
+    const extras = {};
+    for (const key of Object.keys(sourceFm)) {
+      if (!standardKeys.includes(key)) extras[key] = sourceFm[key];
+    }
+    if (Object.keys(extras).length > 0) newFm.metadata = extras;
+  } else if (targetPlatform.id === "codex") {
+    newFm.metadata = { "short-description": sourceFm.description.slice(0, 50) };
+  } else if (targetPlatform.id === "claude") {
+    if (sourceFm["allowed-tools"])
+      newFm["allowed-tools"] = sourceFm["allowed-tools"];
+  }
+
+  const newContent = generateSkill(newFm, markdownBody);
+  const targetDirName = `${sourceFm.name}_${targetPlatform.id}`;
+  const targetDir = path.join(path.dirname(resolvedSource), targetDirName);
+
+  if (await fs.pathExists(targetDir)) {
+    if (options.force) {
+      // Continue
+    } else if (options.nonInteractive) {
+      console.error(
+        chalk.red(
+          `Error: Target directory ${targetDir} already exists. Use --force to overwrite.`,
+        ),
+      );
+      process.exit(1);
+    } else {
+      console.error(
+        chalk.red(`Error: Target directory ${targetDir} already exists`),
+      );
+      process.exit(1);
+    }
+  }
+
+  try {
+    await fs.ensureDir(targetDir);
+    await fs.writeFile(path.join(targetDir, "SKILL.md"), newContent);
+
+    const items = await fs.readdir(resolvedSource);
+    for (const item of items) {
+      if (item !== "SKILL.md" && item !== ".git" && item !== "node_modules") {
+        await fs.copy(
+          path.join(resolvedSource, item),
+          path.join(targetDir, item),
+        );
+      }
+    }
+
+    console.log(chalk.green(`Successfully converted skill to ${targetDir}`));
+  } catch (e) {
+    console.error(chalk.red(`Conversion failed: ${e.message}`));
+    process.exit(1);
+  }
+}