scaffold-agent-skill 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aryan
+
+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,145 @@
+# create-agent-skill
+
+Interactively scaffold agent skills and plugins from a single specification. Target multiple developer and agent platforms simultaneously with a clean, validated scaffolding directory.
+
+Supported platforms include:
+
+- Claude Code Plugin: Generates `.claude-plugin/plugin.json` and `skills/<id>/SKILL.md` alongside individual subagent prompts in `agents/`.
+- OpenAI Custom GPT Action: Generates a serialized `openapi.yaml` and a production-hardened Express server (with helmet, cors, input validation, global error handling, and pinned dependencies).
+- OpenClaw Gateway Skill: Generates `skills/<id>/SKILL.md` (and files for each subagent) alongside a config snippet in `openclaw.json`.
+- Google ADK / Gemini Agent: Generates `agent.py` and a `requirements.txt` file setup with `google-adk` dependencies.
+
+## Key Features
+
+- Interactive CLI: Step-by-step prompts to configure your main agent's ID, human-readable name, description, instructions, interfaces, platforms, and subagents.
+- Multi-Platform Code Generation: Generates required files for selected targets simultaneously.
+- Security and Robustness Guards:
+  - Path Traversal Guard: Prevents directory escape by checking that output directories remain inside the current working directory.
+  - Safe String Escaping: Employs proper escaping for Python strings (triple quote breaks), JavaScript template literals (backticks, expression placeholders), and comments (newlines, comment markers).
+  - Validation: Enforces constraints on ID characters (alphanumeric and hyphens only), ID length (maximum 64 characters), descriptions (maximum 200 characters), and instructions (maximum 2000 characters).
+  - ID Collision Resolution: Rejects duplicate subagent IDs and prevents subagent IDs from colliding with the main agent ID.
+  - Subagent Limit: Restricts subagents to a maximum of 20 to maintain manageable architectures.
+- Clean Casing Utilities: ASCII-safe camelCase, PascalCase, and snake_case converters that strip invalid characters to prevent compiler errors.
+- Overwrite Protection: Prompts for confirmation before writing files into directories that already contain content.
+
+## Quick Start (npx)
+
+You can run the tool interactively without installing it:
+
+```bash
+npx create-agent-skill
+```
+
+You will be prompted to:
+1. Provide a skill ID (kebab-case, e.g. "check-stock").
+2. Enter a human-readable name and description.
+3. Provide instructions for what the skill should do.
+4. Select the target interface types (CLI, service API, or developer SDK).
+5. Select platforms based on those interfaces (Claude Code, OpenAI, OpenClaw, Google ADK).
+6. Optionally configure up to 20 subagents (which will be linked as tools).
+7. Select or confirm the output directory.
+
+## Development and Local Installation
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/Aryan/create-agent-skill.git
+cd create-agent-skill
+npm install
+```
+
+Run the tool locally:
+
+```bash
+node bin/cli.js
+```
+
+Or link it globally to run it from anywhere on your machine:
+
+```bash
+npm link
+create-agent-skill
+```
+
+## Generated Outputs and Usage
+
+Running the tool with all options will generate the following structure in your output folder:
+
+```
+my-skill/
+├── .gitignore
+├── README.md
+├── .claude-plugin/
+│   └── plugin.json
+├── skills/
+│   ├── my-skill/
+│   │   └── SKILL.md
+│   └── my-subagent/
+│       └── SKILL.md
+├── agents/
+│   └── my-subagent.md
+├── openapi.yaml
+├── server/
+│   ├── index.js
+│   └── package.json
+├── agent.py
+├── requirements.txt
+└── openclaw.json
+```
+
+### Claude Code Plugin
+
+Test the skill locally in Claude Code:
+
+```bash
+cd my-skill
+claude --plugin-dir .
+```
+Inside Claude Code, invoke your plugin:
+```
+/my-skill
+```
+
+### OpenAI Custom GPT Action
+
+1. Install dependencies and start the Express server stub:
+   ```bash
+   cd my-skill/server
+   npm install
+   npm start
+   ```
+2. Deploy the server to a hosting provider with HTTPS support (e.g. Railway, Fly.io, Render).
+3. Update the `servers.url` field in the generated `openapi.yaml` with your deployed URL.
+4. Paste the contents of `openapi.yaml` into the Actions configuration page of your Custom GPT in ChatGPT.
+
+### OpenClaw Gateway Skill
+
+1. Copy the generated `skills/` folders to your OpenClaw skills directory (usually located at `~/.openclaw/skills/`).
+2. Merge the configuration options from the generated `openclaw.json` file into your global OpenClaw configuration file (`~/.openclaw/openclaw.json`).
+3. Run OpenClaw and invoke the skill using your main skill ID.
+
+### Google ADK / Gemini Agent
+
+1. Install the required libraries:
+   ```bash
+   pip install -r requirements.txt
+   ```
+2. Run your Gemini agent:
+   ```bash
+   python agent.py "Your query prompt here"
+   ```
+
+## Running Tests
+
+The codebase comes equipped with a comprehensive stress test suite to verify case converter logic, path containment, and escape safety across all platforms.
+
+Run the test suite with:
+
+```bash
+npm test
+```
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

package/bin/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+
+run(process.argv.slice(2)).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "scaffold-agent-skill",
+  "version": "0.1.0",
+  "description": "Interactively scaffold an AI agent skill or plugin (Claude Code plugin, OpenAI Custom GPT Action, OpenClaw, or Google ADK/Gemini) from a single spec.",
+  "type": "module",
+  "license": "MIT",
+  "author": "",
+  "bin": {
+    "scaffold-agent-skill": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test/smoke.mjs"
+  },
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "agent",
+    "skill",
+    "openai",
+    "custom-gpt",
+    "openclaw",
+    "google-adk",
+    "gemini",
+    "subagent",
+    "scaffold",
+    "cli",
+    "generator"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YOUR_GITHUB_USERNAME/create-agent-skill.git"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0",
+    "kleur": "^4.1.5",
+    "prompts": "^2.4.2"
+  }
+}

package/src/cli.js

@@ -0,0 +1,441 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import prompts from 'prompts';
+import kleur from 'kleur';
+import { generateClaudeCodePlugin } from './generators/claudeCode.js';
+import { generateOpenAiAction } from './generators/openaiAction.js';
+import { generateOpenclawPlugin } from './generators/openclaw.js';
+import { generateGeminiAdkAgent } from './generators/geminiAdk.js';
+
+const KEBAB_CASE_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+class CancelledError extends Error {
+  constructor() {
+    super('Cancelled');
+    this.name = 'CancelledError';
+  }
+}
+
+async function isDirectoryNotEmpty(dirPath) {
+  try {
+    const files = await fs.readdir(dirPath);
+    return files.length > 0;
+  } catch (err) {
+    return false;
+  }
+}
+
+async function writeGitignore(outDir) {
+  const content = `# Logs
+logs
+*.log
+npm-debug.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# OS files
+.DS_Store
+Thumbs.db
+`;
+  await fs.writeFile(path.join(outDir, '.gitignore'), content, 'utf8');
+}
+
+export async function run(argv = []) {
+  console.log(kleur.bold('\nCreate Agent Skill\n'));
+  console.log(
+    'Answer a few questions and this will scaffold a ready-to-edit skill/plugin\nfor Claude Code, OpenAI Custom GPT Actions, OpenClaw, or Google ADK.\n'
+  );
+
+  const cliId = argv[0] && !argv[0].startsWith('-') ? argv[0] : undefined;
+
+  const questions = [
+    {
+      type: 'text',
+      name: 'id',
+      message: 'Skill id (kebab-case, e.g. "check-stock"):',
+      initial: cliId,
+      validate: (value) => {
+        if (!KEBAB_CASE_RE.test(value)) {
+          return 'Use lowercase letters, numbers, and hyphens only (e.g. "check-stock").';
+        }
+        if (value.length > 64) {
+          return 'Maximum length is 64 characters.';
+        }
+        return true;
+      },
+    },
+    {
+      type: 'text',
+      name: 'nameForHuman',
+      message: 'Human-readable name:',
+      initial: (prev) => titleCase(prev),
+      validate: (value) => value.trim().length > 0 || 'Required.',
+    },
+    {
+      type: 'text',
+      name: 'description',
+      message: 'One-line description (what does it do?):',
+      validate: (value) => {
+        if (value.trim().length === 0) return 'Required.';
+        if (value.length > 200) return 'Maximum length is 200 characters.';
+        return true;
+      },
+    },
+    {
+      type: 'text',
+      name: 'instructions',
+      message: 'Instructions for the model (a sentence or two):',
+      validate: (value) => {
+        if (value.trim().length === 0) return 'Required.';
+        if (value.length > 2000) return 'Maximum length is 2000 characters.';
+        return true;
+      },
+    },
+    {
+      type: 'text',
+      name: 'author',
+      message: 'Author name (optional):',
+    },
+    {
+      type: 'multiselect',
+      name: 'interfaceTypes',
+      message: 'Select target interface types:',
+      choices: [
+        { title: 'CLI Plugin (run in command line)', value: 'cli', selected: true },
+        { title: 'Web App / Service API (run as a web service)', value: 'service', selected: true },
+        { title: 'SDK / Developer Framework (run in code)', value: 'sdk', selected: true },
+      ],
+      min: 1,
+      hint: '- Space to select, Enter to confirm',
+    },
+    {
+      type: 'multiselect',
+      name: 'platforms',
+      message: 'Which platform(s) should this target?',
+      choices: (prev, values) => {
+        const list = [];
+        if (values.interfaceTypes.includes('cli')) {
+          list.push({ title: 'Claude Code plugin', value: 'claude-code', selected: true });
+        }
+        if (values.interfaceTypes.includes('service')) {
+          list.push({ title: 'OpenAI Custom GPT Action', value: 'openai-action', selected: true });
+          list.push({ title: 'OpenClaw Gateway Skill', value: 'openclaw', selected: true });
+        }
+        if (values.interfaceTypes.includes('sdk')) {
+          list.push({ title: 'Google ADK / Gemini Agent', value: 'gemini-adk', selected: true });
+        }
+        return list;
+      },
+      min: 1,
+      hint: '- Space to select, Enter to confirm',
+    },
+    {
+      type: 'select',
+      name: 'logicType',
+      message: 'Select the backend logic template style:',
+      choices: [
+        { title: 'Simple Mock/Stub', value: 'stub' },
+        { title: 'External API Client (fetches from an HTTP endpoint)', value: 'fetch' },
+        { title: 'Local Filesystem (reads/writes files in a secure directory)', value: 'fs' },
+        { title: 'SQLite Database Utility (runs SQL queries on a local DB)', value: 'database' },
+      ],
+      initial: 0,
+    },
+    {
+      type: 'confirm',
+      name: 'hasSubagents',
+      message: 'Do you want to define subagents for delegation?',
+      initial: false,
+    },
+    {
+      type: 'text',
+      name: 'outDir',
+      message: 'Output directory:',
+      initial: (prev, values) => values.id,
+      validate: (value) => {
+        if (!value || value.trim().length === 0) return 'Required.';
+        const resolved = path.resolve(process.cwd(), value);
+        const relative = path.relative(process.cwd(), resolved);
+        if (relative.startsWith('..') || path.isAbsolute(value) || path.win32.isAbsolute(value) || path.posix.isAbsolute(value)) {
+          return 'Path traversal detected. Output directory must be within the current working directory.';
+        }
+        return true;
+      },
+    },
+  ];
+
+  try {
+    const spec = await prompts(questions, {
+      onCancel: () => {
+        throw new CancelledError();
+      },
+    });
+
+    spec.subagents = [];
+    if (spec.hasSubagents) {
+      console.log(kleur.bold('\n--- Subagents Configuration ---\n'));
+      let addMore = true;
+      const seenIds = new Set([spec.id]);
+      while (addMore) {
+        if (spec.subagents.length >= 20) {
+          console.log(kleur.yellow('\nMaximum cap of 20 subagents reached.'));
+          break;
+        }
+        const subagentQuestions = [
+          {
+            type: 'text',
+            name: 'id',
+            message: 'Subagent id (kebab-case, e.g. "coder-agent"):',
+            validate: (value) => {
+              if (!KEBAB_CASE_RE.test(value)) {
+                return 'Use lowercase letters, numbers, and hyphens only.';
+              }
+              if (value.length > 64) {
+                return 'Maximum length is 64 characters.';
+              }
+              if (seenIds.has(value)) {
+                if (value === spec.id) {
+                  return 'Subagent ID cannot be the same as the main skill ID.';
+                }
+                return 'Subagent ID must be unique (this ID is already in use).';
+              }
+              return true;
+            },
+          },
+          {
+            type: 'text',
+            name: 'nameForHuman',
+            message: 'Human-readable name:',
+            initial: (prev) => titleCase(prev),
+            validate: (value) => value.trim().length > 0 || 'Required.',
+          },
+          {
+            type: 'text',
+            name: 'description',
+            message: 'One-line description:',
+            validate: (value) => {
+              if (value.trim().length === 0) return 'Required.';
+              if (value.length > 200) return 'Maximum length is 200 characters.';
+              return true;
+            },
+          },
+          {
+            type: 'text',
+            name: 'instructions',
+            message: 'Instructions / system prompt for this subagent:',
+            validate: (value) => {
+              if (value.trim().length === 0) return 'Required.';
+              if (value.length > 2000) return 'Maximum length is 2000 characters.';
+              return true;
+            },
+          },
+          {
+            type: 'confirm',
+            name: 'addMore',
+            message: 'Add another subagent?',
+            initial: false,
+          },
+        ];
+        const subagentSpec = await prompts(subagentQuestions, {
+          onCancel: () => {
+            throw new CancelledError();
+          },
+        });
+        addMore = subagentSpec.addMore;
+        delete subagentSpec.addMore;
+        seenIds.add(subagentSpec.id);
+        spec.subagents.push(subagentSpec);
+      }
+    }
+
+    const outDir = path.resolve(process.cwd(), spec.outDir);
+
+    if (await isDirectoryNotEmpty(outDir)) {
+      const confirmOverwrite = await prompts({
+        type: 'confirm',
+        name: 'overwrite',
+        message: `The output directory "${spec.outDir}" is not empty. Overwrite existing files?`,
+        initial: false,
+      }, {
+        onCancel: () => {
+          throw new CancelledError();
+        }
+      });
+
+      if (!confirmOverwrite.overwrite) {
+        console.log(kleur.yellow('\nAborted to prevent overwriting existing files.'));
+        return;
+      }
+    }
+
+    await fs.mkdir(outDir, { recursive: true });
+
+    const summaryFiles = [];
+    const summarySteps = [];
+    const successfulPlatforms = [];
+    const failedPlatforms = [];
+
+    if (spec.platforms.includes('claude-code')) {
+      try {
+        const result = await generateClaudeCodePlugin(spec, outDir);
+        summaryFiles.push(...result.files);
+        summarySteps.push(...result.nextSteps);
+        successfulPlatforms.push('claude-code');
+      } catch (err) {
+        console.error(kleur.red(`Error generating Claude Code plugin: ${err.message}`));
+        failedPlatforms.push({ platform: 'claude-code', error: err.message });
+      }
+    }
+
+    if (spec.platforms.includes('openai-action')) {
+      try {
+        const result = await generateOpenAiAction(spec, outDir);
+        summaryFiles.push(...result.files);
+        summarySteps.push(...result.nextSteps);
+        successfulPlatforms.push('openai-action');
+      } catch (err) {
+        console.error(kleur.red(`Error generating OpenAI Custom GPT Action: ${err.message}`));
+        failedPlatforms.push({ platform: 'openai-action', error: err.message });
+      }
+    }
+
+    if (spec.platforms.includes('openclaw')) {
+      try {
+        const result = await generateOpenclawPlugin(spec, outDir);
+        summaryFiles.push(...result.files);
+        summarySteps.push(...result.nextSteps);
+        successfulPlatforms.push('openclaw');
+      } catch (err) {
+        console.error(kleur.red(`Error generating OpenClaw Gateway Skill: ${err.message}`));
+        failedPlatforms.push({ platform: 'openclaw', error: err.message });
+      }
+    }
+
+    if (spec.platforms.includes('gemini-adk')) {
+      try {
+        const result = await generateGeminiAdkAgent(spec, outDir);
+        summaryFiles.push(...result.files);
+        summarySteps.push(...result.nextSteps);
+        successfulPlatforms.push('gemini-adk');
+      } catch (err) {
+        console.error(kleur.red(`Error generating Google ADK / Gemini Agent: ${err.message}`));
+        failedPlatforms.push({ platform: 'gemini-adk', error: err.message });
+      }
+    }
+
+    if (failedPlatforms.length > 0 && successfulPlatforms.length === 0) {
+      throw new Error('All platform generators failed.');
+    }
+
+    await writeTopLevelReadme(spec, outDir);
+    summaryFiles.push('README.md');
+
+    await writeGitignore(outDir);
+    summaryFiles.push('.gitignore');
+
+    console.log(kleur.green(`\nDone! Created ${path.relative(process.cwd(), outDir).replace(/\\/g, '/') || '.'}/`));
+    console.log('\nFiles:');
+    for (const f of summaryFiles) {
+      console.log(`  ${kleur.cyan(f.replace(/\\/g, '/'))}`);
+    }
+
+    console.log('\nNext steps:');
+    for (const step of summarySteps) {
+      console.log(`  - ${step}`);
+    }
+    console.log('');
+
+    if (failedPlatforms.length > 0) {
+      console.log(kleur.yellow(`Warning: Some platforms failed to generate:`));
+      for (const fp of failedPlatforms) {
+        console.log(`  - ${kleur.bold(fp.platform)}: ${fp.error}`);
+      }
+      console.log('');
+    }
+  } catch (err) {
+    if (err instanceof CancelledError || err.name === 'CancelledError') {
+      console.log(kleur.yellow('\nCancelled.'));
+      return;
+    }
+    throw err;
+  }
+}
+
+function titleCase(id = '') {
+  return id
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+async function writeTopLevelReadme(spec, outDir) {
+  const lines = [
+    `# ${spec.nameForHuman}`,
+    '',
+    spec.description,
+    '',
+    '## Contents',
+    '',
+  ];
+
+  if (spec.platforms.includes('claude-code')) {
+    lines.push(
+      '- `.claude-plugin/plugin.json` + `skills/' + spec.id + '/SKILL.md` — Claude Code plugin.',
+      '  Test with `claude --plugin-dir .` from this directory, then try `/' + spec.id + '`.'
+    );
+  }
+
+  if (spec.platforms.includes('openai-action')) {
+    lines.push(
+      '- `openapi.yaml` + `server/` — Express stub and OpenAPI spec for an OpenAI Custom GPT Action.',
+      '  Run `cd server && npm install && npm start`, deploy it somewhere with HTTPS, then paste',
+      '  `openapi.yaml` into the GPT builder under Configure > Actions.'
+    );
+  }
+
+  if (spec.platforms.includes('openclaw')) {
+    lines.push(
+      '- `skills/` + `openclaw.json` — OpenClaw gateway configuration and skills.',
+      '  Copy the folders under `skills/` to your OpenClaw skills path and merge `openclaw.json` into your primary config.'
+    );
+  }
+
+  if (spec.platforms.includes('gemini-adk')) {
+    lines.push(
+      '- `agent.py` + `requirements.txt` — Google ADK / Gemini Agent definition.',
+      '  Run `pip install -r requirements.txt` and execute with `python agent.py "query"`.'
+    );
+  }
+
+  if (spec.subagents && spec.subagents.length > 0) {
+    lines.push(
+      '',
+      '### Subagents',
+      '',
+      'This scaffold includes ' + spec.subagents.length + ' subagent(s) for task delegation:'
+    );
+    for (const sa of spec.subagents) {
+      lines.push(`- **${sa.nameForHuman}** (${sa.id}): ${sa.description}`);
+    }
+  }
+
+  lines.push('', '## Generated by', '', '`create-agent-skill` — edit everything above freely, this is just a starting point.', '');
+
+  await fs.writeFile(path.join(outDir, 'README.md'), lines.join('\n'), 'utf8');
+}
+

