opencode-swarm-plugin 0.12.20 → 0.12.22

package/scripts/init-skill.ts

@@ -0,0 +1,222 @@
+#!/usr/bin/env bun
+/**
+ * Skill Initializer - Creates a new skill from template
+ *
+ * Usage:
+ *   bun scripts/init-skill.ts <skill-name> [--path <path>] [--global]
+ *
+ * Examples:
+ *   bun scripts/init-skill.ts my-skill
+ *   bun scripts/init-skill.ts my-skill --path .claude/skills
+ *   bun scripts/init-skill.ts my-skill --global
+ */
+
+import { mkdir, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import { join } from "path";
+import { parseArgs } from "util";
+
+const SKILL_TEMPLATE = (name: string, title: string) => `---
+name: ${name}
+description: [TODO: Complete description of what this skill does and WHEN to use it. Be specific about scenarios that trigger this skill.]
+tags:
+  - [TODO: add tags]
+---
+
+# ${title}
+
+## Overview
+
+[TODO: 1-2 sentences explaining what this skill enables]
+
+## When to Use This Skill
+
+[TODO: List specific scenarios when this skill should be activated:
+- When working on X type of task
+- When files matching Y pattern are involved
+- When the user asks about Z topic]
+
+## Instructions
+
+[TODO: Add actionable instructions for the agent. Use imperative form:
+- "Read the configuration file first"
+- "Check for existing patterns before creating new ones"
+- "Always validate output before completing"]
+
+## Examples
+
+### Example 1: [TODO: Realistic scenario]
+
+**User**: "[TODO: Example user request]"
+
+**Process**:
+1. [TODO: Step-by-step process]
+2. [TODO: Next step]
+3. [TODO: Final step]
+
+## Resources
+
+This skill may include additional resources:
+
+### scripts/
+Executable scripts for automation. Run with \`skills_execute\`.
+
+### references/
+Documentation loaded on-demand. Access with \`skills_read\`.
+
+---
+*Delete any unused sections and this line when skill is complete.*
+`;
+
+const EXAMPLE_SCRIPT = (name: string) => `#!/usr/bin/env bash
+# Example helper script for ${name}
+#
+# This is a placeholder. Replace with actual implementation or delete.
+#
+# Usage: skills_execute(skill: "${name}", script: "example.sh")
+
+echo "Hello from ${name} skill!"
+echo "Project directory: $1"
+
+# TODO: Add actual script logic
+`;
+
+const REFERENCE_TEMPLATE = (title: string) => `# Reference Documentation for ${title}
+
+## Overview
+
+[TODO: Detailed reference material for this skill]
+
+## API Reference
+
+[TODO: If applicable, document APIs, schemas, or interfaces]
+
+## Detailed Workflows
+
+[TODO: Complex multi-step workflows that don't fit in SKILL.md]
+
+## Troubleshooting
+
+[TODO: Common issues and solutions]
+`;
+
+function titleCase(name: string): string {
+  return name
+    .split("-")
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+}
+
+async function initSkill(
+  name: string,
+  basePath: string,
+  isGlobal: boolean
+): Promise<void> {
+  // Validate name
+  if (!/^[a-z0-9-]+$/.test(name)) {
+    console.error("❌ Error: Skill name must be lowercase with hyphens only");
+    process.exit(1);
+  }
+
+  if (name.length > 64) {
+    console.error("❌ Error: Skill name must be 64 characters or less");
+    process.exit(1);
+  }
+
+  // Determine target directory
+  let skillDir: string;
+  if (isGlobal) {
+    const home = process.env.HOME || process.env.USERPROFILE || "~";
+    skillDir = join(home, ".config", "opencode", "skills", name);
+  } else {
+    skillDir = join(basePath, name);
+  }
+
+  // Check if exists
+  if (existsSync(skillDir)) {
+    console.error(`❌ Error: Skill directory already exists: ${skillDir}`);
+    process.exit(1);
+  }
+
+  const title = titleCase(name);
+  const createdFiles: string[] = [];
+
+  try {
+    // Create skill directory
+    await mkdir(skillDir, { recursive: true });
+    console.log(`✅ Created skill directory: ${skillDir}`);
+
+    // Create SKILL.md
+    const skillPath = join(skillDir, "SKILL.md");
+    await writeFile(skillPath, SKILL_TEMPLATE(name, title));
+    createdFiles.push("SKILL.md");
+    console.log("✅ Created SKILL.md");
+
+    // Create scripts/ directory with example
+    const scriptsDir = join(skillDir, "scripts");
+    await mkdir(scriptsDir, { recursive: true });
+    const scriptPath = join(scriptsDir, "example.sh");
+    await writeFile(scriptPath, EXAMPLE_SCRIPT(name), { mode: 0o755 });
+    createdFiles.push("scripts/example.sh");
+    console.log("✅ Created scripts/example.sh");
+
+    // Create references/ directory with example
+    const refsDir = join(skillDir, "references");
+    await mkdir(refsDir, { recursive: true });
+    const refPath = join(refsDir, "guide.md");
+    await writeFile(refPath, REFERENCE_TEMPLATE(title));
+    createdFiles.push("references/guide.md");
+    console.log("✅ Created references/guide.md");
+
+    console.log(`\n✅ Skill '${name}' initialized successfully at ${skillDir}`);
+    console.log("\nNext steps:");
+    console.log("  1. Edit SKILL.md to complete TODO placeholders");
+    console.log("  2. Update the description in frontmatter");
+    console.log("  3. Add specific 'When to Use' scenarios");
+    console.log("  4. Delete unused sections and placeholder files");
+    console.log("  5. Test with skills_use to verify it works");
+  } catch (error) {
+    console.error(
+      `❌ Error: ${error instanceof Error ? error.message : String(error)}`
+    );
+    process.exit(1);
+  }
+}
+
+// Parse arguments
+const { values, positionals } = parseArgs({
+  args: process.argv.slice(2),
+  options: {
+    path: { type: "string", default: ".opencode/skills" },
+    global: { type: "boolean", default: false },
+    help: { type: "boolean", short: "h", default: false },
+  },
+  allowPositionals: true,
+});
+
+if (values.help || positionals.length === 0) {
+  console.log(`
+Skill Initializer - Creates a new skill from template
+
+Usage:
+  bun scripts/init-skill.ts <skill-name> [options]
+
+Options:
+  --path <path>   Directory to create skill in (default: .opencode/skills)
+  --global        Create in global ~/.config/opencode/skills directory
+  -h, --help      Show this help message
+
+Examples:
+  bun scripts/init-skill.ts my-skill
+  bun scripts/init-skill.ts my-skill --path .claude/skills
+  bun scripts/init-skill.ts my-skill --global
+
+Skill name requirements:
+  - Lowercase letters, digits, and hyphens only
+  - Max 64 characters
+`);
+  process.exit(values.help ? 0 : 1);
+}
+
+const skillName = positionals[0];
+await initSkill(skillName, values.path!, values.global!);

package/scripts/validate-skill.ts

@@ -0,0 +1,204 @@
+#!/usr/bin/env bun
+/**
+ * Skill Validator - Validates skill structure and content
+ *
+ * Usage:
+ *   bun scripts/validate-skill.ts <path/to/skill>
+ *
+ * Examples:
+ *   bun scripts/validate-skill.ts .opencode/skills/my-skill
+ *   bun scripts/validate-skill.ts global-skills/debugging
+ */
+
+import { readFile, readdir } from "fs/promises";
+import { existsSync } from "fs";
+import { join, basename } from "path";
+import { parseFrontmatter } from "../src/skills.js";
+
+interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+  info: string[];
+}
+
+async function validateSkill(skillPath: string): Promise<ValidationResult> {
+  const result: ValidationResult = {
+    valid: true,
+    errors: [],
+    warnings: [],
+    info: [],
+  };
+
+  const skillName = basename(skillPath);
+
+  // Check directory exists
+  if (!existsSync(skillPath)) {
+    result.errors.push(`Skill directory does not exist: ${skillPath}`);
+    result.valid = false;
+    return result;
+  }
+
+  // Check SKILL.md exists
+  const skillMdPath = join(skillPath, "SKILL.md");
+  if (!existsSync(skillMdPath)) {
+    result.errors.push("Missing required SKILL.md file");
+    result.valid = false;
+    return result;
+  }
+
+  // Read and parse SKILL.md
+  const content = await readFile(skillMdPath, "utf-8");
+
+  // Check frontmatter
+  if (!content.startsWith("---\n") && !content.startsWith("---\r\n")) {
+    result.errors.push("SKILL.md must start with YAML frontmatter (---)");
+    result.valid = false;
+    return result;
+  }
+
+  const { metadata: frontmatter, body } = parseFrontmatter(content);
+  if (Object.keys(frontmatter).length === 0) {
+    result.errors.push("Invalid YAML frontmatter format");
+    result.valid = false;
+    return result;
+  }
+
+  // Validate required fields
+  if (!frontmatter.name) {
+    result.errors.push("Missing required 'name' field in frontmatter");
+    result.valid = false;
+  } else if (frontmatter.name !== skillName) {
+    result.warnings.push(
+      `Frontmatter name '${frontmatter.name}' doesn't match directory name '${skillName}'`,
+    );
+  }
+
+  if (!frontmatter.description) {
+    result.errors.push("Missing required 'description' field in frontmatter");
+    result.valid = false;
+  } else {
+    const desc = String(frontmatter.description);
+    if (desc.includes("[TODO")) {
+      result.warnings.push("Description contains TODO placeholder");
+    }
+    if (desc.length < 20) {
+      result.warnings.push("Description is very short (< 20 chars)");
+    }
+    if (desc.length > 500) {
+      result.warnings.push("Description is very long (> 500 chars)");
+    }
+  }
+
+  // Check for TODO placeholders in body
+  const todoCount = (body.match(/\[TODO/g) || []).length;
+  if (todoCount > 0) {
+    result.warnings.push(`Found ${todoCount} TODO placeholder(s) in body`);
+  }
+
+  // Check body length (body is already extracted by parseFrontmatter)
+  const lineCount = body.split("\n").length;
+  if (lineCount > 500) {
+    result.warnings.push(
+      `SKILL.md body is ${lineCount} lines (recommended < 500)`,
+    );
+  }
+
+  // Check for optional directories
+  const scriptsDir = join(skillPath, "scripts");
+  const refsDir = join(skillPath, "references");
+  const assetsDir = join(skillPath, "assets");
+
+  if (existsSync(scriptsDir)) {
+    const scripts = await readdir(scriptsDir);
+    result.info.push(`Found ${scripts.length} script(s) in scripts/`);
+
+    // Check for example placeholders
+    if (scripts.includes("example.sh") || scripts.includes("example.py")) {
+      result.warnings.push("Contains placeholder example script");
+    }
+  }
+
+  if (existsSync(refsDir)) {
+    const refs = await readdir(refsDir);
+    result.info.push(`Found ${refs.length} reference(s) in references/`);
+  }
+
+  if (existsSync(assetsDir)) {
+    const assets = await readdir(assetsDir);
+    result.info.push(`Found ${assets.length} asset(s) in assets/`);
+  }
+
+  // Check for unwanted files
+  const unwantedFiles = [
+    "README.md",
+    "CHANGELOG.md",
+    "INSTALLATION.md",
+    "CONTRIBUTING.md",
+  ];
+  for (const file of unwantedFiles) {
+    if (existsSync(join(skillPath, file))) {
+      result.warnings.push(
+        `Found ${file} - skills should only contain SKILL.md and resources`,
+      );
+    }
+  }
+
+  return result;
+}
+
+// Main
+const skillPath = process.argv[2];
+
+if (!skillPath) {
+  console.log(`
+Skill Validator - Validates skill structure and content
+
+Usage:
+  bun scripts/validate-skill.ts <path/to/skill>
+
+Examples:
+  bun scripts/validate-skill.ts .opencode/skills/my-skill
+  bun scripts/validate-skill.ts global-skills/debugging
+`);
+  process.exit(1);
+}
+
+console.log(`Validating skill: ${skillPath}\n`);
+
+const result = await validateSkill(skillPath);
+
+// Print results
+if (result.errors.length > 0) {
+  console.log("❌ Errors:");
+  for (const error of result.errors) {
+    console.log(`   - ${error}`);
+  }
+  console.log();
+}
+
+if (result.warnings.length > 0) {
+  console.log("⚠️  Warnings:");
+  for (const warning of result.warnings) {
+    console.log(`   - ${warning}`);
+  }
+  console.log();
+}
+
+if (result.info.length > 0) {
+  console.log("ℹ️  Info:");
+  for (const info of result.info) {
+    console.log(`   - ${info}`);
+  }
+  console.log();
+}
+
+if (result.valid) {
+  console.log("✅ Skill is valid!");
+  if (result.warnings.length > 0) {
+    console.log("   (but consider addressing warnings above)");
+  }
+} else {
+  console.log("❌ Skill validation failed");
+  process.exit(1);
+}

package/src/agent-mail.ts

@@ -27,6 +27,35 @@ const AGENT_MAIL_URL = "http://127.0.0.1:8765";
 const DEFAULT_TTL_SECONDS = 3600; // 1 hour
 const MAX_INBOX_LIMIT = 5; // HARD CAP - never exceed this
 
+/**
+ * Default project directory for Agent Mail operations
+ *
+ * This is set by the plugin init to the actual working directory (from OpenCode).
+ * Without this, tools might use the plugin's directory instead of the project's.
+ *
+ * Set this via setAgentMailProjectDirectory() before using tools.
+ */
+let agentMailProjectDirectory: string | null = null;
+
+/**
+ * Set the default project directory for Agent Mail operations
+ *
+ * Called during plugin initialization with the actual project directory.
+ * This ensures agentmail_init uses the correct project path by default.
+ */
+export function setAgentMailProjectDirectory(directory: string): void {
+  agentMailProjectDirectory = directory;
+}
+
+/**
+ * Get the default project directory
+ *
+ * Returns the configured directory, or falls back to cwd if not set.
+ */
+export function getAgentMailProjectDirectory(): string {
+  return agentMailProjectDirectory || process.cwd();
+}
+
 // Retry configuration
 const RETRY_CONFIG = {
   maxRetries: parseInt(process.env.OPENCODE_AGENT_MAIL_MAX_RETRIES || "3"),
@@ -1077,7 +1106,10 @@ export const agentmail_init = tool({
   args: {
     project_path: tool.schema
       .string()
-      .describe("Absolute path to the project/repo"),
+      .optional()
+      .describe(
+        "Absolute path to the project/repo (defaults to current working directory)",
+      ),
     agent_name: tool.schema
       .string()
       .optional()
@@ -1088,6 +1120,10 @@ export const agentmail_init = tool({
       .describe("Description of current task"),
   },
   async execute(args, ctx) {
+    // Use provided path or fall back to configured project directory
+    // This prevents using the plugin's directory when working in a different project
+    const projectPath = args.project_path || getAgentMailProjectDirectory();
+
     // Check if Agent Mail is available
     const available = await checkAgentMailAvailable();
     if (!available) {
@@ -1113,12 +1149,12 @@ export const agentmail_init = tool({
       try {
         // 1. Ensure project exists
         const project = await mcpCall<ProjectInfo>("ensure_project", {
-          human_key: args.project_path,
+          human_key: projectPath,
         });
 
         // 2. Register agent
         const agent = await mcpCall<AgentInfo>("register_agent", {
-          project_key: args.project_path,
+          project_key: projectPath,
           program: "opencode",
           model: "claude-opus-4",
           name: args.agent_name, // undefined = auto-generate
@@ -1127,7 +1163,7 @@ export const agentmail_init = tool({
 
         // 3. Store state using sessionID
         const state: AgentMailState = {
-          projectKey: args.project_path,
+          projectKey: projectPath,
           agentName: agent.name,
           reservations: [],
           startedAt: new Date().toISOString(),

package/src/beads.ts

@@ -159,6 +159,11 @@ function buildCreateCommand(args: BeadCreateArgs): string[] {
     parts.push("--parent", args.parent_id);
   }
 
+  // Custom ID for human-readable bead names (e.g., 'phase-0', 'phase-1.e2e-test')
+  if (args.id) {
+    parts.push("--id", args.id);
+  }
+
   parts.push("--json");
   return parts;
 }
@@ -288,12 +293,22 @@ export const beads_create_epic = tool({
       .string()
       .optional()
       .describe("Epic description"),
+    epic_id: tool.schema
+      .string()
+      .optional()
+      .describe("Custom ID for the epic (e.g., 'phase-0')"),
     subtasks: tool.schema
       .array(
         tool.schema.object({
           title: tool.schema.string(),
           priority: tool.schema.number().min(0).max(3).optional(),
           files: tool.schema.array(tool.schema.string()).optional(),
+          id_suffix: tool.schema
+            .string()
+            .optional()
+            .describe(
+              "Custom ID suffix (e.g., 'e2e-test' becomes 'phase-0.e2e-test')",
+            ),
         }),
       )
       .describe("Subtasks to create under the epic"),
@@ -309,6 +324,7 @@ export const beads_create_epic = tool({
         type: "epic",
         priority: 1,
         description: validated.epic_description,
+        id: validated.epic_id,
       });
 
       const epicResult = await runBdCommand(epicCmd.slice(1)); // Remove 'bd' prefix
@@ -326,11 +342,19 @@ export const beads_create_epic = tool({
 
       // 2. Create subtasks
       for (const subtask of validated.subtasks) {
+        // Build subtask ID: if epic has custom ID and subtask has suffix, combine them
+        // e.g., epic_id='phase-0', id_suffix='e2e-test' → 'phase-0.e2e-test'
+        let subtaskId: string | undefined;
+        if (validated.epic_id && subtask.id_suffix) {
+          subtaskId = `${validated.epic_id}.${subtask.id_suffix}`;
+        }
+
         const subtaskCmd = buildCreateCommand({
           title: subtask.title,
           type: "task",
           priority: subtask.priority ?? 2,
           parent_id: epic.id,
+          id: subtaskId,
         });
 
         const subtaskResult = await runBdCommand(subtaskCmd.slice(1)); // Remove 'bd' prefix

package/src/index.ts

@@ -25,12 +25,14 @@ import type { Plugin, PluginInput, Hooks } from "@opencode-ai/plugin";
 import { beadsTools, setBeadsWorkingDirectory } from "./beads";
 import {
   agentMailTools,
+  setAgentMailProjectDirectory,
   type AgentMailState,
   AGENT_MAIL_URL,
 } from "./agent-mail";
 import { structuredTools } from "./structured";
 import { swarmTools } from "./swarm";
 import { repoCrawlTools } from "./repo-crawl";
+import { skillsTools, setSkillsProjectDirectory } from "./skills";
 
 /**
  * OpenCode Swarm Plugin
@@ -41,6 +43,7 @@ import { repoCrawlTools } from "./repo-crawl";
  * - structured:* - Structured output parsing and validation
  * - swarm:* - Swarm orchestration and task decomposition
  * - repo-crawl:* - GitHub API tools for repository research
+ * - skills:* - Agent skills discovery, activation, and execution
  *
  * @param input - Plugin context from OpenCode
  * @returns Plugin hooks including tools, events, and tool execution hooks
@@ -54,6 +57,15 @@ export const SwarmPlugin: Plugin = async (
   // This ensures bd runs in the project directory, not ~/.config/opencode
   setBeadsWorkingDirectory(directory);
 
+  // Set the project directory for skills discovery
+  // Skills are discovered from .opencode/skills/, .claude/skills/, or skills/
+  setSkillsProjectDirectory(directory);
+
+  // Set the project directory for Agent Mail
+  // This ensures agentmail_init uses the correct project path by default
+  // (prevents using plugin directory when working in a different project)
+  setAgentMailProjectDirectory(directory);
+
   /** Track active sessions for cleanup */
   let activeAgentMailState: AgentMailState | null = null;
 
@@ -116,6 +128,7 @@ export const SwarmPlugin: Plugin = async (
       ...structuredTools,
       ...swarmTools,
       ...repoCrawlTools,
+      ...skillsTools,
     },
 
     /**
@@ -239,6 +252,11 @@ export {
   AgentMailNotInitializedError,
   FileReservationConflictError,
   createAgentMailError,
+  setAgentMailProjectDirectory,
+  getAgentMailProjectDirectory,
+  mcpCallWithAutoInit,
+  isProjectNotFoundError,
+  isAgentNotFoundError,
   type AgentMailState,
 } from "./agent-mail";
 
@@ -305,6 +323,7 @@ export const allTools = {
   ...structuredTools,
   ...swarmTools,
   ...repoCrawlTools,
+  ...skillsTools,
 } as const;
 
 /**
@@ -387,3 +406,33 @@ export {
  * - Graceful rate limit handling
  */
 export { repoCrawlTools, RepoCrawlError } from "./repo-crawl";
+
+/**
+ * Re-export skills module
+ *
+ * Implements Anthropic's Agent Skills specification for OpenCode.
+ *
+ * Includes:
+ * - skillsTools - All skills tools (list, use, execute, read)
+ * - discoverSkills, getSkill, listSkills - Discovery functions
+ * - parseFrontmatter - YAML frontmatter parser
+ * - getSkillsContextForSwarm - Swarm integration helper
+ * - findRelevantSkills - Task-based skill matching
+ *
+ * Types:
+ * - Skill, SkillMetadata, SkillRef - Skill data types
+ */
+export {
+  skillsTools,
+  discoverSkills,
+  getSkill,
+  listSkills,
+  parseFrontmatter,
+  setSkillsProjectDirectory,
+  invalidateSkillsCache,
+  getSkillsContextForSwarm,
+  findRelevantSkills,
+  type Skill,
+  type SkillMetadata,
+  type SkillRef,
+} from "./skills";