build-skill 0.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flash Brew Digital / Ben Sabic
+
+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,182 @@
+# Build Skill
+
+![Flash Brew Digital OSS](https://img.shields.io/badge/Flash_Brew_Digital-OSS-6F4E37?style=for-the-badge&labelColor=E9E3DD)
+![MIT License](https://img.shields.io/badge/License-MIT-6F4E37?style=for-the-badge&labelColor=E9E3DD)
+
+Scaffold AI agent skills quickly with the Build Skill CLI. Creates a fully-configured skills repository following the [Agent Skills Specification](https://agentskills.io/specification).
+
+## What are Agent Skills?
+
+Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently. They work across any AI agent that supports the [open Agent Skills standard](https://agentskills.io).
+
+## Quick Start
+
+```bash
+npx build-skill
+```
+
+This launches an interactive prompt to configure your skill.
+
+## Usage
+
+### Interactive Mode
+
+```bash
+npx build-skill
+```
+
+You'll be prompted for:
+- **Brand/Organization name** - Your company or project name (e.g., `acme-corp`)
+- **Skill name** - Name of your first skill (e.g., `data-processor`)
+- **Skill description** - What the skill does and when to use it
+
+### Quiet Mode (CI/Scripts)
+
+```bash
+npx build-skill --name my-skill --description "Helps with X tasks" --quiet
+```
+
+### CLI Options
+
+| Option | Alias | Description | Default |
+| ------ | ----- | ----------- | ------- |
+| `--brand <brand>` | `-b` | Brand/organization name | Same as `--name` |
+| `--name <name>` | `-n` | Skill name | *Required in quiet mode* |
+| `--description <desc>` | `-d` | Skill description | *Required in quiet mode* |
+| `--license <license>` | `-l` | License for the skill | `MIT` |
+| `--website <url>` | `-w` | Website/docs URL | `https://example.com` |
+| `--repository <repo>` | `-r` | GitHub repository (owner/repo) | `<brand>/agent-skills` |
+| `--category <category>` | `-c` | Skill category | `general` |
+| `--keywords <keywords>` | `-k` | Comma-separated keywords | `ai, agent, skill` |
+| `--output <dir>` | `-o` | Output directory | `.` |
+| `--quiet` | `-q` | Suppress prompts and visual output | `false` |
+| `--force` | `-f` | Overwrite existing directory | `false` |
+| `--version` | `-V` | Show version number | |
+| `--help` | `-h` | Show help | |
+
+### Examples
+
+```bash
+# Interactive mode
+npx build-skill
+
+# Specify brand and skill name
+npx build-skill --brand acme-corp --name data-processor --description "Processes data files"
+
+# Full configuration
+npx build-skill \
+  --brand acme-corp \
+  --name data-processor \
+  --description "Processes CSV and JSON data files" \
+  --license Apache-2.0 \
+  --website https://acme.example.com/docs \
+  --repository acme-corp/agent-skills \
+  --category productivity \
+  --keywords "data, csv, json, processing" \
+  --quiet
+
+# Overwrite existing directory
+npx build-skill --name my-skill --description "My skill" --force --quiet
+```
+
+## Generated Structure
+
+```
+<brand>-skills/
+├── .claude-plugin/
+│   └── marketplace.json
+├── .github/
+│   └── workflows/
+│       └── process-skills.yml
+├── scripts/
+│   └── sync-skills.js
+├── skills/
+│   └── <skill-name>/
+│       ├── .claude-plugin/
+│       │   └── plugin.json
+│       └── SKILL.md
+└── README.md
+```
+
+## Included Automation
+
+### GitHub Actions Workflow
+
+The generated repository includes a `process-skills.yml` workflow that:
+
+- **On Pull Requests**: Validates all skills using the [Validate Agent Skill](https://github.com/marketplace/actions/validate-skill) action
+- **On Push to Main**: Validates skills and syncs the README and marketplace.json
+
+### Add Skill Script
+
+The `scripts/add-skill.js` utility creates new skills:
+
+```bash
+node scripts/add-skill.js <skill-name> "<description>"
+```
+
+Example:
+```bash
+node scripts/add-skill.js data-processor "Processes CSV and JSON data files"
+```
+
+This script:
+- Creates the skill directory structure in `skills/`
+- Generates `SKILL.md` with frontmatter
+- Generates `.claude-plugin/plugin.json`
+- Automatically runs sync-skills.js to update README and marketplace.json
+
+### Sync Script
+
+The `scripts/sync-skills.js` utility keeps your repository in sync:
+
+```bash
+node scripts/sync-skills.js
+```
+
+This script:
+- Scans the `skills/` directory for all skills
+- Updates the "Available Skills" table in `README.md`
+- Updates the `plugins` array in `.claude-plugin/marketplace.json`
+
+Run it after modifying skills to keep everything up to date.
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Run tests
+pnpm test
+
+# Lint
+pnpm check
+
+# Fix lint issues
+pnpm fix
+
+# Type check
+pnpm type-check
+```
+
+## Resources
+
+- [Agent Skills Specification](https://agentskills.io/specification)
+- [Vercel Skills CLI](https://skills.sh/)
+- [Validate Agent Skill](https://github.com/marketplace/actions/validate-skill)
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](.github/CONTRIBUTING.md) for more information.
+
+## License
+
+[MIT License](LICENSE.md)
+
+## Author
+
+[Ben Sabic](https://bensabic.ca) at [Flash Brew Digital](https://flashbrew.digital)

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { dirname, join as join2, resolve } from "path";
+import { fileURLToPath } from "url";
+import { log as log2 } from "@clack/prompts";
+import { program } from "commander";
+import pc3 from "picocolors";
+
+// src/prompts.ts
+import { cancel, group, log, outro, text } from "@clack/prompts";
+import pc from "picocolors";
+
+// src/utils.ts
+import { execa } from "execa";
+function normalizeName(input) {
+  return input.toLowerCase().trim().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+async function getGitConfig(key) {
+  try {
+    const { stdout } = await execa("git", ["config", "--get", key]);
+    return stdout.trim();
+  } catch {
+    return "";
+  }
+}
+
+// src/prompts.ts
+var MAX_DESCRIPTION_LENGTH = 1024;
+function validateName(value) {
+  if (!value?.trim()) {
+    return "Name is required";
+  }
+  if (!normalizeName(value)) {
+    return "Name must contain at least one letter or number";
+  }
+}
+function validateDescription(value) {
+  if (!value) {
+    return "Description is required";
+  }
+  if (value.length > MAX_DESCRIPTION_LENGTH) {
+    return `Description must be under ${MAX_DESCRIPTION_LENGTH} characters`;
+  }
+}
+async function promptForInput(providedBrand, providedName, providedDescription) {
+  const answers = await group(
+    {
+      brandName: () => {
+        if (providedBrand) {
+          return Promise.resolve(providedBrand);
+        }
+        return text({
+          message: "What is your brand/organization name?",
+          placeholder: "acme-corp",
+          validate: validateName
+        });
+      },
+      skillName: () => {
+        if (providedName) {
+          return Promise.resolve(providedName);
+        }
+        return text({
+          message: "What is the name of your first skill?",
+          placeholder: "my-skill",
+          validate: validateName
+        });
+      },
+      skillDescription: () => {
+        if (providedDescription) {
+          return Promise.resolve(providedDescription);
+        }
+        return text({
+          message: "Describe what this skill does and when to use it:",
+          placeholder: "Helps with X tasks. Use when working with Y or when the user mentions Z.",
+          validate: validateDescription
+        });
+      }
+    },
+    {
+      onCancel: () => {
+        cancel("Operation cancelled.");
+        process.exit(0);
+      }
+    }
+  );
+  return {
+    brandName: normalizeName(answers.brandName),
+    skillName: normalizeName(answers.skillName),
+    skillDescription: answers.skillDescription
+  };
+}
+function getQuietInput(providedBrand, providedName, providedDescription) {
+  if (!providedName) {
+    throw new Error("--name is required in quiet mode");
+  }
+  if (!providedDescription) {
+    throw new Error("--description is required in quiet mode");
+  }
+  const brand = providedBrand || providedName;
+  const nameError = validateName(providedName);
+  if (nameError) {
+    throw new Error(nameError);
+  }
+  const brandError = validateName(brand);
+  if (brandError) {
+    throw new Error(`Brand ${brandError.toLowerCase()}`);
+  }
+  const descError = validateDescription(providedDescription);
+  if (descError) {
+    throw new Error(descError);
+  }
+  return {
+    brandName: normalizeName(brand),
+    skillName: normalizeName(providedName),
+    skillDescription: providedDescription
+  };
+}
+function printSuccess(targetDir, brandName, skillName, quiet) {
+  if (quiet) {
+    console.log(targetDir);
+    return;
+  }
+  log.success(`Created ${pc.cyan(targetDir)}`);
+  log.info(`
+Next steps:
+  ${pc.cyan(`cd ${brandName}-skills`)}
+  ${pc.cyan("git init")}
+  ${pc.cyan("git remote add origin <YOUR_REPO_URL>")}
+  ${pc.cyan("git branch -M main")}
+  ${pc.cyan("git add .")}
+  ${pc.cyan(`git commit -m "Initial release of ${skillName} skill"`)}
+  ${pc.cyan("git push -u origin main")}
+
+Edit your skill at:
+  ${pc.cyan(`skills/${skillName}/SKILL.md`)}
+`);
+  outro(pc.green("Happy building! \u{1F680}"));
+}
+
+// src/scaffold.ts
+import {
+  access,
+  cp,
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  writeFile
+} from "fs/promises";
+import { join } from "path";
+import { spinner } from "@clack/prompts";
+import pc2 from "picocolors";
+var SKILL_NAME_PLACEHOLDER = "{Skill_Name}";
+async function pathExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function copyDir(src, dest) {
+  await mkdir(dest, { recursive: true });
+  const entries = await readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath);
+    } else {
+      await cp(srcPath, destPath);
+    }
+  }
+}
+async function replaceInFile(filePath, values) {
+  let content = await readFile(filePath, "utf-8");
+  for (const [key, value] of Object.entries(values)) {
+    const placeholder = `{${key}}`;
+    content = content.replaceAll(placeholder, value);
+  }
+  await writeFile(filePath, content, "utf-8");
+}
+async function processDirectory(dir, values) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === SKILL_NAME_PLACEHOLDER) {
+        const newPath = join(dir, values.Skill_Name);
+        await rename(fullPath, newPath);
+        await processDirectory(newPath, values);
+      } else {
+        await processDirectory(fullPath, values);
+      }
+    } else {
+      await replaceInFile(fullPath, values);
+    }
+  }
+}
+function formatError(error) {
+  if (error instanceof Error) {
+    if (error.message.includes("ENOENT")) {
+      return "Template directory not found. Please reinstall build-skill.";
+    }
+    if (error.message.includes("EACCES")) {
+      return "Permission denied. Check write permissions for the output directory.";
+    }
+    if (error.message.includes("ENOSPC")) {
+      return "No space left on device.";
+    }
+    return error.message;
+  }
+  return "An unknown error occurred";
+}
+async function createSkillRepository(templateDir, targetDir, values, quiet, force) {
+  const s = quiet ? null : spinner();
+  if (!await pathExists(templateDir)) {
+    throw new Error(
+      "Template directory not found. Please reinstall build-skill."
+    );
+  }
+  if (await pathExists(targetDir)) {
+    if (force) {
+      await rm(targetDir, { recursive: true, force: true });
+    } else {
+      throw new Error(`Directory already exists: ${targetDir}`);
+    }
+  }
+  s?.start(
+    `Creating the ${pc2.cyan(values.Brand_Name)} agent skills repository...`
+  );
+  try {
+    await copyDir(templateDir, targetDir);
+    await processDirectory(targetDir, values);
+    s?.stop("Agent Skills repository created!");
+  } catch (error) {
+    s?.stop("Failed to create skill repository");
+    try {
+      await rm(targetDir, { recursive: true, force: true });
+    } catch {
+    }
+    throw new Error(formatError(error));
+  }
+}
+
+// src/index.ts
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var TEMPLATE_DIR = join2(__dirname, "..", "template");
+var version = true ? "0.0.0" : "dev";
+var BANNER = `
+ _           _ _     _       _    _ _ _
+| |__  _   _(_) | __| |  ___| | _(_) | |
+| '_ \\| | | | | |/ _\` | / __| |/ / | | |
+| |_) | |_| | | | (_| | \\__ \\   <| | | |
+|_.__/ \\__,_|_|_|\\__,_| |___/_|\\_\\_|_|_|
+`;
+async function main() {
+  program.name("build-skill").description("Scaffold AI agent skills quickly").version(version).argument("[name]", "Skill name").argument("[description]", "Skill description").option("-b, --brand <brand>", "Brand/organization name").option("-n, --name <name>", "Skill name").option("-d, --description <description>", "Skill description").option("-l, --license <license>", "License for the skill").option("-w, --website <url>", "Website URL (e.g. docs) for the skill").option("-r, --repository <repo>", "GitHub repository (owner/repo)").option("-c, --category <category>", "Skill category").option("-k, --keywords <keywords>", "Comma-separated keywords").option("-o, --output <dir>", "Output directory", ".").option("-q, --quiet", "Suppress interactive prompts and visual output").option("-f, --force", "Overwrite existing directory").parse();
+  const options = program.opts();
+  const [argName, argDescription] = program.args;
+  const providedBrand = options.brand;
+  const providedName = options.name || argName;
+  const providedDescription = options.description || argDescription;
+  if (!options.quiet) {
+    console.log(pc3.green(BANNER));
+  }
+  const gitName = await getGitConfig("user.name");
+  const gitEmail = await getGitConfig("user.email");
+  const hasGitConfig = gitName && gitEmail;
+  if (!(hasGitConfig || options.quiet)) {
+    log2.warn(
+      "Could not detect git user.name or user.email. Using placeholders."
+    );
+  }
+  const input = options.quiet ? getQuietInput(providedBrand, providedName, providedDescription) : await promptForInput(providedBrand, providedName, providedDescription);
+  const { brandName, skillName, skillDescription } = input;
+  const outputDir = resolve(process.cwd(), options.output || ".");
+  const targetDir = join2(outputDir, `${brandName}-skills`);
+  const values = {
+    Brand_Name: brandName,
+    Skill_Name: skillName,
+    Skill_Description: skillDescription,
+    Creator_Name: gitName || "Your Name",
+    Creator_Email: gitEmail || "your.email@example.com",
+    Skill_License: options.license || "MIT",
+    Skill_Homepage: options.website || "https://example.com",
+    Skill_Repository: options.repository || `${brandName}/agent-skills`,
+    Skill_Category: options.category || "general",
+    Skill_Keywords: options.keywords || "ai, agent, skill"
+  };
+  await createSkillRepository(
+    TEMPLATE_DIR,
+    targetDir,
+    values,
+    Boolean(options.quiet),
+    Boolean(options.force)
+  );
+  printSuccess(targetDir, brandName, skillName, Boolean(options.quiet));
+}
+main().catch((error) => {
+  console.error(
+    pc3.red(
+      error instanceof Error ? error.message : "An unexpected error occurred"
+    )
+  );
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "build-skill",
+  "version": "0.0.0",
+  "description": "Scaffold AI agent skills quickly with the Build Skill CLI.",
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "agent",
+    "skills",
+    "tools"
+  ],
+  "homepage": "https://github.com/Flash-Brew-Digital/build-skill",
+  "bugs": {
+    "url": "https://github.com/Flash-Brew-Digital/build-skill/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Ben Sabic",
+    "url": "https://bensabic.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Flash-Brew-Digital/build-skill.git"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "build-skill": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "template",
+    "README.md"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm build",
+    "check": "ultracite check",
+    "fix": "ultracite fix",
+    "bump-deps": "npx npm-check-updates -u -p pnpm && pnpm install",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.0.0",
+    "commander": "^14.0.3",
+    "execa": "^9.6.1",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.13",
+    "@types/node": "^25.2.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "ultracite": "7.1.3",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@10.28.2"
+}

package/template/.claude-plugin/marketplace.json

@@ -0,0 +1,29 @@
+{
+  "name": "{Brand_Name}-skills",
+  "description": "{Brand_Name} agent skills",
+  "owner": {
+    "name": "{Creator_Name}",
+    "email": "{Creator_Email}"
+  },
+  "metadata": {
+    "version": "1.0.0",
+    "description": "Claude Code marketplace of skills by {Brand_Name}"
+  },
+  "plugins": [
+    {
+      "name": "{Skill_Name}-skill",
+      "description": "{Skill_Description}",
+      "version": "1.0.0",
+      "author": {
+        "name": "{Creator_Name}",
+        "email": "{Creator_Email}"
+      },
+      "source": "./skills/{Skill_Name}",
+      "homepage": "{Skill_Homepage}",
+      "repository": "https://github.com/{Skill_Repository}",
+      "license": "{Skill_License}",
+      "category": "{Skill_Category}",
+      "keywords": "{Skill_Keywords}"
+    }
+  ]
+}

package/template/.github/workflows/process-skills.yml

@@ -0,0 +1,86 @@
+name: Process Skills
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "**/SKILL.md"
+  pull_request:
+    branches: [main]
+    paths:
+      - "**/SKILL.md"
+
+concurrency:
+  group: validate-skill-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  detect-changes:
+    runs-on: ubuntu-slim
+    if: github.event.pull_request.draft != true && github.actor != 'dependabot[bot]'
+    outputs:
+      skills: ${{ steps.changed-skills.outputs.skills }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Get changed skills
+        id: changed-skills
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            BASE=${{ github.event.pull_request.base.sha }}
+            HEAD=${{ github.event.pull_request.head.sha }}
+          else
+            BASE=${{ github.event.before }}
+            HEAD=${{ github.event.after }}
+          fi
+
+          # Find changed SKILL.md files and extract skill directories
+          SKILLS=$(git diff --name-only $BASE $HEAD | \
+            grep 'SKILL.md$' | \
+            xargs -I {} dirname {} | \
+            sort -u | \
+            jq -R -s -c 'split("\n") | map(select(length > 0))')
+
+          echo "skills=$SKILLS" >> $GITHUB_OUTPUT
+          echo "Changed skills: $SKILLS"
+
+  validate:
+    needs: detect-changes
+    if: needs.detect-changes.outputs.skills != '[]'
+    runs-on: ubuntu-slim
+    strategy:
+      fail-fast: false
+      matrix:
+        skill: ${{ fromJson(needs.detect-changes.outputs.skills) }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Validate ${{ matrix.skill }}
+        uses: Flash-Brew-Digital/validate-skill@v1
+        with:
+          path: ${{ matrix.skill }}
+
+  sync:
+    needs: validate
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-slim
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Sync skills
+        run: node scripts/sync-skills.js
+
+      - name: Commit changes
+        run: |
+          git config user.name "Agent Skills Bot"
+          git config user.email "agent-skills-bot@users.noreply.github.com"
+          git add README.md .claude-plugin/marketplace.json
+          git diff --staged --quiet || git commit -m "chore: sync skills documentation"
+          git push

package/template/README.md

@@ -0,0 +1,79 @@
+# {Brand_Name} Agent Skills
+
+This repository contains a collection of agent skills for {Brand_Name}. These skills are designed to enhance the capabilities of agents by providing them with specialized functionalities.
+
+## What are Agent Skills?
+
+Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently. They work across any AI agent that supports the [open Agent Skills standard](https://agentskills.io).
+
+## Available Skills
+<!-- START:Available-Skills -->
+
+| Skill | Description |
+| ----- | ----------- |
+| {Skill_Name} | {Skill_Description} |
+
+<!-- END:Available-Skills -->
+
+## Installation
+
+### Option 1: Skills (Recommended)
+
+Use the [Vercel Skills CLI](https://skills.sh/) to install skills directly:
+
+```bash
+# Install all skills
+npx skills add {Brand_Name}/agent-skills
+
+# Install specific skills
+npx skills add {Brand_Name}/agent-skills --skill {Skill_Name}
+
+# List available skills
+npx skills add {Brand_Name}/agent-skills --list
+```
+
+### Option 2: Claude Code Plugin
+
+Install via Claude Code's plugin system:
+
+```bash
+# Add the marketplace
+/plugin marketplace add {Brand_Name}/agent-skills
+
+# Install specific skill
+/plugin install {Skill_Name}-skill
+```
+
+## Adding New Skills
+
+Use the included script to add new skills:
+
+```bash
+node scripts/add-skill.js <skill-name> "<description>"
+```
+
+Example:
+
+```bash
+node scripts/add-skill.js {Skill_Name} "{Skill_Description}"
+```
+
+This will create the skill structure and automatically update this README and the marketplace.json.
+
+## Scripts
+
+| Script | Description |
+| ------ | ----------- |
+| `node scripts/add-skill.js` | Add a new skill to the repository |
+| `node scripts/sync-skills.js` | Sync README and marketplace.json with skills directory |
+
+## Contributing
+
+1. Fork this repository
+2. Create a new skill using `node scripts/add-skill.js`
+3. Edit the skill's `SKILL.md` with your content
+4. Submit a pull request
+
+## License
+
+{Skill_License}

package/template/scripts/add-skill.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+
+/**
+ * add-skill.js
+ *
+ * Adds a new skill to the repository.
+ *
+ * Usage: node scripts/add-skill.js <skill-name> <description>
+ *
+ * Example: node scripts/add-skill.js my-new-skill "Helps with X tasks"
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT_DIR = join(__dirname, "..");
+const SKILLS_DIR = join(ROOT_DIR, "skills");
+const MARKETPLACE_PATH = join(ROOT_DIR, ".claude-plugin", "marketplace.json");
+const SYNC_SCRIPT = join(__dirname, "sync-skills.js");
+
+const SKILLS_SUFFIX_REGEX = /-skills$/;
+
+function normalizeName(input) {
+  return input
+    .toLowerCase()
+    .trim()
+    .replace(/\s+/g, "-")
+    .replace(/[^a-z0-9-]/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function printUsage() {
+  console.log(`
+Usage: node scripts/add-skill.js <skill-name> <description>
+
+Arguments:
+  skill-name   Name of the skill (will be normalized to lowercase with hyphens)
+  description  Brief description of what the skill does
+
+Example:
+  node scripts/add-skill.js my-new-skill "Helps with data processing tasks"
+`);
+}
+
+async function loadMarketplace() {
+  try {
+    const content = await readFile(MARKETPLACE_PATH, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    console.error("Error: Could not read .claude-plugin/marketplace.json");
+    console.error("Make sure you're running this from the repository root.");
+    process.exit(1);
+  }
+}
+
+async function skillExists(skillName) {
+  try {
+    await readFile(join(SKILLS_DIR, skillName, "SKILL.md"), "utf-8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function generateSkillMd(skillName, description, marketplace) {
+  const brandName = marketplace.name.replace(SKILLS_SUFFIX_REGEX, "");
+  const license =
+    marketplace.plugins?.[0]?.license || marketplace.license || "MIT";
+
+  return `---
+name: ${skillName}
+description: ${description}
+license: ${license}
+metadata:
+  author: ${brandName}
+  version: "1.0.0"
+---
+
+`;
+}
+
+function generatePluginJson(skillName, description, marketplace) {
+  const owner = marketplace.owner || {};
+  const existingPlugin = marketplace.plugins?.[0] || {};
+
+  return JSON.stringify(
+    {
+      name: skillName,
+      description,
+      version: "1.0.0",
+      author: {
+        name: owner.name || "Your Name",
+        email: owner.email || "your.email@example.com",
+      },
+      license: existingPlugin.license || "MIT",
+      homepage: existingPlugin.homepage || "https://example.com",
+      repository: existingPlugin.repository || "",
+      keywords: existingPlugin.keywords || "ai, agent, skill",
+      category: existingPlugin.category || "general",
+    },
+    null,
+    2
+  );
+}
+
+async function runSyncScript() {
+  const { spawn } = await import("node:child_process");
+
+  return new Promise((resolve, reject) => {
+    const child = spawn("node", [SYNC_SCRIPT], {
+      stdio: "inherit",
+      cwd: ROOT_DIR,
+    });
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`sync-skills.js exited with code ${code}`));
+      }
+    });
+
+    child.on("error", reject);
+  });
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length < 2 || args.includes("--help") || args.includes("-h")) {
+    printUsage();
+    process.exit(args.includes("--help") || args.includes("-h") ? 0 : 1);
+  }
+
+  const [rawName, ...descParts] = args;
+  const description = descParts.join(" ");
+  const skillName = normalizeName(rawName);
+
+  if (!skillName) {
+    console.error(
+      "Error: Skill name must contain at least one letter or number"
+    );
+    process.exit(1);
+  }
+
+  if (!description) {
+    console.error("Error: Description is required");
+    process.exit(1);
+  }
+
+  if (await skillExists(skillName)) {
+    console.error(`Error: Skill "${skillName}" already exists`);
+    process.exit(1);
+  }
+
+  console.log(`\nCreating skill: ${skillName}\n`);
+
+  const marketplace = await loadMarketplace();
+  const skillDir = join(SKILLS_DIR, skillName);
+  const pluginDir = join(skillDir, ".claude-plugin");
+
+  // Create directories
+  await mkdir(pluginDir, { recursive: true });
+
+  // Generate files
+  const skillMd = generateSkillMd(skillName, description, marketplace);
+  const pluginJson = generatePluginJson(skillName, description, marketplace);
+
+  await writeFile(join(skillDir, "SKILL.md"), skillMd, "utf-8");
+  await writeFile(join(pluginDir, "plugin.json"), `${pluginJson}\n`, "utf-8");
+
+  console.log(`✓ Created skills/${skillName}/SKILL.md`);
+  console.log(`✓ Created skills/${skillName}/.claude-plugin/plugin.json`);
+  console.log();
+
+  // Run sync script
+  console.log("Running sync-skills.js...\n");
+  await runSyncScript();
+
+  console.log(`\nSkill "${skillName}" created successfully!`);
+  console.log("\nNext steps:");
+  console.log(
+    `  1. Edit skills/${skillName}/SKILL.md to add your skill content`
+  );
+  console.log(
+    `  2. Update skills/${skillName}/.claude-plugin/plugin.json if needed`
+  );
+  console.log();
+}
+
+main().catch((error) => {
+  console.error("Error:", error.message);
+  process.exit(1);
+});

package/template/scripts/sync-skills.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+
+/**
+ * sync-skills.js
+ *
+ * Syncs the Available Skills section in README.md and the plugins array
+ * in .claude-plugin/marketplace.json with the actual skills in skills/
+ *
+ * Usage: node scripts/sync-skills.js
+ */
+
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT_DIR = join(__dirname, "..");
+const SKILLS_DIR = join(ROOT_DIR, "skills");
+const README_PATH = join(ROOT_DIR, "README.md");
+const MARKETPLACE_PATH = join(ROOT_DIR, ".claude-plugin", "marketplace.json");
+
+const FRONTMATTER_REGEX = /^---\n([\s\S]*?)\n---/;
+const WHITESPACE_REGEX = /\S/;
+
+function parseValue(raw) {
+  const trimmed = raw.trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(FRONTMATTER_REGEX);
+  if (!match) {
+    return {};
+  }
+
+  const lines = match[1].split("\n");
+  const result = {};
+  let currentObject = null;
+
+  for (const line of lines) {
+    if (line.trim() === "") {
+      continue;
+    }
+
+    const colonIndex = line.indexOf(":");
+    if (colonIndex === -1) {
+      continue;
+    }
+
+    const indent = line.search(WHITESPACE_REGEX);
+    const key = line.slice(0, colonIndex).trim();
+    const rawValue = line.slice(colonIndex + 1);
+
+    if (indent > 0 && currentObject !== null) {
+      // Nested property
+      const value = parseValue(rawValue);
+      if (value !== "") {
+        currentObject[key] = value;
+      }
+    } else {
+      // Top-level property
+      const value = parseValue(rawValue);
+      if (value === "") {
+        // Start of a nested object
+        currentObject = {};
+        result[key] = currentObject;
+      } else {
+        currentObject = null;
+        result[key] = value;
+      }
+    }
+  }
+
+  return result;
+}
+
+async function discoverSkills() {
+  const skills = [];
+
+  let entries;
+  try {
+    entries = await readdir(SKILLS_DIR, { withFileTypes: true });
+  } catch {
+    console.warn("No skills directory found. Skipping sync.");
+    return skills;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    const skillDir = join(SKILLS_DIR, entry.name);
+    const skillMdPath = join(skillDir, "SKILL.md");
+    const pluginJsonPath = join(skillDir, ".claude-plugin", "plugin.json");
+
+    try {
+      const skillMd = await readFile(skillMdPath, "utf-8");
+      const frontmatter = parseFrontmatter(skillMd);
+
+      let pluginJson = {};
+      try {
+        const pluginContent = await readFile(pluginJsonPath, "utf-8");
+        pluginJson = JSON.parse(pluginContent);
+      } catch {
+        // Ignore missing or invalid plugin.json
+      }
+
+      const metadata = frontmatter.metadata || {};
+
+      skills.push({
+        dirName: entry.name,
+        name: frontmatter.name || entry.name,
+        description: frontmatter.description || pluginJson.description || "",
+        license: frontmatter.license || pluginJson.license || "MIT",
+        version: metadata.version || pluginJson.version || "1.0.0",
+        author: metadata.author || pluginJson.author || {},
+        homepage: pluginJson.homepage || "",
+        repository: pluginJson.repository || "",
+        category: pluginJson.category || "general",
+        keywords: pluginJson.keywords || "",
+      });
+    } catch (error) {
+      console.warn(
+        `Warning: Could not read skill at ${entry.name}:`,
+        error.message
+      );
+    }
+  }
+
+  return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function truncate(str, maxLength = 80) {
+  if (str.length <= maxLength) {
+    return str;
+  }
+  return `${str.slice(0, maxLength - 3)}...`;
+}
+
+function generateReadmeSkillsList(skills) {
+  if (skills.length === 0) {
+    return "\n*No skills available yet.*\n";
+  }
+
+  const lines = ["", "| Skill | Description |", "| ----- | ----------- |"];
+
+  for (const skill of skills) {
+    const escapedDesc = truncate(skill.description).replace(/\|/g, "\\|");
+    lines.push(`| ${skill.name} | ${escapedDesc} |`);
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+async function updateReadme(skills) {
+  const content = await readFile(README_PATH, "utf-8");
+  const startMarker = "<!-- START:Available-Skills -->";
+  const endMarker = "<!-- END:Available-Skills -->";
+
+  const startIndex = content.indexOf(startMarker);
+  const endIndex = content.indexOf(endMarker);
+
+  if (startIndex === -1 || endIndex === -1) {
+    console.warn("Warning: Could not find skill markers in README.md");
+    return false;
+  }
+
+  const skillsList = generateReadmeSkillsList(skills);
+  const newContent =
+    content.slice(0, startIndex + startMarker.length) +
+    skillsList +
+    content.slice(endIndex);
+
+  await writeFile(README_PATH, newContent, "utf-8");
+  return true;
+}
+
+async function updateMarketplace(skills) {
+  let marketplace;
+  try {
+    const content = await readFile(MARKETPLACE_PATH, "utf-8");
+    marketplace = JSON.parse(content);
+  } catch {
+    console.warn("Warning: Could not read marketplace.json");
+    return false;
+  }
+
+  marketplace.plugins = skills.map((skill) => ({
+    name: `${skill.name}-skill`,
+    description: skill.description,
+    version: skill.version,
+    author: skill.author,
+    source: `./skills/${skill.dirName}`,
+    homepage: skill.homepage,
+    repository: skill.repository,
+    license: skill.license,
+    category: skill.category,
+    keywords: skill.keywords,
+  }));
+
+  await writeFile(
+    MARKETPLACE_PATH,
+    `${JSON.stringify(marketplace, null, 2)}\n`,
+    "utf-8"
+  );
+  return true;
+}
+
+async function main() {
+  console.log("Syncing agent skill(s)...\n");
+
+  const skills = await discoverSkills();
+  console.log(`Found ${skills.length} agent skill(s):`);
+  for (const skill of skills) {
+    console.log(`  - ${skill.name}`);
+  }
+  console.log();
+
+  const readmeUpdated = await updateReadme(skills);
+  if (readmeUpdated) {
+    console.log("✓ Updated README.md");
+  }
+
+  const marketplaceUpdated = await updateMarketplace(skills);
+  if (marketplaceUpdated) {
+    console.log("✓ Updated .claude-plugin/marketplace.json");
+  }
+
+  console.log("\nDone!");
+}
+
+main().catch((error) => {
+  console.error("Error:", error.message);
+  process.exit(1);
+});

package/template/skills/{Skill_Name}/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "{Skill_Name}",
+  "description": "{Skill_Description}",
+  "version": "1.0.0",
+  "author": {
+    "name": "{Creator_Name}",
+    "email": "{Creator_Email}"
+  },
+  "license": "{Skill_License}",
+  "homepage": "{Skill_Homepage}",
+  "repository": "https://github.com/{Skill_Repository}",
+  "keywords": "{Skill_Keywords}",
+  "category": "{Skill_Category}"
+}

package/template/skills/{Skill_Name}/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: {Skill_Name}
+description: {Skill_Description}
+license: {Skill_License}
+metadata:
+  author: {Brand_Name}
+  version: "1.0.0"
+---
+