@codenhub/skills 0.0.2

package/src/cli.ts

@@ -0,0 +1,311 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { fileURLToPath } from "url";
+
+interface Skill {
+  id: string;
+  name: string;
+  description: string;
+  path: string;
+}
+
+export function parseFrontmatter(content: string): Record<string, string> {
+  const match = content.match(/^---\r?\n([\s\S]+?)\r?\n---/);
+  const metadata: Record<string, string> = {};
+  if (!match) {
+    return metadata;
+  }
+
+  const lines = match[1].split(/\r?\n/);
+  for (const line of lines) {
+    const colonIndex = line.indexOf(":");
+    if (colonIndex !== -1) {
+      const key = line.slice(0, colonIndex).trim();
+      const value = line.slice(colonIndex + 1).trim();
+      metadata[key] = value;
+    }
+  }
+  return metadata;
+}
+
+export function getSkills(srcDir: string): Skill[] {
+  if (!fs.existsSync(srcDir)) {
+    return [];
+  }
+
+  const items = fs.readdirSync(srcDir);
+  const skills: Skill[] = [];
+
+  for (const item of items) {
+    const itemPath = path.join(srcDir, item);
+    const stat = fs.statSync(itemPath);
+
+    if (stat.isDirectory()) {
+      const skillMdPath = path.join(itemPath, "SKILL.md");
+      if (fs.existsSync(skillMdPath)) {
+        const content = fs.readFileSync(skillMdPath, "utf8");
+        const meta = parseFrontmatter(content);
+        skills.push({
+          id: item,
+          name: meta.name || item,
+          description: meta.description || "",
+          path: itemPath,
+        });
+      }
+    }
+  }
+
+  return skills;
+}
+
+export function copyRecursiveSync(src: string, dest: string, ignoreList: string[] = []): void {
+  const exists = fs.existsSync(src);
+  const stats = exists && fs.statSync(src);
+  const isDirectory = exists && stats && stats.isDirectory();
+
+  if (isDirectory) {
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(dest, { recursive: true });
+    }
+    fs.readdirSync(src).forEach((childItemName) => {
+      if (ignoreList.includes(childItemName)) {
+        return;
+      }
+      copyRecursiveSync(path.join(src, childItemName), path.join(dest, childItemName), ignoreList);
+    });
+  } else {
+    const destDir = path.dirname(dest);
+    if (!fs.existsSync(destDir)) {
+      fs.mkdirSync(destDir, { recursive: true });
+    }
+    fs.copyFileSync(src, dest);
+  }
+}
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Find skills source directory
+let skillsSrcDir = path.resolve(__dirname, "../src");
+if (
+  !fs.existsSync(skillsSrcDir) ||
+  !fs.readdirSync(skillsSrcDir).some((f) => fs.statSync(path.join(skillsSrcDir, f)).isDirectory())
+) {
+  skillsSrcDir = __dirname;
+}
+
+const home = os.homedir();
+
+const HARNESS_MAPPING: Record<string, string> = {
+  "Antigravity Global": path.join(home, ".gemini/config/skills"),
+  "Antigravity Workspace": path.resolve("./.agents/skills"),
+  "OpenCode Global": path.join(home, ".config/opencode/skills"),
+  "OpenCode Workspace": path.resolve("./.opencode/skills"),
+  "Claude Global": path.join(home, ".claude/skills"),
+  "Claude Workspace": path.resolve("./.claude/skills"),
+  "Codex Global": path.join(home, ".codex/skills"),
+  "Codex Workspace": path.resolve("./.codex/skills"),
+};
+
+const ANSI = {
+  HIDE_CURSOR: "\x1b[?25l",
+  SHOW_CURSOR: "\x1b[?25h",
+  CLEAR_LINE: "\x1b[2K",
+  CURSOR_UP: (n: number) => `\x1b[${n}A`,
+  RESET: "\x1b[0m",
+  BOLD: "\x1b[1m",
+  DIM: "\x1b[2m",
+  CYAN: "\x1b[36m",
+  GREEN: "\x1b[32m",
+  RED: "\x1b[31m",
+  BLUE: "\x1b[34m",
+  YELLOW: "\x1b[33m",
+  WHITE: "\x1b[37m",
+};
+
+const CONSTANTS = {
+  CODEX_IDENTIFIER: "Codex",
+  EXCLUDE_FOLDER_AGENTS: "agents",
+};
+
+interface Choice {
+  name: string;
+  value: string;
+  checked: boolean;
+  description?: string;
+}
+
+function checkboxPrompt(message: string, choices: Choice[]): Promise<string[]> {
+  return new Promise((resolve) => {
+    const stdout = process.stdout;
+    if (!process.stdin.isTTY) {
+      resolve(choices.filter((c) => c.checked).map((c) => c.value));
+      return;
+    }
+    let cursor = 0;
+
+    // Hide terminal cursor
+    stdout.write(ANSI.HIDE_CURSOR);
+
+    function render(first = false) {
+      if (!first) {
+        // Move cursor up to overwrite previous render
+        const linesToMove = choices.length + 2;
+        stdout.write(ANSI.CURSOR_UP(linesToMove));
+      }
+
+      // Title/Message
+      stdout.write(`${ANSI.BOLD}${ANSI.CYAN}? ${ANSI.WHITE}${message}${ANSI.RESET}\n`);
+
+      // Choices
+      choices.forEach((choice, index) => {
+        const isCurrent = index === cursor;
+        const pointer = isCurrent ? `${ANSI.CYAN}❯${ANSI.RESET}` : " ";
+        const checkbox = choice.checked ? `${ANSI.GREEN}[◼]${ANSI.RESET}` : "[ ]";
+        const name = isCurrent ? `${ANSI.CYAN}${ANSI.BOLD}${choice.name}${ANSI.RESET}` : choice.name;
+        const desc = choice.description ? ` ${ANSI.DIM}(${choice.description})${ANSI.RESET}` : "";
+
+        stdout.write(`${ANSI.CLEAR_LINE}${pointer} ${checkbox} ${name}${desc}\n`);
+      });
+
+      // Instructions
+      stdout.write(
+        `${ANSI.CLEAR_LINE}${ANSI.DIM}(Use arrows to navigate, Space to toggle, Enter to confirm, Ctrl+C to exit)${ANSI.RESET}\n`,
+      );
+    }
+
+    render(true);
+
+    function onKeypress(_str: string | undefined, key: { ctrl?: boolean; name?: string } | undefined) {
+      if (key && key.ctrl && key.name === "c") {
+        cleanup();
+        stdout.write(`\n${ANSI.RED}Installation cancelled.${ANSI.RESET}\n`);
+        process.exit(0);
+      }
+
+      if (!key) {
+        return;
+      }
+
+      switch (key.name) {
+        case "up":
+          cursor = (cursor - 1 + choices.length) % choices.length;
+          render();
+          break;
+        case "down":
+          cursor = (cursor + 1) % choices.length;
+          render();
+          break;
+        case "space":
+          choices[cursor].checked = !choices[cursor].checked;
+          render();
+          break;
+        case "return":
+          cleanup();
+          const selectedValues = choices.filter((c) => c.checked).map((c) => c.value);
+          stdout.write(`${ANSI.CLEAR_LINE}\r${ANSI.GREEN}✔${ANSI.RESET} Selection confirmed.\n`);
+          resolve(selectedValues);
+          break;
+      }
+    }
+
+    function cleanup() {
+      process.stdin.removeListener("keypress", onKeypress);
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(false);
+      }
+      process.stdin.pause();
+      stdout.write(ANSI.SHOW_CURSOR); // Show cursor
+    }
+
+    // Setup keypress listener
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+
+    const readline = require("readline");
+    readline.emitKeypressEvents(process.stdin);
+
+    process.stdin.on("keypress", onKeypress);
+  });
+}
+
+// Helper to use require safely in ESM
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+
+async function main() {
+  console.log(`\n${ANSI.BOLD}${ANSI.CYAN}=========================================${ANSI.RESET}`);
+  console.log(`${ANSI.BOLD}${ANSI.CYAN}    Codenhub AI Agent Skills Installer${ANSI.RESET}`);
+  console.log(`${ANSI.BOLD}${ANSI.CYAN}=========================================${ANSI.RESET}\n`);
+
+  const skills = getSkills(skillsSrcDir);
+  if (skills.length === 0) {
+    console.error(`${ANSI.RED}Error: No skills found in source directory.${ANSI.RESET}`);
+    process.exit(1);
+  }
+
+  // 1. Prompt for skills selection
+  const skillChoices: Choice[] = skills.map((s) => ({
+    name: s.name,
+    value: s.id,
+    checked: true,
+    description: s.description,
+  }));
+
+  const selectedSkills = await checkboxPrompt("Which skills do you want to install?", skillChoices);
+  if (selectedSkills.length === 0) {
+    console.log(`\n${ANSI.YELLOW}No skills selected. Exiting.${ANSI.RESET}`);
+    process.exit(0);
+  }
+
+  // 2. Prompt for harnesses selection
+  const harnessChoices: Choice[] = Object.keys(HARNESS_MAPPING).map((name) => ({
+    name,
+    value: name,
+    checked: true,
+    description: HARNESS_MAPPING[name],
+  }));
+
+  const selectedHarnesses = await checkboxPrompt("Which harnesses do you want to install to?", harnessChoices);
+  if (selectedHarnesses.length === 0) {
+    console.log(`\n${ANSI.YELLOW}No harnesses selected. Exiting.${ANSI.RESET}`);
+    process.exit(0);
+  }
+
+  console.log(`\n${ANSI.BOLD}Installing skills...${ANSI.RESET}\n`);
+
+  for (const harness of selectedHarnesses) {
+    const destBaseDir = HARNESS_MAPPING[harness];
+    const isCodex = harness.includes(CONSTANTS.CODEX_IDENTIFIER);
+    console.log(`${ANSI.BLUE}→ Installing to ${harness}...${ANSI.RESET}`);
+
+    for (const skillId of selectedSkills) {
+      const skill = skills.find((s) => s.id === skillId);
+      if (!skill) {
+        continue;
+      }
+
+      const destSkillDir = path.join(destBaseDir, skillId);
+      try {
+        copyRecursiveSync(skill.path, destSkillDir, isCodex ? [] : [CONSTANTS.EXCLUDE_FOLDER_AGENTS]);
+        console.log(`  ${ANSI.GREEN}✔${ANSI.RESET} Copied: ${skill.name}`);
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`  ${ANSI.RED}✘${ANSI.RESET} Failed copying ${skill.name}: ${msg}`);
+      }
+    }
+  }
+
+  console.log(`\n${ANSI.GREEN}${ANSI.BOLD}✔ All selected skills successfully installed/updated!${ANSI.RESET}\n`);
+}
+
+if (typeof process !== "undefined" && !process.env.VITEST) {
+  main().catch((err) => {
+    console.error(`${ANSI.RED}Unhandled exception:${ANSI.RESET}`, err);
+    process.exit(1);
+  });
+}

