general-skills 0.1.0

package/README.md

@@ -0,0 +1,155 @@
+# General Skills
+
+一个面向 AI 编程工具的通用 Skills 仓库。这里的 `skills/` 是技能源码目录，npm 包只发布轻量级命令行工具 `gskills`，不会把 `skills/` 打进包里。这样后续新增或更新技能后，用户不需要升级 npm 包，也可以从 GitHub 仓库实时拉取最新技能。
+
+默认远程源：
+
+```text
+zhy15608103017/generalSkills@main
+```
+
+## 通过 npm 使用
+
+不全局安装，直接使用：
+
+```powershell
+npx general-skills list
+npx general-skills add my-skill another-skill
+```
+
+全局安装后使用：
+
+```powershell
+npm install -g general-skills
+gskills list
+gskills aicodings
+gskills add my-skill another-skill
+gskills remove my-skill --aicoding claude
+```
+
+当 `gskills add` 或 `gskills remove` 在交互式终端中运行，并且没有传入 `--aicoding` 时，会出现 AI 编程工具选择列表。默认选项是 `default`，安装目录是 `.agents/skills`。在 CI 或脚本等非交互环境中，会自动使用 `default`，避免命令卡住。
+
+## 支持的 AI 编程工具
+
+```powershell
+gskills aicodings
+```
+
+当前目标：
+
+| 目标 | 安装目录 |
+| --- | --- |
+| `default` | `.agents/skills` |
+| `codex` | `.agents/skills` |
+| `claude` | `.claude/skills` |
+| `cursor` | `.cursor/skills` |
+| `trae` | `.trae/skills` |
+| `windsurf` | `.windsurf/skills` |
+| `gemini` | `.gemini/skills` |
+| `opencode` | `.opencode/skills` |
+
+也可以直接指定目标：
+
+```powershell
+gskills add my-skill --aicoding default
+gskills add my-skill --aicoding codex
+gskills add my-skill --aicoding claude
+gskills add my-skill --aicoding cursor
+gskills add my-skill --aicoding trae
+gskills add my-skill --aicoding windsurf
+gskills add my-skill --aicoding gemini
+gskills add my-skill --aicoding opencode
+gskills add my-skill --aicoding all
+```
+
+`--tool` 仍然保留为 `--aicoding` 的兼容别名。
+
+## 切换远程源
+
+使用其他仓库或分支：
+
+```powershell
+gskills list --source owner/repo --ref main
+gskills add my-skill --source https://github.com/owner/repo.git --ref main
+```
+
+也可以通过环境变量覆盖默认值：
+
+```powershell
+$env:GSKILLS_SOURCE = "owner/repo"
+$env:GSKILLS_REF = "main"
+gskills list
+```
+
+## 仓库结构
+
+```text
+skills/                  # 技能源码目录，每个技能一个文件夹
+  example-skill/
+    SKILL.md             # 必需：包含 name 和 description frontmatter
+    scripts/             # 可选：可重复执行的脚本
+    references/          # 可选：按需加载的参考文档
+    assets/              # 可选：模板、图片、示例文件等资源
+scripts/                 # 仓库维护脚本
+bin/                     # 发布到 npm 的 gskills 命令
+templates/               # 新技能模板
+docs/                    # 兼容性和设计文档
+```
+
+请把 `skills/` 作为唯一手写源码目录。发布到 npm 时，`package.json` 的 `files` 白名单会排除 `skills/`，确保安装包保持轻量。
+
+## 创建新技能
+
+```powershell
+npm run new-skill -- my-skill --description "Use when doing a specific repeatable task." --resources references,scripts
+```
+
+该命令会创建 `skills/my-skill/SKILL.md`，并按需创建 `references/`、`scripts/`、`assets/` 等资源目录。
+
+## 校验技能
+
+```powershell
+npm run validate
+npm test
+```
+
+`npm run validate` 会校验技能目录命名和 `SKILL.md` frontmatter。`npm test` 会运行命令行工具和安装逻辑的自动化测试。
+
+## 本地开发时安装技能
+
+如果技能还没有推送到 GitHub `main`，`gskills add` 看不到它。此时可以使用本仓库的本地安装脚本：
+
+```powershell
+npm run install-skills -- --aicoding default --dest D:\path\to\project --skills my-skill
+```
+
+安装到所有支持目标：
+
+```powershell
+npm run install-skills -- --aicoding all --dest D:\path\to\project --skills my-skill,another-skill
+```
+
+安装到当前仓库用于本地测试：
+
+```powershell
+npm run install-skills -- --aicoding default --dest . --skills code-review-loop
+```
+
+兼容旧用法时仍可使用 `--tool`，但新文档和示例优先使用 `--aicoding`。
+
+发布后的用户使用方式仍然推荐：
+
+```powershell
+gskills add my-skill
+gskills remove my-skill
+```
+
+## 发布前检查
+
+```powershell
+npm test
+npm run validate
+npm pack --dry-run
+```
+
+`npm pack --dry-run` 的输出中不应包含 `skills/`。