package/src/generators/claudeCode.js

@@ -0,0 +1,89 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import yaml from 'js-yaml';
+
+/**
+ * Generates a Claude Code plugin:
+ *   <out>/.claude-plugin/plugin.json
+ *   <out>/skills/<id>/SKILL.md
+ *   <out>/README.md (only if not already created by another generator)
+ *
+ * @param {import('../schema.js').SkillSpec} spec
+ * @param {string} outDir
+ */
+export async function generateClaudeCodePlugin(spec, outDir) {
+  const pluginDir = path.join(outDir, '.claude-plugin');
+  const skillDir = path.join(outDir, 'skills', spec.id);
+
+  await fs.mkdir(pluginDir, { recursive: true });
+  await fs.mkdir(skillDir, { recursive: true });
+
+  const pluginJson = {
+    name: spec.id,
+    version: '0.1.0',
+    description: spec.description,
+    author: spec.author ? { name: spec.author } : undefined,
+  };
+
+  await fs.writeFile(
+    path.join(pluginDir, 'plugin.json'),
+    JSON.stringify(pluginJson, null, 2) + '\n',
+    'utf8'
+  );
+
+  const logicType = spec.logicType || 'stub';
+  let logicTypeInstructions = '';
+  if (logicType === 'fetch') {
+    logicTypeInstructions = '\n\nThis skill requires fetching data from an external HTTP API. Use curl or similar command line utilities to query resources on the network as needed.';
+  } else if (logicType === 'fs') {
+    logicTypeInstructions = '\n\nThis skill reads and writes local files to maintain and manage state. Use file access tools to check, modify, or create files within the workspace folder.';
+  } else if (logicType === 'database') {
+    logicTypeInstructions = '\n\nThis skill interacts with a local SQLite database at "database.db". Use the sqlite3 command-line utility to query or update data in this database.';
+  }
+
+  const mainFrontmatter = yaml.dump({ description: spec.description }).trim();
+  const skillMd = `---
+${mainFrontmatter}
+---
+
+${spec.instructions.trim()}${logicTypeInstructions}
+
+When the user provides additional details after the skill name, they are available as "$ARGUMENTS".
+`;
+
+  await fs.writeFile(path.join(skillDir, 'SKILL.md'), skillMd, 'utf8');
+
+  const files = [
+    path.relative(outDir, path.join(pluginDir, 'plugin.json')),
+    path.relative(outDir, path.join(skillDir, 'SKILL.md')),
+  ];
+
+  const subagents = spec.subagents || [];
+  if (subagents.length > 0) {
+    const agentsDir = path.join(outDir, 'agents');
+    await fs.mkdir(agentsDir, { recursive: true });
+
+    for (const sa of subagents) {
+      const saFrontmatter = yaml.dump({ description: sa.description }).trim();
+      const saMd = `---
+${saFrontmatter}
+---
+
+${sa.instructions.trim()}
+`;
+      const saPath = path.join(agentsDir, `${sa.id}.md`);
+      await fs.writeFile(saPath, saMd, 'utf8');
+      files.push(path.relative(outDir, saPath));
+    }
+  }
+
+  return {
+    files,
+    nextSteps: [
+      `Test locally with: claude --plugin-dir ${path.relative(process.cwd(), outDir).replace(/\\/g, '/') || '.'}`,
+      `Try the skill in Claude Code with: /${spec.id}`,
+      'To share it, add this directory to a plugin marketplace (.claude-plugin/marketplace.json) and have users run /plugin install.',
+    ],
+  };
+}
+