package/src/executing-plans/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: executing-plans
+description: Use when you have a written implementation plan to execute in a separate session with review checkpoints.
+metadata:
+  short-description: Execute implementation plans step by step
+---
+
+# Executing Plans
+
+## Overview
+
+Load the plan, confirm documented approval, review it critically, execute all tasks, and report when complete.
+
+**Announce at start:** "I'm using the executing-plans skill to implement this plan."
+
+Prefer delegated execution via subagents when practical. Use inline execution when subagents are unavailable, the work is too tightly coupled to split cleanly, or the user explicitly prefers inline.
+
+Default git workflow: work on a new branch, make atomic commits as clean milestones land, and open a PR at the end. These are soft defaults; follow repo conventions or explicit user instructions when they differ.
+
+## Tool Compatibility
+
+- Keep instructions tool-agnostic and avoid provider-specific wording.
+- When behavior differs across tools, resolve conflicts in this order: OpenCode > Claude Code > Codex CLI > Gemini CLI.
+
+## The Process
+
+### Step 1: Load and Review Plan
+
+1. Read the plan file and any referenced spec.
+2. Confirm the plan is documented as `Approved`, and confirm the referenced spec is also documented as `Approved`.
+3. If either document is not documented as approved, stop and ask. Only continue without documented approval if the user explicitly tells you to.
+4. Review the plan critically and identify any questions or concerns about it.
+5. If there are concerns, raise them with the human partner before starting.
+6. If there are no concerns, create or update the session plan tracker and proceed.
+7. If you are not already on an appropriate working branch, create a new one before implementation unless the repo or user calls for another approach.
+
+### Step 2: Execute Tasks
+
+For each task:
+
+1. Prefer dispatching a fresh subagent with task-local context when practical.
+2. Mark it as `in_progress`.
+3. Follow each step exactly, whether delegated or inline. The plan should already contain bite-sized steps.
+4. Review the resulting artifacts and run verifications as specified.
+5. Make an atomic commit when the task or another clean milestone is complete, if the workflow allows it.
+6. Mark it as completed.
+
+### Step 3: Complete Development
+
+After all tasks are complete and verified:
+
+- Run the final verification the plan requires.
+- Summarize what changed, what was verified, and any open issues.
+- Suggest updating the relevant spec and plan docs to reflect the completed work.
+- If the user wants you to make those doc updates, do them explicitly. Never assume approval or completion status on your own.
+- If the usual git workflow applies, make sure the work stays on its branch and open a PR before closing out.
+
+## When to Stop and Ask for Help
+
+**STOP executing immediately when:**
+
+- You hit a blocker: missing dependency, test fails, instruction unclear.
+- The plan has critical gaps preventing a safe start.
+- You do not understand an instruction.
+- Verification fails repeatedly.
+
+Ask for clarification rather than guessing.
+
+## When to Revisit Earlier Steps
+
+**Return to Review (Step 1) when:**
+
+- The partner updates the plan based on your feedback.
+- The fundamental approach needs rethinking.
+
+Do not force through blockers. Stop and ask.
+
+## Remember
+
+- Review the plan critically first.
+- Check documented approval before starting implementation.
+- Follow plan steps exactly.
+- Do not skip verifications.
+- Stop when blocked, do not guess.
+- Never start implementation on `main` or `master` without explicit user consent.
+
+## Integration
+
+Related workflow skills:
+
+- `writing-plans` - creates the plan this skill executes
+- `subagent-specialist` - preferred when subagent-based or parallel execution fits the plan