package/bin/gskills.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import path from "node:path";
+
+import {
+  getCliAICodingTarget,
+  promptAICodingTarget,
+  renderAICodingChoices
+} from "../scripts/lib/aicoding-select.mjs";
+import { listAICodingTargets, parseCliArgs } from "../scripts/lib/skill-utils.mjs";
+import {
+  DEFAULT_REF,
+  DEFAULT_SOURCE,
+  addRemoteSkills,
+  listRemoteSkills,
+  removeInstalledSkills,
+  resolveRemoteConfig
+} from "../scripts/lib/remote-skills.mjs";
+
+async function main() {
+  const [command = "help", ...rest] = process.argv.slice(2);
+  const args = parseCliArgs(rest);
+
+  if (command === "help" || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+
+  if (command === "tools" || command === "aicodings" || command === "targets") {
+    printAICodings();
+    return;
+  }
+
+  if (command === "list") {
+    const config = resolveRemoteConfig({ source: args.source, ref: args.ref });
+    const skills = await listRemoteSkills(config);
+    if (skills.length === 0) {
+      console.log("No remote skills found.");
+      return;
+    }
+    for (const skill of skills) {
+      console.log(`${skill.name} - ${skill.description}`);
+    }
+    return;
+  }
+
+  if (command === "add") {
+    const target = getCliAICodingTarget(args);
+    const aicoding = target || (await promptAICodingTarget());
+    const result = await addRemoteSkills({
+      source: args.source,
+      ref: args.ref,
+      destDir: path.resolve(args.dest || "."),
+      tool: aicoding,
+      skills: args._
+    });
+    for (const entry of result.installed) {
+      console.log(`Added ${entry.skillName} for ${entry.tool}: ${entry.path}`);
+    }
+    return;
+  }
+
+  if (command === "remove" || command === "rm") {
+    const target = getCliAICodingTarget(args);
+    const aicoding = target || (await promptAICodingTarget());
+    const result = await removeInstalledSkills({
+      destDir: path.resolve(args.dest || "."),
+      tool: aicoding,
+      skills: args._
+    });
+    for (const entry of result.removed) {
+      console.log(`Removed ${entry.skillName} for ${entry.tool}: ${entry.path}`);
+    }
+    return;
+  }
+
+  throw new Error(`Unknown command "${command}". Run gskills help.`);
+}
+
+function printAICodings() {
+  console.log(renderAICodingChoices());
+}
+
+function printHelp() {
+  console.log(`gskills
+
+Usage:
+  gskills list [--source owner/repo] [--ref main]
+  gskills add <skill...> [--aicoding target] [--dest path]
+  gskills remove <skill...> [--aicoding target] [--dest path]
+  gskills aicodings
+
+Defaults:
+  source: ${DEFAULT_SOURCE}
+  ref: ${DEFAULT_REF}
+  aicoding: interactive selection in a TTY, default in scripts
+
+Targets:
+${listAICodingTargets()
+  .map((target) => `  ${target.name} -> ${target.relativePath}`)
+  .join("\n")}
+
+Compatibility:
+  --tool works as an alias for --aicoding
+
+Environment:
+  GSKILLS_SOURCE=owner/repo
+  GSKILLS_REF=main`);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/docs/compatibility.md

@@ -0,0 +1,110 @@
+# Tool Compatibility
+
+This repository uses `skills/` as the canonical source and installs copies into project-local directories expected by common coding tools.
+
+When used through npm, `gskills` fetches `skills/` from `zhy15608103017/generalSkills@main` by default. Override the source with `--source owner/repo` or `GSKILLS_SOURCE`; override the ref with `--ref` or `GSKILLS_REF`.
+
+Run `gskills aicodings` to list supported AI coding targets. If `gskills add <skill>` runs in an interactive terminal without `--aicoding`, it opens a selection list. In non-interactive environments, it uses `default`, which writes to `.agents/skills`.
+
+## Supported Targets
+
+| Target | Directory |
+| --- | --- |
+| `default` | `.agents/skills` |
+| `codex` | `.agents/skills` |
+| `claude` / `claude-code` | `.claude/skills` |
+| `cursor` | `.cursor/skills` |
+| `trae` | `.trae/skills` |
+| `windsurf` / `cascade` | `.windsurf/skills` |
+| `gemini` / `gemini-cli` | `.gemini/skills` |
+| `opencode` | `.opencode/skills` |
+
+## Codex
+
+Use `.agents/skills` in the target project for Codex-style project skills. Run:
+
+```powershell
+npx general-skills add my-skill --aicoding codex
+```
+
+For local repository development:
+
+```powershell
+npm run install-skills -- --aicoding codex --dest D:\path\to\project
+```
+
+## Claude Code
+
+Use `.claude/skills` in the target project for Claude Code project skills. Run:
+
+```powershell
+npx general-skills add my-skill --aicoding claude
+```
+
+## Cursor
+
+Use `.cursor/skills` in the target project for Cursor project skills. Run:
+
+```powershell
+npx general-skills add my-skill --aicoding cursor
+```
+
+## Trae
+
+Use `.trae/skills` in the target project for Trae project skills. Run:
+
+```powershell
+npx general-skills add my-skill --aicoding trae
+```
+
+For local repository development:
+
+```powershell
+npm run install-skills -- --aicoding trae --dest D:\path\to\project
+```
+
+## opencode
+
+Use `.opencode/skills` in the target project for opencode project skills. Run:
+
+```powershell
+npx general-skills add my-skill --aicoding opencode
+```
+
+## Windsurf
+
+Use `.windsurf/skills` in the target project for Windsurf/Cascade project skills. Run:
+
+```powershell
+npx general-skills add my-skill --aicoding windsurf
+```
+
+## Gemini CLI
+
+Use `.gemini/skills` in the target project for Gemini CLI project skills. Run:
+
+```powershell
+npx general-skills add my-skill --aicoding gemini
+```
+
+For local repository development:
+
+```powershell
+npm run install-skills -- --aicoding gemini --dest D:\path\to\project
+```
+
+## Multi-Tool Install
+
+Use `--aicoding all` when a project is used by multiple coding tools:
+
+```powershell
+npx general-skills add my-skill --aicoding all
+```
+
+For local repository development:
+
+```powershell
+npm run install-skills -- --aicoding all --dest D:\path\to\project
+```
+
+The install command replaces generated copies of each selected skill, while leaving unrelated target project files alone.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "general-skills",
+  "version": "0.1.0",
+  "description": "A lightweight CLI for installing reusable Agent Skills into AI coding tools.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhy15608103017/generalSkills.git"
+  },
+  "keywords": [
+    "agent-skills",
+    "codex",
+    "claude-code",
+    "cursor",
+    "trae",
+    "windsurf",
+    "gemini-cli",
+    "opencode",
+    "cli"
+  ],
+  "bin": {
+    "gskills": "bin/gskills.mjs"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "templates/",
+    "README.md",
+    "docs/compatibility.md"
+  ],
+  "scripts": {
+    "test": "node --test tests",
+    "validate": "node scripts/validate-skills.mjs",
+    "new-skill": "node scripts/new-skill.mjs",
+    "install-skills": "node scripts/install-skills.mjs",
+    "gskills": "node bin/gskills.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/scripts/install-skills.mjs

@@ -0,0 +1,78 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import {
+  copyDirectory,
+  listSkillDirs,
+  parseCliArgs,
+  resolveToolTargets,
+  validateSkillDir,
+  writeTargetConfig
+} from "./lib/skill-utils.mjs";
+
+export async function installSkills({
+  repoDir = process.cwd(),
+  destDir = process.cwd(),
+  tool = "all",
+  skills
+} = {}) {
+  const selectedNames = skills ? new Set(skills) : null;
+  const skillDirs = (await listSkillDirs(repoDir)).filter(
+    (skill) => !selectedNames || selectedNames.has(skill.name)
+  );
+
+  if (selectedNames && skillDirs.length !== selectedNames.size) {
+    const found = new Set(skillDirs.map((skill) => skill.name));
+    const missing = [...selectedNames].filter((name) => !found.has(name));
+    throw new Error(`Missing skill(s): ${missing.join(", ")}`);
+  }
+
+  for (const skillDir of skillDirs) {
+    const validation = await validateSkillDir(skillDir);
+    if (validation.errors.length > 0) {
+      throw new Error(validation.errors.join("\n"));
+    }
+  }
+
+  const targets = resolveToolTargets(tool);
+  const installed = [];
+  for (const target of targets) {
+    for (const skillDir of skillDirs) {
+      const destination = path.join(destDir, target.relativePath, skillDir.name);
+      await copyDirectory(skillDir.path, destination);
+      await writeTargetConfig({ destDir, target });
+      installed.push({
+        tool: target.tool,
+        skillName: skillDir.name,
+        path: destination
+      });
+    }
+  }
+
+  return { installed };
+}
+
+async function main() {
+  const args = parseCliArgs(process.argv.slice(2));
+  const skills = args.skills ? String(args.skills).split(",").map((name) => name.trim()) : undefined;
+  const result = await installSkills({
+    repoDir: path.resolve(args.repo || "."),
+    destDir: path.resolve(args.dest || "."),
+    tool: args.aicoding || args.tool || "all",
+    skills
+  });
+
+  for (const entry of result.installed) {
+    console.log(`Installed ${entry.skillName} for ${entry.tool}: ${entry.path}`);
+  }
+  if (result.installed.length === 0) {
+    console.log("No skills to install.");
+  }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] || "").href) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/scripts/lib/aicoding-select.mjs

