@gethmy/mcp 2.1.0 → 2.1.2

package/src/tui/docs.ts

@@ -1,10 +1,5 @@
-import {
-  existsSync,
-  readFileSync,
-  readdirSync,
-  statSync,
-} from "node:fs";
-import { join } from "node:path";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, resolve, sep } from "node:path";
 import * as p from "@clack/prompts";
 import { colors, symbols } from "./theme.js";
 
@@ -182,8 +177,12 @@ export function scanProject(cwd: string): ProjectInfo {
   let framework: string | null = null;
   if (pkg) {
     const deps: Record<string, string> = {
-      ...(typeof pkg.dependencies === "object" ? (pkg.dependencies as Record<string, string>) : {}),
-      ...(typeof pkg.devDependencies === "object" ? (pkg.devDependencies as Record<string, string>) : {}),
+      ...(typeof pkg.dependencies === "object"
+        ? (pkg.dependencies as Record<string, string>)
+        : {}),
+      ...(typeof pkg.devDependencies === "object"
+        ? (pkg.devDependencies as Record<string, string>)
+        : {}),
     };
 
     if (deps.next) {
@@ -347,7 +346,12 @@ function describeScript(name: string): string {
  * Generate a scaffold AGENTS.md from project metadata.
  */
 export function generateAgentsMd(info: ProjectInfo, _cwd: string): string {
-  const lang = info.language === "typescript" ? "TypeScript" : info.language === "javascript" ? "JavaScript" : info.language;
+  const lang =
+    info.language === "typescript"
+      ? "TypeScript"
+      : info.language === "javascript"
+        ? "JavaScript"
+        : info.language;
   const frameworkLabel = info.framework ? `${info.framework} ` : "";
   const monoLabel = info.monorepo ? " (monorepo)" : "";
 
@@ -388,7 +392,8 @@ export function generateAgentsMd(info: ProjectInfo, _cwd: string): string {
   lines.push("## Code Standards");
   lines.push("");
 
-  const langLabel = info.language === "typescript" ? "TypeScript" : "JavaScript";
+  const langLabel =
+    info.language === "typescript" ? "TypeScript" : "JavaScript";
   if (info.language === "typescript" || info.language === "javascript") {
     lines.push(`- ${langLabel} with ES modules`);
   }
@@ -442,7 +447,10 @@ export function generateClaudeMd(info: ProjectInfo): string {
 /**
  * Generate an architecture.md scaffold.
  */
-export function generateArchitectureMd(info: ProjectInfo, _cwd: string): string {
+export function generateArchitectureMd(
+  info: ProjectInfo,
+  _cwd: string,
+): string {
   const lines: string[] = [];
   lines.push("# Architecture");
   lines.push("");
@@ -468,20 +476,74 @@ export function generateArchitectureMd(info: ProjectInfo, _cwd: string): string
 
 // ── Verification ────────────────────────────────────────────────────────────
 
+/** Vague phrases that provide no actionable guidance to agents. */
+const VAGUE_STANDARDS = [
+  "follow best practices",
+  "use best practices",
+  "keep it clean",
+  "write clean code",
+  "maintain code quality",
+  "ensure quality",
+  "use proper naming",
+  "follow conventions",
+  "be consistent",
+];
+
 /**
- * Verify existing docs for broken references, stale commands, and dead paths.
+ * Verify existing docs for broken references, stale commands, dead paths,
+ * and structural quality issues from the setup-agent-docs quality checks.
  */
 export function verifyDocs(cwd: string): DocsIssue[] {
   const issues: DocsIssue[] = [];
 
-  // 1. CLAUDE.md — check @-references
   const claudeMd = readText(join(cwd, "CLAUDE.md"));
+  const agentsMd = readText(join(cwd, "AGENTS.md"));
+  const pkg = readJson(join(cwd, "package.json"));
+  const pkgScripts =
+    pkg && typeof pkg.scripts === "object" && pkg.scripts !== null
+      ? (pkg.scripts as Record<string, string>)
+      : {};
+
+  // ── CLAUDE.md checks ──────────────────────────────────────────────────
+
+  const projectRoot = resolve(cwd);
+
   if (claudeMd) {
+    // Check @-references exist on disk (with path traversal protection)
+    const importedFiles: { ref: string; resolved: string }[] = [];
     for (const line of claudeMd.split("\n")) {
       const match = line.match(/^@(.+)$/);
       if (match) {
         const refPath = match[1].trim();
-        if (!existsSync(join(cwd, refPath))) {
+
+        // Reject absolute paths
+        if (isAbsolute(refPath)) {
+          issues.push({
+            severity: "error",
+            file: "CLAUDE.md",
+            message: `@ reference uses an absolute path: ${refPath}`,
+            fix: "Use a project-relative path under the repository root",
+          });
+          continue;
+        }
+
+        // Resolve and ensure the path stays inside the project root
+        const resolvedPath = resolve(projectRoot, refPath);
+        if (
+          resolvedPath !== projectRoot &&
+          !resolvedPath.startsWith(projectRoot + sep)
+        ) {
+          issues.push({
+            severity: "error",
+            file: "CLAUDE.md",
+            message: `@ reference escapes project root: ${refPath}`,
+            fix: "Remove traversal segments (../) and keep references inside the repo",
+          });
+          continue;
+        }
+
+        importedFiles.push({ ref: refPath, resolved: resolvedPath });
+        if (!existsSync(resolvedPath)) {
           issues.push({
             severity: "error",
             file: "CLAUDE.md",
@@ -491,28 +553,99 @@ export function verifyDocs(cwd: string): DocsIssue[] {
         }
       }
     }
+
+    // Line count — CLAUDE.md should be under 100 lines (lean, @imports only)
+    const claudeLines = claudeMd.split("\n").length;
+    if (claudeLines > 100) {
+      issues.push({
+        severity: "warning",
+        file: "CLAUDE.md",
+        message: `CLAUDE.md is ${claudeLines} lines (recommended: under 100)`,
+        fix: "Move detailed content to AGENTS.md or docs/ files and use @imports",
+      });
+    }
+
+    // Duplication — check if CLAUDE.md duplicates content from imported files
+    if (importedFiles.length > 0) {
+      const claudeHeadings = extractHeadings(claudeMd);
+      for (const { ref: refPath, resolved: resolvedPath } of importedFiles) {
+        const refContent = readText(resolvedPath);
+        if (!refContent) continue;
+        const refHeadings = extractHeadings(refContent);
+        // Flag if CLAUDE.md repeats section headings from imported files
+        for (const heading of claudeHeadings) {
+          if (refHeadings.has(heading)) {
+            issues.push({
+              severity: "warning",
+              file: "CLAUDE.md",
+              message: `Section "${heading}" duplicates content from @${refPath}`,
+              fix: `Remove the "${heading}" section — it's already included via @import`,
+            });
+          }
+        }
+      }
+    }
   }
 
-  // 2. AGENTS.md — check commands against package.json scripts
-  const agentsMd = readText(join(cwd, "AGENTS.md"));
-  const pkg = readJson(join(cwd, "package.json"));
-  const pkgScripts = pkg && typeof pkg.scripts === "object" && pkg.scripts !== null
-    ? (pkg.scripts as Record<string, string>)
-    : {};
+  // ── AGENTS.md checks ──────────────────────────────────────────────────
 
   if (agentsMd) {
-    // Extract commands from code blocks
+    // Project Context — first non-heading, non-blank line should be exactly one line
+    const agentsLines = agentsMd.split("\n");
+    const contextLines: string[] = [];
+    let pastFirstHeading = false;
+    let hitNextSection = false;
+    for (const line of agentsLines) {
+      if (!pastFirstHeading) {
+        if (line.startsWith("# ")) {
+          pastFirstHeading = true;
+        }
+        continue;
+      }
+      // Stop at next ## heading
+      if (line.startsWith("## ")) {
+        hitNextSection = true;
+        break;
+      }
+      const trimmed = line.trim();
+      if (trimmed) contextLines.push(trimmed);
+    }
+
+    if (pastFirstHeading && !hitNextSection && contextLines.length === 0) {
+      issues.push({
+        severity: "warning",
+        file: "AGENTS.md",
+        message: "Missing project context line after the title heading",
+        fix: "Add a single-line description: stack + what the project does",
+      });
+    } else if (contextLines.length > 1) {
+      issues.push({
+        severity: "warning",
+        file: "AGENTS.md",
+        message: `Project context should be exactly 1 line, found ${contextLines.length}`,
+        fix: "Condense to a single line: stack + what the project does",
+      });
+    }
+
+    // Commands — check against package.json scripts
     const codeBlockRe = /```[\s\S]*?```/g;
     let blockMatch: RegExpExecArray | null;
     while ((blockMatch = codeBlockRe.exec(agentsMd)) !== null) {
       const block = blockMatch[0];
-      // Match lines that look like package manager commands
       const cmdRe = /(?:bun|npm|pnpm|yarn)\s+(?:run\s+)?(\S+)/g;
       let cmdMatch: RegExpExecArray | null;
       while ((cmdMatch = cmdRe.exec(block)) !== null) {
         const scriptName = cmdMatch[1];
-        // Skip if the script name is a built-in (install, init, etc.)
-        const builtins = new Set(["install", "init", "create", "exec", "dlx", "x", "test", "start"]);
+        const builtins = new Set([
+          "install",
+          "init",
+          "create",
+          "exec",
+          "dlx",
+          "x",
+          "test",
+          "start",
+        ]);
         if (builtins.has(scriptName)) continue;
         if (Object.keys(pkgScripts).length > 0 && !(scriptName in pkgScripts)) {
           issues.push({
@@ -525,11 +658,47 @@ export function verifyDocs(cwd: string): DocsIssue[] {
       }
     }
 
-    // 3. Check backtick-quoted paths in AGENTS.md
+    // Code Standards — flag vague, non-actionable phrases
+    const standardsSection = extractSection(agentsMd, "Code Standards");
+    if (standardsSection) {
+      const lower = standardsSection.toLowerCase();
+      for (const phrase of VAGUE_STANDARDS) {
+        if (lower.includes(phrase)) {
+          issues.push({
+            severity: "warning",
+            file: "AGENTS.md",
+            message: `Code Standards contains vague phrase: "${phrase}"`,
+            fix: "Replace with specific, verifiable conventions derived from config files",
+          });
+        }
+      }
+    }
+
+    // Missing test command — if no test script exists, AGENTS.md should say so
+    if (Object.keys(pkgScripts).length > 0) {
+      const hasTestScript = Object.keys(pkgScripts).some(
+        (k) => k === "test" || k.startsWith("test:"),
+      );
+      if (!hasTestScript) {
+        const mentionsNoTest = agentsMd.toLowerCase().includes("no test");
+        if (!mentionsNoTest) {
+          issues.push({
+            severity: "warning",
+            file: "AGENTS.md",
+            message:
+              "No test script in package.json and AGENTS.md doesn't mention it",
+            fix: 'Add a note like "No test framework. Verify changes with `bun run build`."',
+          });
+        }
+      }
+    }
+
+    // Check backtick-quoted paths
     checkBacktickPaths(agentsMd, "AGENTS.md", cwd, issues);
   }
 
-  // 3b. Check backtick-quoted paths in docs/architecture.md
+  // ── docs/architecture.md checks ───────────────────────────────────────
+
   const archMd = readText(join(cwd, "docs", "architecture.md"));
   if (archMd) {
     checkBacktickPaths(archMd, "docs/architecture.md", cwd, issues);
@@ -538,6 +707,44 @@ export function verifyDocs(cwd: string): DocsIssue[] {
   return issues;
 }
 
+/** Extract ## headings from markdown content. */
+function extractHeadings(content: string): Set<string> {
+  const headings = new Set<string>();
+  for (const line of content.split("\n")) {
+    const match = line.match(/^#{2,3}\s+(.+)$/);
+    if (match) {
+      headings.add(match[1].trim());
+    }
+  }
+  return headings;
+}
+
+/** Extract content under a specific ## section heading. */
+function extractSection(content: string, heading: string): string | null {
+  const lines = content.split("\n");
+  let capturing = false;
+  const result: string[] = [];
+
+  for (const line of lines) {
+    if (capturing) {
+      // Stop at next ## heading
+      if (line.match(/^#{1,2}\s/)) break;
+      result.push(line);
+    } else if (
+      line.match(
+        new RegExp(
+          `^##\\s+${heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`,
+          "i",
+        ),
+      )
+    ) {
+      capturing = true;
+    }
+  }
+
+  return result.length > 0 ? result.join("\n") : null;
+}
+
 /** Scan markdown for backtick-quoted paths and check they exist. */
 function checkBacktickPaths(
   content: string,
@@ -549,12 +756,18 @@ function checkBacktickPaths(
   let match: RegExpExecArray | null;
   const checked = new Set<string>();
 
+  const root = resolve(cwd);
+
   while ((match = pathRe.exec(content)) !== null) {
     const refPath = match[1].replace(/\/$/, ""); // strip trailing slash
     if (checked.has(refPath)) continue;
     checked.add(refPath);
 
-    if (!existsSync(join(cwd, refPath))) {
+    // Skip paths that escape the project root (e.g. src/../../etc/hosts)
+    const resolvedRef = resolve(root, refPath);
+    if (resolvedRef !== root && !resolvedRef.startsWith(root + sep)) continue;
+
+    if (!existsSync(resolvedRef)) {
       issues.push({
         severity: "warning",
         file,

package/src/tui/setup.ts

@@ -17,6 +17,7 @@ import {
   loadConfig,
   saveLocalConfig,
 } from "../config.js";
+import { buildSkillFile, HARMONY_WORKFLOW_PROMPT } from "../skills.js";
 import { type AgentId, detectAgents } from "./agents.js";
 import { runDocsStep } from "./docs.js";
 import { colors, formatPath, messages } from "./theme.js";
@@ -42,298 +43,6 @@ const GLOBAL_SKILLS_DIR = join(homedir(), ".agents", "skills");
 // API base URL
 const API_URL = "https://gethmy.com/api";
 
-// Harmony workflow prompt - shared across agents
-const HARMONY_WORKFLOW_PROMPT = `# Harmony Card Workflow
-
-Start work on a Harmony card. Card reference: $ARGUMENTS
-
-## 1. Find & Fetch Card
-
-Parse the reference and fetch the card:
-- \`#42\` or \`42\` → \`harmony_get_card_by_short_id\` with \`shortId: 42\`
-- UUID → \`harmony_get_card\` with \`cardId\`
-- Name/text → \`harmony_search_cards\` with \`query\`
-
-## 2. Get Board State
-
-Call \`harmony_get_board\` to get columns and labels. From the response:
-- Find the "In Progress" (or "Progress") column ID
-- Find the "agent" label ID
-
-## 3. Setup Card for Work
-
-Execute these in sequence:
-1. \`harmony_move_card\` → Move to "In Progress" column
-2. \`harmony_add_label_to_card\` → Add "agent" label
-3. \`harmony_start_agent_session\`:
-   - \`cardId\`: Card UUID
-   - \`agentIdentifier\`: Your agent identifier
-   - \`agentName\`: Your agent name
-   - \`currentTask\`: "Analyzing card requirements"
-
-## 4. Generate Work Prompt
-
-Call \`harmony_generate_prompt\` with:
-- \`cardId\` or \`shortId\` (+ \`projectId\` if using shortId)
-- \`variant\`: Select based on task:
-  - \`"execute"\` (default) → Clear tasks, bug fixes, well-defined work
-  - \`"analysis"\` → Complex features, unclear requirements
-  - \`"draft"\` → Medium complexity, want feedback first
-
-The generated prompt provides role framing, focus areas, subtasks, linked cards, and suggested outputs.
-
-## 5. Display Card Summary
-
-Show the user: Card title, short ID, role, priority, labels, due date, description, and subtasks.
-
-## 6. Implement Solution
-
-Work on the card following the generated prompt's guidance. Update progress at milestones:
-- \`harmony_update_agent_progress\` with \`progressPercent\` (0-100), \`currentTask\`, \`status\`, \`blockers\`
-
-**Progress checkpoints:** 20% (exploration), 50% (implementation), 80% (testing), 100% (done)
-
-## 7. Complete Work
-
-When finished:
-1. \`harmony_end_agent_session\` with \`status: "completed"\`, \`progressPercent: 100\`
-2. \`harmony_move_card\` to "Review" column
-3. Summarize accomplishments
-
-If pausing: \`harmony_end_agent_session\` with \`status: "paused"\`
-
-## Key Tools Reference
-
-**Cards:** \`harmony_get_card\`, \`harmony_get_card_by_short_id\`, \`harmony_search_cards\`, \`harmony_create_card\`, \`harmony_update_card\`, \`harmony_move_card\`, \`harmony_delete_card\`, \`harmony_assign_card\`
-
-**Subtasks:** \`harmony_create_subtask\`, \`harmony_toggle_subtask\`, \`harmony_delete_subtask\`
-
-**Labels:** \`harmony_add_label_to_card\`, \`harmony_remove_label_from_card\`, \`harmony_create_label\`
-
-**Links:** \`harmony_add_link_to_card\`, \`harmony_remove_link_from_card\`, \`harmony_get_card_links\`
-
-**Board:** \`harmony_get_board\`, \`harmony_list_projects\`, \`harmony_get_context\`, \`harmony_set_project_context\`
-
-**Sessions:** \`harmony_start_agent_session\`, \`harmony_update_agent_progress\`, \`harmony_end_agent_session\`, \`harmony_get_agent_session\`
-
-**AI:** \`harmony_generate_prompt\`, \`harmony_process_command\`
-`;
-
-// Harmony plan prompt - unified plan creation and execution workflow
-const HARMONY_PLAN_PROMPT = `# Harmony Plan Workflow
-
-Create a new plan or work on an existing one. Argument: $ARGUMENTS
-
-## Step 1 — Detect Intent
-
-Parse \`$ARGUMENTS\` to determine the workflow:
-
-- **UUID** (contains dashes, 36 chars) → call \`harmony_get_plan\` with \`planId\` directly → **Step 2A**
-- **\`#N\`** (short ID) → call \`harmony_get_card_by_short_id\` to get the card, then \`harmony_get_plan\` with \`cardId\` → **Step 2A**
-- **Text** (anything else) → call \`harmony_list_plans\` with \`search\` set to the text
-  - If **one match** → use it → **Step 2A**
-  - If **multiple matches** → list them with title, status, phase, and updated date. Ask the user to pick one using \`AskUserQuestion\` → **Step 2A**
-  - If **no matches** → ask user: "No existing plans found for '$ARGUMENTS'. Would you like to create a new plan on this topic?" → **Step 2B**
-- **Empty / vague topic** → **Step 2B** (create new plan)
-
----
-
-## Step 2A — Work on Existing Plan
-
-### 2A.1 — Analyze & Display
-
-Once you have the plan ID, call \`harmony_get_plan\` to fetch the full plan with tasks. Show a structured summary:
-
-\\\`\\\`\\\`
-## [Plan Title]
-**Status:** draft/active/archived | **Phase:** plan/execute/verify/done
-**Tasks:** N total (X pending, Y in_progress, Z completed)
-**URL:** https://gethmy.com/plans/{id}
-\\\`\\\`\\\`
-
-If plan is in execute phase and tasks already have linked cards, note which tasks have cards and which don't.
-
-### 2A.2 — Recall Context
-
-Call \`harmony_memory_search\` with the plan title to find related knowledge, patterns, or decisions that may inform execution.
-
-### 2A.3 — Present Options
-
-Use \`AskUserQuestion\` to offer execution choices. Adapt options based on plan state:
-
-#### Default options (plan in \`plan\` phase):
-
-**(A) Single card** — Create one card with plan summary + link to plan. Best for simple plans.
-**(B) Multiple cards** — Create one card per task via \`harmony_advance_plan\`. Best for complex plans with independent tasks.
-**(C) Analyze only** — Review the plan and design an implementation approach. Create cards later.
-**(D) Skip** — Do nothing.
-
-#### If plan has no tasks:
-Only offer **(A) Single card**, **(C) Analyze only**, or **(D) Skip**.
-
-#### If plan is already in \`execute\` phase with existing cards:
-**(A) Work on existing cards** — List cards with short IDs, suggest \`/hmy #N\` to start
-**(B) Create cards for remaining tasks** — Only create cards for tasks without linked cards
-**(C) Analyze progress** — Review what's done vs remaining
-**(D) Skip**
-
-### 2A.4 — Execute Choice
-
-#### Option A — Single card
-1. Call \`harmony_create_card\` with:
-   - \`title\`: Plan title
-   - \`description\`: Brief 2-3 sentence summary of the plan + \`\\n\\n[View plan](https://gethmy.com/plans/{planId})\`
-   - \`priority\`: based on plan task priorities (use highest)
-2. Call \`harmony_update_plan\` to set \`status: "active"\`, \`workflowPhase: "execute"\`
-
-#### Option B — Multiple cards (advance plan)
-1. Call \`harmony_advance_plan\` with:
-   - \`planId\`: the plan ID
-   - \`phase\`: \`"execute"\`
-   - \`summary\`: Brief summary of the plan scope
-2. Display the created cards with their short IDs
-
-#### Option C — Analyze only
-1. Present a structured implementation analysis:
-   - Suggested order of tasks
-   - Dependencies between tasks
-   - Key technical considerations from memory search
-   - Estimated complexity
-2. Suggest creating cards when ready
-
-#### Option D — Skip
-Acknowledge and stop.
-
-### 2A.5 — Summary
-
-After execution, show:
-- Created card(s) with short IDs
-- Current plan phase
-- Suggest next step: \`/hmy #N\` to start working on a card
-
----
-
-## Step 2B — Create New Plan
-
-### 2B.1 — Context Gathering
-
-Before interviewing, gather existing context:
-
-1. Call \`harmony_get_board\` for board state (columns, cards, labels)
-2. Call \`harmony_recall\` with relevant tags to find existing knowledge on the topic
-3. Call \`harmony_memory_search\` with the topic to find related patterns/decisions/lessons
-
-Note what you learn — reference it during the interview to ask smarter questions.
-
-### 2B.2 — Structured Interview (3-5 questions)
-
-Interview the user with **3-5 focused questions** using AskUserQuestion. Adapt based on complexity.
-
-#### Core Questions
-1. **Problem & Audience**: What problem are we solving? Who benefits?
-2. **Scope**: What's in v1, what's deferred?
-3. **Technical Constraints**: Any technical preferences, constraints, or existing patterns to follow?
-
-#### Adaptive Follow-ups (if needed)
-- Key user flows or interactions?
-- Integration points with existing systems?
-- Performance, security, or accessibility requirements?
-
-#### Interview Rules
-- Reference what you found in Step 2B.1 (board state, memories) to ask informed questions
-- Skip questions that aren't relevant — simple features need fewer questions
-- Tell the user when you have enough information to draft
-
-### 2B.3 — Plan Document
-
-Create a structured markdown document:
-
-\\\`\\\`\\\`markdown
-# [Title]
-
-## Problem
-[What problem we're solving and why]
-
-## Scope
-
-### In Scope
-- [Feature/capability 1]
-- [Feature/capability 2]
-
-### Out of Scope
-- [Deferred items]
-
-## Approach
-[Technical design, architecture decisions, key patterns]
-
-### Key Decisions
-| Decision | Choice | Rationale |
-|----------|--------|-----------|
-| ... | ... | ... |
-
-## Tasks
-1. **[Task title]** — priority: high
-   [Brief description]
-
-2. **[Task title]** — priority: medium
-   [Brief description]
-
-[Continue for all tasks...]
-
-## Risks & Mitigations
-| Risk | Mitigation |
-|------|------------|
-| ... | ... |
-
-## Success Criteria
-- [ ] [Measurable criterion]
-\\\`\\\`\\\`
-
-### 2B.4 — Create Plan
-
-Call \`harmony_create_plan\` with:
-- \`title\`: The plan title
-- \`content\`: Full markdown document from Step 2B.3
-- \`source\`: \`"agent"\`
-- \`workflowPhase\`: \`"plan"\`
-- \`tasks\`: Array of tasks from the Tasks section, each with:
-  - \`content\`: Task title + brief description
-  - \`priority\`: \`"high"\`, \`"medium"\`, or \`"low"\`
-  - \`status\`: \`"pending"\`
-
-### 2B.5 — User Approval
-
-Show the user:
-- Plan URL: \`https://gethmy.com/plans/{id}\`
-- Number of tasks created
-- Brief summary
-
-Then ask: **"Ready to execute? I'll create board cards from these tasks and start the execution phase."**
-
-Options:
-1. **Yes, advance to Execute** — proceed to Step 2B.6
-2. **Let me review first** — end here, they can advance later from the UI
-3. **Make changes** — iterate on the plan
-
-### 2B.6 — Advance to Execute
-
-Call \`harmony_advance_plan\` with:
-- \`planId\`: The plan ID from Step 2B.4
-- \`phase\`: \`"execute"\`
-- \`summary\`: A 2-3 sentence summary of the key decisions made during planning
-
-Report the result:
-- "Created N cards in 'To Do'. Use \`/hmy #<id>\` to start working on any card."
-- List the created cards with their short IDs
-
-## Key Tools Reference
-
-**Discovery:** \`harmony_list_plans\`, \`harmony_get_plan\`, \`harmony_get_card_by_short_id\`
-**Context:** \`harmony_get_board\`, \`harmony_recall\`, \`harmony_memory_search\`
-**Planning:** \`harmony_create_plan\`, \`harmony_advance_plan\`, \`harmony_update_plan\`
-**Execution:** \`harmony_create_card\`, \`harmony_update_card\`
-`;
-
 /**
  * Register MCP server using Claude CLI
  * Returns true if successful, false if CLI unavailable or failed
@@ -521,25 +230,9 @@ function getAgentFiles(
 
   switch (agentId) {
     case "claude": {
-      // Claude Code skill file
-      const skillContent = `---
-name: hmy
-description: Start working on a Harmony card. Use when given a card reference like #42, UUID, or card name to implement.
-argument-hint: <card-reference>
----
-
-${HARMONY_WORKFLOW_PROMPT.replace("Your agent identifier", "claude-code").replace("Your agent name", "Claude Code")}
-`;
-
-      // hmy-plan skill file (unified plan creation + execution)
-      const planSkillContent = `---
-name: hmy-plan
-description: Create a new plan or work on an existing one. Use when asked to plan a feature, execute a plan, review a plan, or given a plan reference.
-argument-hint: [plan name, ID, or topic to plan]
----
-
-${HARMONY_PLAN_PROMPT.replace("$ARGUMENTS", "$ARGUMENTS")}
-`;
+      // Claude Code skill files built from the central skill registry
+      const skillContent = buildSkillFile("hmy", "claude");
+      const planSkillContent = buildSkillFile("hmy-plan", "claude");
 
       if (installMode === "global") {
         // Global mode: Write skills to ~/.agents/skills/, symlink directories to ~/.claude/skills/