package/src/executing-plans/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Executing Plans"
+  short_description: "Execute written plans with review checkpoints"
+  default_prompt: "Use $executing-plans to load the plan, confirm the plan and spec are documented as approved before execution unless the user explicitly says otherwise, prefer subagent-based execution, work on a new branch with atomic commits, open a PR at the end when appropriate, and suggest doc status updates when finished."

package/src/frontend-design/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
+---
+
+This skill guides the coding agent in creating distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Tool Compatibility
+
+- Keep instructions tool-agnostic and avoid provider-specific wording.
+- When behavior differs across tools, resolve conflicts in this order: OpenCode > Claude Code > Codex CLI > Gemini CLI.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+## Execution Guidance
+
+When applying this skill:
+
+- Build the requested interface directly instead of stopping at ideas or mock descriptions.
+- Preserve the existing design system, component patterns, and frontend architecture when working inside an established codebase.
+- Use the strongest visual direction that still fits the product and the repository's technical constraints.
+- Refine the result for both desktop and mobile instead of treating responsiveness as a follow-up.
+- Prefer modern, production-ready framework patterns already present in the codebase instead of introducing novelty for its own sake.
+- Push toward concrete design decisions, polished implementation details, and cohesive execution rather than generic safe choices.
+
+Remember: strong creative results come from a clear aesthetic direction and enough room to execute it with conviction. Do not hold back; think outside the box and commit fully to a distinctive vision.

package/src/frontend-design/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Frontend Design"
+  short_description: "Build distinctive frontend interfaces"
+  default_prompt: "Use $frontend-design to build a distinctive production-grade frontend interface."