package/src/generators/geminiAdk.js

@@ -0,0 +1,153 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { toSnakeCase, escapePythonString, cleanComment } from '../schema.js';
+
+/**
+ * Generates Google ADK / Gemini Agent code:
+ *   <out>/agent.py
+ *   <out>/requirements.txt
+ *
+ * @param {import('../schema.js').SkillSpec} spec
+ * @param {string} outDir
+ */
+export async function generateGeminiAdkAgent(spec, outDir) {
+  const generatedFiles = [];
+
+  const mainAgentVar = toSnakeCase(spec.id);
+  const mainAgentName = toSnakeCase(spec.id) + '_agent';
+
+  // Construct subagents definitions
+  const subagents = spec.subagents || [];
+  const subagentDefs = [];
+  const subagentVars = [];
+
+  for (const sa of subagents) {
+    const saVar = toSnakeCase(sa.id);
+    const saName = toSnakeCase(sa.id) + '_agent';
+    subagentVars.push(saVar);
+    subagentDefs.push(`# Subagent: ${cleanComment(sa.nameForHuman)}
+${saVar} = LlmAgent(
+    model="gemini-2.0-flash-exp",
+    name="${saName}",
+    description="${escapePythonString(sa.description)}",
+    instruction="${escapePythonString(sa.instructions.trim())}",
+)
+`);
+  }
+
+  const logicType = spec.logicType;
+  let pythonToolsDefs = '';
+  let pythonToolsList = [...subagentVars];
+
+  if (logicType === 'fetch') {
+    pythonToolsDefs = `def fetch_external_api(query: str) -> str:
+    """Fetches data from an external API based on a query string."""
+    import urllib.request
+    import urllib.parse
+    import json
+    url = f"https://api.example.com/data?query={urllib.parse.quote(query)}"
+    try:
+        req = urllib.request.Request(url, headers={'User-Agent': 'Mozilla/5.0'})
+        with urllib.request.urlopen(req) as response:
+            return response.read().decode('utf-8')
+    except Exception as e:
+        return f"Error fetching from external API: {str(e)}"
+
+`;
+    pythonToolsList.push('fetch_external_api');
+  } else if (logicType === 'fs') {
+    pythonToolsDefs = `def interact_with_filesystem(filename: str, content: str = None) -> str:
+    """Reads or writes text content from/to a local file securely."""
+    import os
+    safe_path = os.path.basename(filename)
+    try:
+        if content is not None:
+            with open(safe_path, 'w', encoding='utf-8') as f:
+                f.write(content)
+            return f"Successfully wrote content to {safe_path}"
+        else:
+            if not os.path.exists(safe_path):
+                return f"File {safe_path} does not exist"
+            with open(safe_path, 'r', encoding='utf-8') as f:
+                return f.read()
+    except Exception as e:
+        return f"Filesystem error: {str(e)}"
+
+`;
+    pythonToolsList.push('interact_with_filesystem');
+  } else if (logicType === 'database') {
+    pythonToolsDefs = `def query_local_database(sql_query: str) -> str:
+    """Executes a SQL query on the local SQLite database and returns the rows as JSON."""
+    import sqlite3
+    import json
+    try:
+        conn = sqlite3.connect("database.db")
+        cursor = conn.cursor()
+        cursor.execute("CREATE TABLE IF NOT EXISTS queries (id INTEGER PRIMARY KEY, val TEXT)")
+        conn.commit()
+        cursor.execute(sql_query)
+        if sql_query.strip().upper().startswith("SELECT"):
+            rows = cursor.fetchall()
+            conn.close()
+            return json.dumps(rows)
+        else:
+            conn.commit()
+            conn.close()
+            return "Query executed successfully"
+    except Exception as e:
+        return f"Database error: {str(e)}"
+
+`;
+    pythonToolsList.push('query_local_database');
+  } else if (logicType === 'stub') {
+    pythonToolsDefs = `def stub_tool(input_val: str) -> str:
+    """A placeholder tool that echoes the input parameter."""
+    return f"Stub tool received: {input_val}"
+
+`;
+    pythonToolsList.push('stub_tool');
+  }
+
+  const subagentsSection = subagentDefs.length > 0 ? subagentDefs.join('\n') + '\n' : '';
+  const toolsList = pythonToolsList.length > 0 ? `tools=[${pythonToolsList.join(', ')}]` : 'tools=[]';
+
+  const agentPy = `from google.adk.agents import LlmAgent
+
+${pythonToolsDefs}
+${subagentsSection}# Main Agent: ${cleanComment(spec.nameForHuman)}
+${mainAgentVar} = LlmAgent(
+    model="gemini-2.0-flash-exp",
+    name="${mainAgentName}",
+    description="${escapePythonString(spec.description)}",
+    instruction="${escapePythonString(spec.instructions.trim())}",
+    ${toolsList},
+)
+
+if __name__ == "__main__":
+    import sys
+    query = sys.argv[1] if len(sys.argv) > 1 else "Hello"
+    print(f"Running agent: {${mainAgentVar}.name} with query: '{query}'")
+    # Example execution:
+    # response = ${mainAgentVar}.run(query)
+    # print(response)
+`;
+
+  const agentPyPath = path.join(outDir, 'agent.py');
+  await fs.writeFile(agentPyPath, agentPy, 'utf8');
+  generatedFiles.push(path.relative(outDir, agentPyPath));
+
+  const requirementsTxt = `google-adk>=0.1.0
+`;
+  const reqPath = path.join(outDir, 'requirements.txt');
+  await fs.writeFile(reqPath, requirementsTxt, 'utf8');
+  generatedFiles.push(path.relative(outDir, reqPath));
+
+  return {
+    files: generatedFiles,
+    nextSteps: [
+      'Install dependencies with: pip install -r requirements.txt',
+      `Run the agent locally using: python agent.py "your-prompt-here"`,
+    ],
+  };
+}
+