@@ -0,0 +1,84 @@
+import readline from "node:readline";
+
+import { listAICodingTargets } from "./skill-utils.mjs";
+
+export function getCliAICodingTarget(args, { isTTY = process.stdin.isTTY } = {}) {
+  if (args.aicoding) return args.aicoding;
+  if (args.tool) return args.tool;
+  return isTTY ? null : "default";
+}
+
+export function renderAICodingChoices() {
+  return listAICodingTargets()
+    .map((target) => {
+      const aliases = target.aliases.length > 0 ? ` aliases: ${target.aliases.join(", ")}` : "";
+      return `${target.name} - ${target.label} -> ${target.relativePath}${aliases}`;
+    })
+    .join("\n");
+}
+
+export async function promptAICodingTarget({
+  stdin = process.stdin,
+  stdout = process.stdout
+} = {}) {
+  if (!stdin.isTTY) {
+    return "default";
+  }
+
+  const choices = listAICodingTargets();
+  let selectedIndex = 0;
+
+  readline.emitKeypressEvents(stdin);
+  const previousRawMode = stdin.isRaw;
+  if (typeof stdin.setRawMode === "function") {
+    stdin.setRawMode(true);
+  }
+  stdin.resume();
+
+  return await new Promise((resolve, reject) => {
+    const render = () => {
+      stdout.write("\x1b[2J\x1b[0f");
+      stdout.write("Select AI coding target:\n\n");
+      choices.forEach((choice, index) => {
+        const marker = index === selectedIndex ? "> " : "  ";
+        stdout.write(`${marker}${choice.name} - ${choice.label} (${choice.relativePath})\n`);
+      });
+      stdout.write("\nUse Up/Down, then Enter.\n");
+    };
+
+    const cleanup = () => {
+      stdin.off("keypress", onKeypress);
+      if (typeof stdin.setRawMode === "function") {
+        stdin.setRawMode(Boolean(previousRawMode));
+      }
+      stdin.pause();
+      stdout.write("\n");
+    };
+
+    const onKeypress = (_text, key) => {
+      if (key?.name === "down") {
+        selectedIndex = (selectedIndex + 1) % choices.length;
+        render();
+        return;
+      }
+      if (key?.name === "up") {
+        selectedIndex = (selectedIndex - 1 + choices.length) % choices.length;
+        render();
+        return;
+      }
+      if (key?.name === "return" || key?.name === "enter") {
+        const selected = choices[selectedIndex].name;
+        cleanup();
+        resolve(selected);
+        return;
+      }
+      if (key?.ctrl && key.name === "c") {
+        cleanup();
+        reject(new Error("Cancelled."));
+      }
+    };
+
+    stdin.on("keypress", onKeypress);
+    render();
+  });
+}

package/scripts/lib/remote-skills.mjs

@@ -0,0 +1,256 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { installSkills } from "../install-skills.mjs";
+import {
+  parseSkillFrontmatter,
+  resolveToolTargets,
+  validateSkillName
+} from "./skill-utils.mjs";
+
+export const DEFAULT_SOURCE = "zhy15608103017/generalSkills";
+export const DEFAULT_REF = "main";
+
+export function resolveRemoteConfig({
+  source,
+  ref,
+  env = process.env
+} = {}) {
+  return {
+    source: source || env.GSKILLS_SOURCE || DEFAULT_SOURCE,
+    ref: ref || env.GSKILLS_REF || DEFAULT_REF
+  };
+}
+
+export function parseGitHubSource(source) {
+  const value = String(source || "").trim();
+  const https = value.match(/^https:\/\/github\.com\/([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/);
+  if (https) {
+    return {
+      owner: https[1],
+      repo: stripGitSuffix(https[2])
+    };
+  }
+
+  const ssh = value.match(/^git@github\.com:([^/\s]+)\/([^/\s]+?)(?:\.git)?$/);
+  if (ssh) {
+    return {
+      owner: ssh[1],
+      repo: stripGitSuffix(ssh[2])
+    };
+  }
+
+  const ownerRepo = value.match(/^([^/:\s]+)\/([^/:\s]+)$/);
+  if (ownerRepo) {
+    return {
+      owner: ownerRepo[1],
+      repo: stripGitSuffix(ownerRepo[2])
+    };
+  }
+
+  throw new Error(`Invalid GitHub source "${source}". Use owner/repo or a GitHub URL.`);
+}
+
+function stripGitSuffix(value) {
+  return value.endsWith(".git") ? value.slice(0, -4) : value;
+}
+
+export async function listRemoteSkills({
+  source,
+  ref,
+  fetchImpl = globalThis.fetch
+} = {}) {
+  const config = resolveRemoteConfig({ source, ref });
+  const tree = await fetchRemoteTree({ ...config, fetchImpl });
+  const skillNames = discoverSkillNames(tree);
+  const skills = [];
+
+  for (const skillName of skillNames) {
+    const text = await fetchRawText({
+      ...config,
+      remotePath: `skills/${skillName}/SKILL.md`,
+      fetchImpl
+    });
+    const frontmatter = parseSkillFrontmatter(text);
+    skills.push({
+      name: frontmatter.name,
+      description: frontmatter.description
+    });
+  }
+
+  return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export async function addRemoteSkills({
+  source,
+  ref,
+  destDir = process.cwd(),
+  tool = "all",
+  skills,
+  fetchImpl = globalThis.fetch
+} = {}) {
+  const requestedSkills = normalizeRequestedSkills(skills);
+  const config = resolveRemoteConfig({ source, ref });
+  const tree = await fetchRemoteTree({ ...config, fetchImpl });
+  const available = new Set(discoverSkillNames(tree));
+  const missing = requestedSkills.filter((skill) => !available.has(skill));
+  if (missing.length > 0) {
+    throw new Error(`Missing remote skill(s): ${missing.join(", ")}`);
+  }
+
+  const tempRepo = await makeTempRepo();
+  try {
+    for (const skillName of requestedSkills) {
+      await downloadRemoteSkill({
+        ...config,
+        tree,
+        skillName,
+        repoDir: tempRepo,
+        fetchImpl
+      });
+    }
+
+    return await installSkills({
+      repoDir: tempRepo,
+      destDir,
+      tool,
+      skills: requestedSkills
+    });
+  } finally {
+    await rm(tempRepo, { recursive: true, force: true });
+  }
+}
+
+export async function removeInstalledSkills({
+  destDir = process.cwd(),
+  tool = "all",
+  skills
+} = {}) {
+  const requestedSkills = normalizeRequestedSkills(skills);
+  const targets = resolveToolTargets(tool);
+  const removed = [];
+
+  for (const target of targets) {
+    for (const skillName of requestedSkills) {
+      const destination = path.join(destDir, target.relativePath, skillName);
+      await rm(destination, { recursive: true, force: true });
+      removed.push({
+        tool: target.tool,
+        skillName,
+        path: destination
+      });
+    }
+  }
+
+  return { removed };
+}
+
+async function fetchRemoteTree({ source, ref, fetchImpl }) {
+  ensureFetch(fetchImpl);
+  const { owner, repo } = parseGitHubSource(source);
+  const url = `https://api.github.com/repos/${owner}/${repo}/git/trees/${encodeURIComponent(ref)}?recursive=1`;
+  const response = await fetchImpl(url, {
+    headers: {
+      "Accept": "application/vnd.github+json",
+      "User-Agent": "gskills"
+    }
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch remote skill tree: HTTP ${response.status} ${response.statusText}`);
+  }
+  const data = await response.json();
+  if (!Array.isArray(data.tree)) {
+    throw new Error("GitHub tree response did not include a tree array.");
+  }
+  return data.tree;
+}
+
+function discoverSkillNames(tree) {
+  return tree
+    .filter((entry) => entry.type === "blob")
+    .map((entry) => entry.path)
+    .map((remotePath) => remotePath.match(/^skills\/([^/]+)\/SKILL\.md$/))
+    .filter(Boolean)
+    .map((match) => match[1])
+    .filter((name) => validateSkillName(name).length === 0)
+    .sort((a, b) => a.localeCompare(b));
+}
+
+async function downloadRemoteSkill({
+  source,
+  ref,
+  tree,
+  skillName,
+  repoDir,
+  fetchImpl
+}) {
+  const prefix = `skills/${skillName}/`;
+  const files = tree
+    .filter((entry) => entry.type === "blob")
+    .map((entry) => entry.path)
+    .filter((remotePath) => remotePath.startsWith(prefix));
+
+  for (const remotePath of files) {
+    const bytes = await fetchRawBytes({
+      source,
+      ref,
+      remotePath,
+      fetchImpl
+    });
+    const outputPath = path.join(repoDir, ...remotePath.split("/"));
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, bytes);
+  }
+}
+
+async function fetchRawText(options) {
+  const bytes = await fetchRawBytes(options);
+  return bytes.toString("utf8");
+}
+
+async function fetchRawBytes({ source, ref, remotePath, fetchImpl }) {
+  ensureFetch(fetchImpl);
+  const { owner, repo } = parseGitHubSource(source);
+  const url = rawGitHubUrl({ owner, repo, ref, remotePath });
+  const response = await fetchImpl(url, {
+    headers: {
+      "User-Agent": "gskills"
+    }
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${remotePath}: HTTP ${response.status} ${response.statusText}`);
+  }
+  if (typeof response.arrayBuffer === "function") {
+    return Buffer.from(await response.arrayBuffer());
+  }
+  return Buffer.from(await response.text(), "utf8");
+}
+
+function rawGitHubUrl({ owner, repo, ref, remotePath }) {
+  const encodedPath = remotePath.split("/").map(encodeURIComponent).join("/");
+  return `https://raw.githubusercontent.com/${owner}/${repo}/${encodeURIComponent(ref)}/${encodedPath}`;
+}
+
+function normalizeRequestedSkills(skills) {
+  const requested = Array.isArray(skills) ? skills : String(skills || "").split(",");
+  const normalized = requested.map((skill) => String(skill).trim()).filter(Boolean);
+  if (normalized.length === 0) {
+    throw new Error("At least one skill name is required.");
+  }
+  const errors = normalized.flatMap((skill) => validateSkillName(skill).map((error) => `${skill}: ${error}`));
+  if (errors.length > 0) {
+    throw new Error(errors.join("\n"));
+  }
+  return [...new Set(normalized)];
+}
+
+async function makeTempRepo() {
+  return await mkdtemp(path.join(os.tmpdir(), "gskills-"));
+}
+
+function ensureFetch(fetchImpl) {
+  if (typeof fetchImpl !== "function") {
+    throw new Error("fetch is unavailable. Use Node.js 20 or newer.");
+  }
+}

package/scripts/lib/skill-utils.mjs

@@ -0,0 +1,300 @@
+import { cp, mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export const AI_CODING_TARGETS = [
+  {
+    name: "default",
+    label: "Default / Agent Skills",
+    relativePath: ".agents/skills",
+    aliases: ["agent", "agents"]
+  },
+  {
+    name: "codex",
+    label: "Codex",
+    relativePath: ".agents/skills",
+    aliases: ["openai-codex"]
+  },
+  {
+    name: "claude",
+    label: "Claude Code",
+    relativePath: ".claude/skills",
+    aliases: ["claude-code"]
+  },
+  {
+    name: "cursor",
+    label: "Cursor",
+    relativePath: ".cursor/skills",
+    aliases: []
+  },
+  {
+    name: "gemini",
+    label: "Gemini CLI",
+    relativePath: ".gemini/skills",
+    aliases: ["gemini-cli"]
+  },
+  {
+    name: "opencode",
+    label: "opencode",
+    relativePath: ".opencode/skills",
+    aliases: ["open-code"]
+  },
+  {
+    name: "trae",
+    label: "Trae",
+    relativePath: ".trae/skills",
+    aliases: ["trae-ai"]
+  },
+  {
+    name: "windsurf",
+    label: "Windsurf / Cascade",
+    relativePath: ".windsurf/skills",
+    aliases: ["cascade"]
+  }
+];
+
+export const TOOL_TARGETS = Object.fromEntries(
+  AI_CODING_TARGETS.filter((target) => target.name !== "default").map((target) => [
+    target.name,
+    target.relativePath
+  ])
+);
+
+export function normalizeSkillName(value) {
+  return String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-{2,}/g, "-");
+}
+
+export function validateSkillName(name) {
+  const errors = [];
+  if (!name) {
+    errors.push("Skill name is required.");
+    return errors;
+  }
+  if (name.length > 64) {
+    errors.push("Skill name must be 64 characters or fewer.");
+  }
+  if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/.test(name)) {
+    errors.push("Skill name must use lowercase letters, digits, and hyphens only.");
+  }
+  if (name.includes("--")) {
+    errors.push("Skill name must not contain repeated hyphens.");
+  }
+  return errors;
+}
+
+export function parseSkillFrontmatter(text) {
+  const lines = text.split(/\r?\n/);
+  if (lines[0] !== "---") {
+    throw new Error("SKILL.md must start with YAML frontmatter.");
+  }
+
+  const endIndex = lines.findIndex((line, index) => index > 0 && line === "---");
+  if (endIndex === -1) {
+    throw new Error("SKILL.md frontmatter must end with a closing --- line.");
+  }
+
+  const data = {};
+  for (const line of lines.slice(1, endIndex)) {
+    if (!line.trim()) continue;
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!match) {
+      throw new Error(`Invalid frontmatter line: ${line}`);
+    }
+    const [, key, rawValue] = match;
+    data[key] = stripYamlString(rawValue.trim());
+  }
+
+  if (!data.name) {
+    throw new Error("SKILL.md frontmatter must include name.");
+  }
+  if (!data.description) {
+    throw new Error("SKILL.md frontmatter must include description.");
+  }
+
+  return {
+    name: data.name,
+    description: data.description
+  };
+}
+
+function stripYamlString(value) {
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+export async function listSkillDirs(repoDir) {
+  const skillsDir = path.join(repoDir, "skills");
+  try {
+    const entries = await readdir(skillsDir, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isDirectory())
+      .filter((entry) => !entry.name.startsWith("."))
+      .map((entry) => ({
+        name: entry.name,
+        path: path.join(skillsDir, entry.name)
+      }))
+      .sort((a, b) => a.name.localeCompare(b.name));
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+export async function validateSkillDir(skillDir) {
+  const errors = [];
+  const skillFile = path.join(skillDir.path, "SKILL.md");
+
+  for (const error of validateSkillName(skillDir.name)) {
+    errors.push(`${skillDir.name}: ${error}`);
+  }
+
+  let frontmatter;
+  try {
+    const text = await readFile(skillFile, "utf8");
+    frontmatter = parseSkillFrontmatter(text);
+  } catch (error) {
+    errors.push(`${skillDir.name}: ${error.message}`);
+    return { skill: skillDir.name, errors };
+  }
+
+  if (frontmatter.name !== skillDir.name) {
+    errors.push(
+      `${skillDir.name}: frontmatter name must match folder name "${skillDir.name}".`
+    );
+  }
+  for (const error of validateSkillName(frontmatter.name)) {
+    errors.push(`${skillDir.name}: frontmatter ${error}`);
+  }
+  if (!frontmatter.description.trim()) {
+    errors.push(`${skillDir.name}: frontmatter description must not be empty.`);
+  }
+
+  return { skill: skillDir.name, errors };
+}
+
+export function resolveToolTargets(tool) {
+  const selected = String(tool ?? "default").toLowerCase();
+  const targets =
+    selected === "all"
+      ? AI_CODING_TARGETS.filter((target) => target.name !== "default")
+      : [resolveSingleAICodingTarget(selected)];
+
+  return targets.map((target) => ({
+    tool: target.name,
+    label: target.label,
+    relativePath: target.relativePath
+  }));
+}
+
+export function resolveSingleAICodingTarget(value) {
+  const selected = String(value ?? "default").toLowerCase();
+  const target = AI_CODING_TARGETS.find(
+    (entry) => entry.name === selected || entry.aliases.includes(selected)
+  );
+  if (!target) {
+    const names = AI_CODING_TARGETS.map((entry) => entry.name).join(", ");
+    throw new Error(`Unsupported AI coding target "${value}". Use ${names}, or all.`);
+  }
+  return target;
+}
+
+export function listAICodingTargets() {
+  return AI_CODING_TARGETS.map((target) => ({
+    name: target.name,
+    label: target.label,
+    relativePath: target.relativePath,
+    aliases: [...target.aliases]
+  }));
+}
+
+export async function writeTargetConfig({ destDir, target }) {
+  if (target.tool !== "gemini") {
+    return [];
+  }
+
+  const extensionDir = path.join(destDir, ".gemini", "extensions", "gskills");
+  await mkdir(extensionDir, { recursive: true });
+  const manifestPath = path.join(extensionDir, "gemini-extension.json");
+  const manifest = {
+    name: "gskills",
+    version: "0.1.0",
+    mcpServers: {}
+  };
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+  return [manifestPath];
+}
+
+export function parseResourceList(value) {
+  if (Array.isArray(value)) return value;
+  if (!value) return [];
+  const allowed = new Set(["scripts", "references", "assets"]);
+  return String(value)
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map((entry) => {
+      if (!allowed.has(entry)) {
+        throw new Error(`Unsupported resource "${entry}". Use scripts, references, or assets.`);
+      }
+      return entry;
+    });
+}
+
+export async function copyDirectory(source, destination) {
+  await rm(destination, { recursive: true, force: true });
+  await mkdir(path.dirname(destination), { recursive: true });
+  await cp(source, destination, {
+    recursive: true,
+    force: true,
+    errorOnExist: false
+  });
+}
+
+export async function pathExists(filePath) {
+  try {
+    await stat(filePath);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+export function parseCliArgs(argv) {
+  const args = {
+    _: []
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith("--")) {
+      args._.push(arg);
+      continue;
+    }
+
+    const [key, inlineValue] = arg.slice(2).split(/=(.*)/s, 2);
+    if (inlineValue !== undefined && inlineValue !== "") {
+      args[key] = inlineValue;
+      continue;
+    }
+
+    const next = argv[index + 1];
+    if (next && !next.startsWith("--")) {
+      args[key] = next;
+      index += 1;
+    } else {
+      args[key] = true;
+    }
+  }
+
+  return args;
+}

package/scripts/new-skill.mjs

@@ -0,0 +1,98 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import {
+  normalizeSkillName,
+  parseCliArgs,
+  parseResourceList,
+  pathExists,
+  validateSkillName
+} from "./lib/skill-utils.mjs";
+
+export async function createSkill({
+  repoDir = process.cwd(),
+  name,
+  description,
+  resources = [],
+  force = false
+}) {
+  const skillName = normalizeSkillName(name);
+  const nameErrors = validateSkillName(skillName);
+  if (nameErrors.length > 0) {
+    throw new Error(nameErrors.join(" "));
+  }
+
+  const skillDescription =
+    description?.trim() || `Use when working with ${skillName.replaceAll("-", " ")}.`;
+  const skillDir = path.join(repoDir, "skills", skillName);
+  if (!force && (await pathExists(skillDir))) {
+    throw new Error(`Skill "${skillName}" already exists. Use --force to replace it.`);
+  }
+
+  await mkdir(skillDir, { recursive: true });
+  await writeFile(path.join(skillDir, "SKILL.md"), renderSkillMarkdown(skillName, skillDescription));
+
+  for (const resource of parseResourceList(resources)) {
+    await mkdir(path.join(skillDir, resource), { recursive: true });
+    await writeFile(path.join(skillDir, resource, ".gitkeep"), "");
+  }
+
+  return {
+    name: skillName,
+    path: skillDir
+  };
+}
+
+function renderSkillMarkdown(name, description) {
+  return [
+    "---",
+    `name: ${name}`,
+    `description: ${description}`,
+    "---",
+    "",
+    `# ${titleCase(name)}`,
+    "",
+    "Use this skill when the request matches the frontmatter description.",
+    "",
+    "## Workflow",
+    "",
+    "1. Read any relevant files in this skill before acting.",
+    "2. Prefer bundled scripts for repeatable operations.",
+    "3. Keep outputs focused on the user's request.",
+    ""
+  ].join("\n");
+}
+
+function titleCase(name) {
+  return name
+    .split("-")
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+async function main() {
+  const args = parseCliArgs(process.argv.slice(2));
+  const name = args._[0];
+  if (!name) {
+    throw new Error(
+      "Usage: npm run new-skill -- <name> --description \"Use when ...\" --resources references,scripts"
+    );
+  }
+
+  const result = await createSkill({
+    repoDir: path.resolve(args.repo || "."),
+    name,
+    description: args.description,
+    resources: parseResourceList(args.resources),
+    force: Boolean(args.force)
+  });
+  console.log(`Created skill ${result.name} at ${result.path}`);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] || "").href) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/scripts/validate-skills.mjs

@@ -0,0 +1,42 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { listSkillDirs, parseCliArgs, validateSkillDir } from "./lib/skill-utils.mjs";
+
+export async function validateRepository({ repoDir = process.cwd() } = {}) {
+  const skills = await listSkillDirs(repoDir);
+  const validations = await Promise.all(skills.map((skillDir) => validateSkillDir(skillDir)));
+  const errors = validations.flatMap((result) => result.errors);
+
+  return {
+    skills: skills.map((skill) => skill.name),
+    errors
+  };
+}
+
+async function main() {
+  const args = parseCliArgs(process.argv.slice(2));
+  const result = await validateRepository({
+    repoDir: path.resolve(args.repo || ".")
+  });
+
+  if (result.skills.length === 0) {
+    console.log("No skills found under skills/. Repository scaffold is valid.");
+  } else {
+    console.log(`Validated ${result.skills.length} skill(s).`);
+  }
+
+  if (result.errors.length > 0) {
+    for (const error of result.errors) {
+      console.error(`- ${error}`);
+    }
+    process.exitCode = 1;
+  }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] || "").href) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/templates/skill/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: {{name}}
+description: {{description}}
+---
+
+# {{title}}
+
+Use this skill when the request matches the frontmatter description.
+
+## Workflow
+
+1. Read any relevant files in this skill before acting.
+2. Prefer bundled scripts for repeatable operations.
+3. Keep outputs focused on the user's request.