package/src/generators/openaiAction.js

@@ -0,0 +1,281 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import yaml from 'js-yaml';
+import { toCamelCase, escapeJsTemplateLiteral, escapeJsSingleQuoteString, cleanComment } from '../schema.js';
+
+/**
+ * Generates a secure OpenAPI spec + Express server stub suitable for
+ * pasting into a Custom GPT's Actions config, or wrapping in an MCP
+ * server later.
+ *
+ *   <out>/openapi.yaml
+ *   <out>/server/index.js
+ *   <out>/server/package.json
+ *
+ * @param {import('../schema.js').SkillSpec} spec
+ * @param {string} outDir
+ */
+export async function generateOpenAiAction(spec, outDir) {
+  const serverDir = path.join(outDir, 'server');
+  await fs.mkdir(serverDir, { recursive: true });
+
+  const handlerName = toCamelCase(spec.id);
+  const endpointPath = spec.endpointPath || `/${spec.id}`;
+
+  const openapiObj = {
+    openapi: '3.1.0',
+    info: {
+      title: spec.nameForHuman,
+      description: spec.description,
+      version: '0.1.0',
+    },
+    servers: [
+      {
+        url: 'https://YOUR-DEPLOYED-URL.example.com',
+      },
+    ],
+    paths: {
+      [endpointPath]: {
+        get: {
+          operationId: handlerName,
+          summary: spec.description,
+          parameters: [
+            {
+              name: 'input',
+              in: 'query',
+              required: true,
+              schema: {
+                type: 'string',
+              },
+              description: `Free-form input for "${spec.nameForHuman}"`,
+            },
+          ],
+          responses: {
+            200: {
+              description: 'Successful response',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      result: {
+                        type: 'string',
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  };
+
+  const subagents = spec.subagents || [];
+  for (const sa of subagents) {
+    const saHandler = toCamelCase(sa.id);
+    const saPath = `/agents/${sa.id}`;
+    openapiObj.paths[saPath] = {
+      get: {
+        operationId: saHandler,
+        summary: sa.description,
+        parameters: [
+          {
+            name: 'input',
+            in: 'query',
+            required: true,
+            schema: {
+              type: 'string',
+            },
+            description: `Free-form input for subagent "${sa.nameForHuman}"`,
+          },
+        ],
+        responses: {
+          200: {
+            description: 'Successful response',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    result: {
+                      type: 'string',
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+  }
+
+  const openapiYaml = yaml.dump(openapiObj);
+  await fs.writeFile(path.join(outDir, 'openapi.yaml'), openapiYaml, 'utf8');
+
+  const logicType = spec.logicType || 'stub';
+
+  let subagentRoutes = '';
+  for (const sa of subagents) {
+    const saNameEscaped = escapeJsTemplateLiteral(sa.nameForHuman);
+    const saDescComment = cleanComment(sa.description);
+    const saInstComment = cleanComment(sa.instructions.trim().split('\n')[0]);
+    subagentRoutes += `
+// Subagent: ${saNameEscaped} - ${saDescComment}
+// Instructions: ${saInstComment}
+app.get('/agents/${sa.id}', async (req, res) => {
+  const { input } = req.query;
+  if (!input || typeof input !== 'string' || input.trim().length === 0) {
+    return res.status(400).json({ error: 'Missing or invalid required query parameter: input' });
+  }
+
+  // TODO: replace with real logic for "${saNameEscaped}"
+  res.json({ result: \`[${saNameEscaped}] Received input: \${input}\` });
+});
+`;
+  }
+
+  const mainNameEscaped = escapeJsTemplateLiteral(spec.nameForHuman);
+  const mainDescComment = cleanComment(spec.description);
+  const mainInstComment = cleanComment(spec.instructions.trim().split('\n')[0]);
+
+  let importsList = `import express from 'express';
+import cors from 'cors';
+import helmet from 'helmet';`;
+
+  let mainHandlerBody = '';
+
+  if (logicType === 'fetch') {
+    mainHandlerBody = `  // Fetch data from an external API
+  const url = \`https://api.example.com/data?query=\${encodeURIComponent(input)}\`;
+  try {
+    const response = await fetch(url);
+    if (!response.ok) {
+      return res.status(response.status).json({ error: \`External API responded with status \${response.status}\` });
+    }
+    const data = await response.json();
+    res.json({ result: data });
+  } catch (err) {
+    res.status(500).json({ error: \`Failed to fetch external API: \${err.message}\` });
+  }`;
+  } else if (logicType === 'fs') {
+    importsList += `\nimport fs from 'node:fs/promises';\nimport path from 'node:path';`;
+    mainHandlerBody = `  // Read and write data securely to local files
+  const dataFilePath = path.join(process.cwd(), 'data.json');
+  try {
+    let currentData = {};
+    try {
+      const content = await fs.readFile(dataFilePath, 'utf8');
+      currentData = JSON.parse(content);
+    } catch (readErr) {
+      // Ignore if file doesn't exist yet
+    }
+    currentData[new Date().toISOString()] = input;
+    await fs.writeFile(dataFilePath, JSON.stringify(currentData, null, 2), 'utf8');
+    res.json({ result: \`Successfully wrote input to local file data.json. Total entries: \${Object.keys(currentData).length}\` });
+  } catch (err) {
+    res.status(500).json({ error: \`Failed to perform filesystem operation: \${err.message}\` });
+  }`;
+  } else if (logicType === 'database') {
+    importsList += `\nimport sqlite3 from 'sqlite3';\nimport path from 'node:path';`;
+    mainHandlerBody = `  // Connect to local SQLite database and query
+  const dbPath = path.join(process.cwd(), 'database.db');
+  const db = new sqlite3.Database(dbPath);
+  db.serialize(() => {
+    db.run("CREATE TABLE IF NOT EXISTS queries (id INTEGER PRIMARY KEY, val TEXT)");
+    db.run("INSERT INTO queries (val) VALUES (?)", [input], function(err) {
+      if (err) {
+        db.close();
+        return res.status(500).json({ error: \`Database insert error: \${err.message}\` });
+      }
+      db.all("SELECT * FROM queries ORDER BY id DESC LIMIT 5", [], (selectErr, rows) => {
+        db.close();
+        if (selectErr) {
+          return res.status(500).json({ error: \`Database select error: \${selectErr.message}\` });
+        }
+        res.json({ result: \`Inserted entry. Last 5 entries: \${JSON.stringify(rows)}\` });
+      });
+    });
+  });`;
+  } else {
+    mainHandlerBody = `  // TODO: replace with real logic for "${mainNameEscaped}"
+  res.json({ result: \`Received input: \${input}\` });`;
+  }
+
+  const serverIndexJs = `${importsList}
+
+const app = express();
+const port = process.env.PORT || 3000;
+
+app.use(helmet());
+app.use(cors()); // Configure allowed origins, methods, and headers for production
+app.use(express.json());
+
+// Main Skill: ${mainDescComment}
+// Instructions: ${mainInstComment}
+app.get('${escapeJsSingleQuoteString(endpointPath)}', async (req, res) => {
+  const { input } = req.query;
+  if (!input || typeof input !== 'string' || input.trim().length === 0) {
+    return res.status(400).json({ error: 'Missing or invalid required query parameter: input' });
+  }
+
+${mainHandlerBody}
+});
+${subagentRoutes}
+// Global Error Handler
+app.use((err, req, res, next) => {
+  console.error(err.stack);
+  res.status(500).json({ error: 'Internal Server Error' });
+});
+
+app.listen(port, () => {
+  console.log(\`${mainNameEscaped} action server listening on port \${port}\`);
+});
+`;
+
+  await fs.writeFile(path.join(serverDir, 'index.js'), serverIndexJs, 'utf8');
+
+  const serverDependencies = {
+    express: '4.21.0',
+    cors: '2.8.5',
+    helmet: '7.1.0',
+  };
+  if (logicType === 'database') {
+    serverDependencies.sqlite3 = '5.1.7';
+  }
+
+  const serverPackageJson = {
+    name: `${spec.id}-action-server`,
+    version: '0.1.0',
+    private: true,
+    type: 'module',
+    main: 'index.js',
+    scripts: {
+      start: 'node index.js',
+    },
+    dependencies: serverDependencies,
+  };
+
+  await fs.writeFile(
+    path.join(serverDir, 'package.json'),
+    JSON.stringify(serverPackageJson, null, 2) + '\n',
+    'utf8'
+  );
+
+  return {
+    files: [
+      path.relative(outDir, path.join(outDir, 'openapi.yaml')),
+      path.relative(outDir, path.join(serverDir, 'index.js')),
+      path.relative(outDir, path.join(serverDir, 'package.json')),
+    ],
+    nextSteps: [
+      'Deploy server/ somewhere reachable over HTTPS (e.g. a free-tier host), then update the `servers.url` in openapi.yaml.',
+      'In ChatGPT, create a Custom GPT, open Configure > Actions, and paste in the contents of openapi.yaml.',
+      'Set an auth method in the Actions config if your endpoint needs one (none / API key / OAuth).',
+      'Run "npm install" inside the server directory and run "npm audit" to check for vulnerabilities.',
+    ],
+  };
+}
+

package/src/generators/openclaw.js

@@ -0,0 +1,100 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import yaml from 'js-yaml';
+
+/**
+ * Generates OpenClaw config and skills:
+ *   <out>/skills/<id>/SKILL.md
+ *   <out>/skills/<subagent-id>/SKILL.md (for each subagent)
+ *   <out>/openclaw.json
+ *
+ * @param {import('../schema.js').SkillSpec} spec
+ * @param {string} outDir
+ */
+export async function generateOpenclawPlugin(spec, outDir) {
+  const generatedFiles = [];
+  const skillsDir = path.join(outDir, 'skills');
+  await fs.mkdir(skillsDir, { recursive: true });
+
+  const logicType = spec.logicType || 'stub';
+  let logicTypeInstructions = '';
+  if (logicType === 'fetch') {
+    logicTypeInstructions = '\n\nThis skill requires fetching data from an external HTTP API. Use curl or similar command line utilities to query resources on the network as needed.';
+  } else if (logicType === 'fs') {
+    logicTypeInstructions = '\n\nThis skill reads and writes local files to maintain and manage state. Use file access tools to check, modify, or create files within the workspace folder.';
+  } else if (logicType === 'database') {
+    logicTypeInstructions = '\n\nThis skill interacts with a local SQLite database at "database.db". Use the sqlite3 command-line utility to query or update data in this database.';
+  }
+
+  // 1. Generate main skill file
+  const mainSkillDir = path.join(skillsDir, spec.id);
+  await fs.mkdir(mainSkillDir, { recursive: true });
+  const mainFrontmatter = yaml.dump({ description: spec.description }).trim();
+  const mainSkillMd = `---
+${mainFrontmatter}
+---
+
+${spec.instructions.trim()}${logicTypeInstructions}
+`;
+  const mainSkillPath = path.join(mainSkillDir, 'SKILL.md');
+  await fs.writeFile(mainSkillPath, mainSkillMd, 'utf8');
+  generatedFiles.push(path.relative(outDir, mainSkillPath));
+
+  // 2. Generate subagent skill files
+  const subagents = spec.subagents || [];
+  for (const sa of subagents) {
+    const saSkillDir = path.join(skillsDir, sa.id);
+    await fs.mkdir(saSkillDir, { recursive: true });
+    const saFrontmatter = yaml.dump({ description: sa.description }).trim();
+    const saSkillMd = `---
+${saFrontmatter}
+---
+
+${sa.instructions.trim()}
+`;
+    const saSkillPath = path.join(saSkillDir, 'SKILL.md');
+    await fs.writeFile(saSkillPath, saSkillMd, 'utf8');
+    generatedFiles.push(path.relative(outDir, saSkillPath));
+  }
+
+  // 3. Generate openclaw.json config snippet
+  const openclawJson = {
+    agents: {
+      [spec.id]: {
+        model: {
+          primary: 'anthropic/claude-3-5-sonnet',
+          fallback: 'openai/gpt-4o',
+        },
+        workspace: './workspace',
+        tools: ['file', 'shell', 'browser'],
+        skills: [spec.id, ...subagents.map((sa) => sa.id)],
+      },
+    },
+  };
+
+  // Add individual subagent profiles to the config
+  for (const sa of subagents) {
+    openclawJson.agents[sa.id] = {
+      model: {
+        primary: 'anthropic/claude-3-5-sonnet',
+      },
+      workspace: './workspace',
+      tools: ['file'],
+      skills: [sa.id],
+    };
+  }
+
+  const configPath = path.join(outDir, 'openclaw.json');
+  await fs.writeFile(configPath, JSON.stringify(openclawJson, null, 2) + '\n', 'utf8');
+  generatedFiles.push(path.relative(outDir, configPath));
+
+  return {
+    files: generatedFiles,
+    nextSteps: [
+      'Copy the generated `skills/` folders to your OpenClaw skills directory (typically `~/.openclaw/skills/`).',
+      'Merge the generated `openclaw.json` configuration into your global `~/.openclaw/openclaw.json` file.',
+      `Run OpenClaw and target the agent using the ID "${spec.id}".`,
+    ],
+  };
+}
+

package/src/schema.js

@@ -0,0 +1,94 @@
+/**
+ * The internal "spec" object collected from the user via prompts.
+ * This mirrors the modular schema described in the design doc:
+ * a small, platform-agnostic description of a single skill/tool
+ * that generators can translate into platform-specific artifacts.
+ *
+ * @typedef {Object} SubagentSpec
+ * @property {string} id            kebab-case identifier, e.g. "coder-agent"
+ * @property {string} nameForHuman  Human-readable name, e.g. "Coder Agent"
+ * @property {string} description   One-line description of what it does
+ * @property {string} instructions  Instructions / system prompt for this subagent
+ *
+ * @typedef {Object} SkillSpec
+ * @property {string} id            kebab-case identifier, e.g. "check-stock"
+ * @property {string} nameForHuman  Human-readable name, e.g. "Check Stock"
+ * @property {string} description   One-line description of what it does
+ * @property {string} author        Author name (optional)
+ * @property {string} instructions  What the skill/tool should do, in prose
+ * @property {string[]} platforms   Subset of ["claude-code", "openai-action", "openclaw", "gemini-adk"]
+ * @property {string} endpointPath  HTTP path used for the OpenAI Action stub, e.g. "/check-stock"
+ * @property {SubagentSpec[]} subagents Array of subagents (optional)
+ */
+
+export function toPascalCase(id) {
+  if (!id || typeof id !== 'string' || id.trim().length === 0) {
+    throw new Error('Input must be a non-empty string');
+  }
+  // Strip non-ASCII characters first
+  const clean = id.replace(/[^\x00-\x7F]/g, '');
+  // Strip characters that are not alphanumeric, spaces, hyphens, or underscores
+  const cleanAlphaNum = clean.replace(/[^a-zA-Z0-9\s-_]/g, '').trim();
+  if (cleanAlphaNum.length === 0) {
+    throw new Error('Input contains no valid characters for casing');
+  }
+  return cleanAlphaNum
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+}
+
+export function toCamelCase(id) {
+  const pascal = toPascalCase(id);
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+
+export function toSnakeCase(id) {
+  if (!id || typeof id !== 'string' || id.trim().length === 0) {
+    throw new Error('Input must be a non-empty string');
+  }
+  const clean = id.replace(/[^\x00-\x7F]/g, '');
+  const cleanAlphaNum = clean.replace(/[^a-zA-Z0-9\s-_]/g, '').trim();
+  if (cleanAlphaNum.length === 0) {
+    throw new Error('Input contains no valid characters for casing');
+  }
+  return cleanAlphaNum
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part.toLowerCase())
+    .join('_');
+}
+
+export function escapePythonString(val) {
+  if (typeof val !== 'string') return '';
+  return val
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/'/g, "\\'")
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/\t/g, '\\t');
+}
+
+export function escapeJsTemplateLiteral(val) {
+  if (typeof val !== 'string') return '';
+  return val
+    .replace(/\\/g, '\\\\')
+    .replace(/`/g, '\\`')
+    .replace(/\${/g, '\\${');
+}
+
+export function escapeJsSingleQuoteString(val) {
+  if (typeof val !== 'string') return '';
+  return val
+    .replace(/\\/g, '\\\\')
+    .replace(/'/g, "\\'");
+}
+
+export function cleanComment(val) {
+  if (typeof val !== 'string') return '';
+  return val.replace(/[\r\n]/g, ' ').replace(/\*\//g, '* /');
+}
+
+