opencode-swarm-plugin 0.12.25 → 0.12.27

package/.beads/issues.jsonl

@@ -633,6 +633,13 @@
 {"id":"opencode-swarm-plugin-cert","title":"Test bead minimal","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:12:40.697512-08:00","updated_at":"2025-12-08T11:12:43.475157-08:00","closed_at":"2025-12-08T11:12:43.475157-08:00"}
 {"id":"opencode-swarm-plugin-cf7z","title":"Test bead minimal","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T19:41:10.601954-08:00","updated_at":"2025-12-07T19:41:13.224334-08:00","closed_at":"2025-12-07T19:41:13.224334-08:00"}
 {"id":"opencode-swarm-plugin-cjq3","title":"Thread link test bead","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T08:23:19.197074-08:00","updated_at":"2025-12-08T08:23:20.668185-08:00","closed_at":"2025-12-08T08:23:20.668185-08:00"}
+{"id":"opencode-swarm-plugin-cliku","title":"Investigate potential skills for opencode-swarm-plugin","description":"Analyze codebase patterns, workflows, and domain knowledge to identify new skill opportunities beyond the existing 5 bundled skills","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-12T21:44:25.282969-08:00","updated_at":"2025-12-12T21:47:11.486359-08:00","closed_at":"2025-12-12T21:47:11.486359-08:00"}
+{"id":"opencode-swarm-plugin-cliku.1","title":"Analyze src/ modules for extractable patterns","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-12T21:44:25.33437-08:00","updated_at":"2025-12-12T21:46:09.368653-08:00","closed_at":"2025-12-12T21:46:09.368662-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-cliku.1","depends_on_id":"opencode-swarm-plugin-cliku","type":"parent-child","created_at":"2025-12-12T21:44:25.335292-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-cliku.2","title":"Analyze existing skills for gaps and extensions","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-12T21:44:25.38425-08:00","updated_at":"2025-12-12T21:46:10.054798-08:00","closed_at":"2025-12-12T21:46:10.0548-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-cliku.2","depends_on_id":"opencode-swarm-plugin-cliku","type":"parent-child","created_at":"2025-12-12T21:44:25.385157-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-cliku.3","title":"Search CASS for skill-related patterns from past sessions","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-12T21:44:25.437227-08:00","updated_at":"2025-12-12T21:46:10.75249-08:00","closed_at":"2025-12-12T21:46:10.752496-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-cliku.3","depends_on_id":"opencode-swarm-plugin-cliku","type":"parent-child","created_at":"2025-12-12T21:44:25.438595-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-cliku.4","title":"Analyze CLI and plugin patterns for tooling skills","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-12T21:44:25.48734-08:00","updated_at":"2025-12-12T21:46:11.436638-08:00","closed_at":"2025-12-12T21:46:11.43664-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-cliku.4","depends_on_id":"opencode-swarm-plugin-cliku","type":"parent-child","created_at":"2025-12-12T21:44:25.488372-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-cliku.5","title":"Synthesize findings into skill recommendations","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-12T21:44:25.535457-08:00","updated_at":"2025-12-12T21:47:09.742548-08:00","closed_at":"2025-12-12T21:47:09.742548-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-cliku.5","depends_on_id":"opencode-swarm-plugin-cliku","type":"parent-child","created_at":"2025-12-12T21:44:25.536925-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-cliku.6","title":"Search pdf-brain for skill-worthy knowledge","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-12T21:46:12.83653-08:00","updated_at":"2025-12-12T21:46:46.011065-08:00","closed_at":"2025-12-12T21:46:46.011065-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-cliku.6","depends_on_id":"opencode-swarm-plugin-cliku","type":"parent-child","created_at":"2025-12-12T21:46:12.837492-08:00","created_by":"daemon"}]}
 {"id":"opencode-swarm-plugin-cmo6","title":"Update test bead","description":"Blocked on dependency","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-08T07:53:44.299916-08:00","updated_at":"2025-12-08T07:53:46.527966-08:00","closed_at":"2025-12-08T07:53:46.527966-08:00"}
 {"id":"opencode-swarm-plugin-cmx0j","title":"Thread link test bead","description":"Important context here\n\n[thread:test-thread-789]","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T09:06:08.377019-08:00","updated_at":"2025-12-10T09:06:10.913752-08:00","closed_at":"2025-12-10T09:06:10.913752-08:00"}
 {"id":"opencode-swarm-plugin-cor","title":"Bead to close","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T19:34:53.00247-08:00","updated_at":"2025-12-07T19:34:53.027513-08:00","closed_at":"2025-12-07T19:34:53.027513-08:00"}
@@ -828,6 +835,15 @@
 {"id":"opencode-swarm-plugin-ga3","title":"Query test bead","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T19:39:18.459646-08:00","updated_at":"2025-12-07T19:39:20.527941-08:00","closed_at":"2025-12-07T19:39:20.527941-08:00"}
 {"id":"opencode-swarm-plugin-gatr","title":"Epic with file references","description":"","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-08T11:11:08.773318-08:00","updated_at":"2025-12-08T11:11:10.670318-08:00","closed_at":"2025-12-08T11:11:10.670318-08:00"}
 {"id":"opencode-swarm-plugin-gatr.2","title":"Edit src/b.ts","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:11:08.844156-08:00","updated_at":"2025-12-08T11:11:10.722914-08:00","closed_at":"2025-12-08T11:11:10.722914-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gatr.2","depends_on_id":"opencode-swarm-plugin-gatr","type":"parent-child","created_at":"2025-12-08T11:11:08.844503-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-gf1n8","title":"Add skills documentation and create 7 new bundled skills","description":"Update README with skills feature documentation, publish new version, then create 7 new skills: agent-patterns, tacit-knowledge-extraction, learning-systems, zod-validation, resilience-patterns, mcp-tool-authoring, testing-strategies","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-12T21:49:01.067542-08:00","updated_at":"2025-12-12T21:53:55.973974-08:00","closed_at":"2025-12-12T21:53:55.973974-08:00"}
+{"id":"opencode-swarm-plugin-gf1n8.1","title":"Update README with skills documentation","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-12T21:49:01.108379-08:00","updated_at":"2025-12-12T21:49:37.717118-08:00","closed_at":"2025-12-12T21:49:37.717118-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gf1n8.1","depends_on_id":"opencode-swarm-plugin-gf1n8","type":"parent-child","created_at":"2025-12-12T21:49:01.109457-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-gf1n8.2","title":"Create agent-patterns skill from PDF","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-12T21:49:01.147507-08:00","updated_at":"2025-12-12T21:53:28.210831-08:00","closed_at":"2025-12-12T21:53:28.210831-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gf1n8.2","depends_on_id":"opencode-swarm-plugin-gf1n8","type":"parent-child","created_at":"2025-12-12T21:49:01.148296-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-gf1n8.3","title":"Create tacit-knowledge-extraction skill","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-12T21:49:01.190071-08:00","updated_at":"2025-12-12T21:53:29.05083-08:00","closed_at":"2025-12-12T21:53:29.05083-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gf1n8.3","depends_on_id":"opencode-swarm-plugin-gf1n8","type":"parent-child","created_at":"2025-12-12T21:49:01.191674-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-gf1n8.4","title":"Create learning-systems skill","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-12T21:49:01.240273-08:00","updated_at":"2025-12-12T21:53:29.822709-08:00","closed_at":"2025-12-12T21:53:29.822709-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gf1n8.4","depends_on_id":"opencode-swarm-plugin-gf1n8","type":"parent-child","created_at":"2025-12-12T21:49:01.241765-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-gf1n8.5","title":"Create zod-validation skill","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-12T21:49:01.286597-08:00","updated_at":"2025-12-12T21:53:30.592121-08:00","closed_at":"2025-12-12T21:53:30.592121-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gf1n8.5","depends_on_id":"opencode-swarm-plugin-gf1n8","type":"parent-child","created_at":"2025-12-12T21:49:01.287248-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-gf1n8.6","title":"Create resilience-patterns skill","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-12T21:49:01.326304-08:00","updated_at":"2025-12-12T21:53:31.396458-08:00","closed_at":"2025-12-12T21:53:31.396458-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gf1n8.6","depends_on_id":"opencode-swarm-plugin-gf1n8","type":"parent-child","created_at":"2025-12-12T21:49:01.327839-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-gf1n8.7","title":"Create mcp-tool-authoring skill","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-12T21:49:01.3722-08:00","updated_at":"2025-12-12T21:53:32.220987-08:00","closed_at":"2025-12-12T21:53:32.220987-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gf1n8.7","depends_on_id":"opencode-swarm-plugin-gf1n8","type":"parent-child","created_at":"2025-12-12T21:49:01.373746-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-gf1n8.8","title":"Create testing-strategies skill","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-12T21:49:01.415744-08:00","updated_at":"2025-12-12T21:53:32.979008-08:00","closed_at":"2025-12-12T21:53:32.979008-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gf1n8.8","depends_on_id":"opencode-swarm-plugin-gf1n8","type":"parent-child","created_at":"2025-12-12T21:49:01.417461-08:00","created_by":"daemon"}]}
 {"id":"opencode-swarm-plugin-gf3y","title":"Query test bead","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:12:25.651349-08:00","updated_at":"2025-12-08T11:12:28.033348-08:00","closed_at":"2025-12-08T11:12:28.033348-08:00"}
 {"id":"opencode-swarm-plugin-ggq","title":"Limit test bead 4","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T19:36:06.582584-08:00","updated_at":"2025-12-07T19:36:08.680139-08:00","closed_at":"2025-12-07T19:36:08.680139-08:00"}
 {"id":"opencode-swarm-plugin-gh1h","title":"Bead to close","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:11:38.973012-08:00","updated_at":"2025-12-08T11:11:38.996815-08:00","closed_at":"2025-12-08T11:11:38.996815-08:00"}
@@ -925,6 +941,7 @@
 {"id":"opencode-swarm-plugin-if3v","title":"Limit test bead 4","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:10:53.346318-08:00","updated_at":"2025-12-08T11:10:55.820026-08:00","closed_at":"2025-12-08T11:10:55.820026-08:00"}
 {"id":"opencode-swarm-plugin-ijyv","title":"Epic with file references","description":"","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-08T08:56:56.579396-08:00","updated_at":"2025-12-08T08:56:58.480064-08:00","closed_at":"2025-12-08T08:56:58.480064-08:00"}
 {"id":"opencode-swarm-plugin-ijyv.2","title":"Edit src/b.ts","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T08:56:56.641855-08:00","updated_at":"2025-12-08T08:56:58.530793-08:00","closed_at":"2025-12-08T08:56:58.530793-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-ijyv.2","depends_on_id":"opencode-swarm-plugin-ijyv","type":"parent-child","created_at":"2025-12-08T08:56:56.642441-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-ijzjd","title":"Update README to document skills feature","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-12T21:46:13.821586-08:00","updated_at":"2025-12-12T21:49:38.634771-08:00","closed_at":"2025-12-12T21:49:38.634771-08:00"}
 {"id":"opencode-swarm-plugin-ikff","title":"Integration test epic","description":"Testing epic creation","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-08T08:56:56.45202-08:00","updated_at":"2025-12-08T08:56:58.380335-08:00","closed_at":"2025-12-08T08:56:58.380335-08:00"}
 {"id":"opencode-swarm-plugin-ikff.1","title":"Subtask 1","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T08:56:56.484256-08:00","updated_at":"2025-12-08T08:56:58.407318-08:00","closed_at":"2025-12-08T08:56:58.407318-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-ikff.1","depends_on_id":"opencode-swarm-plugin-ikff","type":"parent-child","created_at":"2025-12-08T08:56:56.485079-08:00","created_by":"daemon"}]}
 {"id":"opencode-swarm-plugin-ikff.2","title":"Subtask 2","description":"","status":"closed","priority":3,"issue_type":"task","created_at":"2025-12-08T08:56:56.516509-08:00","updated_at":"2025-12-08T08:56:58.432353-08:00","closed_at":"2025-12-08T08:56:58.432353-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-ikff.2","depends_on_id":"opencode-swarm-plugin-ikff","type":"parent-child","created_at":"2025-12-08T08:56:56.517327-08:00","created_by":"daemon"}]}

package/.github/workflows/opencode.yml

@@ -0,0 +1,31 @@
+name: opencode
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+
+jobs:
+  opencode:
+    if: |
+      contains(github.event.comment.body, ' /oc') ||
+      startsWith(github.event.comment.body, '/oc') ||
+      contains(github.event.comment.body, ' /opencode') ||
+      startsWith(github.event.comment.body, '/opencode')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+      pull-requests: read
+      issues: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Run opencode
+        uses: sst/opencode/github@latest
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        with:
+          model: anthropic/claude-sonnet-4-5

package/README.md

@@ -170,6 +170,111 @@ model: anthropic/claude-haiku-4-5 # Your chosen worker model
 
 Edit these files to customize behavior. Run `swarm setup` to regenerate defaults.
 
+## Skills
+
+Skills are reusable knowledge packages that agents can load on-demand. They contain domain expertise, workflows, and patterns that help agents perform specialized tasks.
+
+### Using Skills
+
+```bash
+# List available skills
+swarm tool skills_list
+
+# Read a skill's content
+swarm tool skills_read --json '{"name": "debugging"}'
+
+# Use a skill (get formatted for context injection)
+swarm tool skills_use --json '{"name": "code-review", "context": "reviewing a PR"}'
+```
+
+In OpenCode, agents can use skills directly:
+
+```
+skills_list()                           # See what's available
+skills_use(name="debugging")            # Load debugging patterns
+skills_use(name="swarm-coordination")   # Load swarm workflow
+```
+
+### Bundled Skills
+
+| Skill                        | Tags                 | Description                                                                          |
+| ---------------------------- | -------------------- | ------------------------------------------------------------------------------------ |
+| `agent-patterns`             | ai, agents, patterns | AI agent design patterns - capability whiteboards, architecture evolution, evals     |
+| `cli-builder`                | cli, typescript, bun | Building TypeScript CLIs with Bun - argument parsing, subcommands, output formatting |
+| `code-review`                | review, quality      | Code review patterns - systematic checklists, feedback patterns                      |
+| `debugging`                  | debugging, errors    | Systematic debugging - root cause analysis, error resolution                         |
+| `learning-systems`           | learning, feedback   | Implicit feedback scoring, confidence decay, anti-pattern detection                  |
+| `mcp-tool-authoring`         | mcp, tools           | Building MCP tools - schema definition, context passing, error handling              |
+| `resilience-patterns`        | errors, recovery     | Error recovery, retry strategies, graceful degradation                               |
+| `skill-creator`              | meta, skills         | Guide for creating effective skills                                                  |
+| `swarm-coordination`         | swarm, multi-agent   | Multi-agent coordination patterns for swarm workflows                                |
+| `tacit-knowledge-extraction` | knowledge, patterns  | Extracting tacit knowledge into pattern languages                                    |
+| `testing-strategies`         | testing, vitest      | Testing async/swarm operations, mocking patterns                                     |
+| `zod-validation`             | zod, typescript      | Schema validation patterns with Zod                                                  |
+
+### Skill Locations
+
+Skills are loaded from three locations (in order):
+
+1. **Project skills**: `.opencode/skills/`, `.claude/skills/`, or `skills/`
+2. **Global skills**: `~/.config/opencode/skills/`
+3. **Bundled skills**: Included with the plugin
+
+### Creating Skills
+
+```bash
+# Initialize project skills directory
+swarm tool skills_init
+
+# Create a new skill
+swarm tool skills_create --json '{"name": "my-skill", "description": "What it does", "tags": ["tag1", "tag2"]}'
+```
+
+Or use the `skill-creator` skill for guidance:
+
+```
+skills_use(name="skill-creator")
+```
+
+Each skill is a directory containing:
+
+```
+my-skill/
+  SKILL.md           # Main content (required)
+  references/        # Optional supporting files
+    patterns.md
+    examples.md
+```
+
+### SKILL.md Format
+
+```markdown
+---
+name: my-skill
+description: Brief description for discovery
+tags:
+  - tag1
+  - tag2
+---
+
+# My Skill
+
+## When to Use
+
+- Trigger condition 1
+- Trigger condition 2
+
+## Patterns
+
+### Pattern Name
+
+Description and examples...
+
+## Anti-Patterns
+
+What NOT to do...
+```
+
 ## Dependencies
 
 | Dependency                                                                                             | Purpose                                                      | Required |

package/bin/swarm.ts

@@ -1072,6 +1072,79 @@ async function setup() {
     }
   }
 
+  // Offer to update AGENTS.md with skill awareness
+  const agentsPath = join(configDir, "AGENTS.md");
+  if (existsSync(agentsPath)) {
+    const updateAgents = await p.confirm({
+      message: "Update AGENTS.md with skill awareness?",
+      initialValue: true,
+    });
+
+    if (!p.isCancel(updateAgents) && updateAgents) {
+      const s = p.spinner();
+      s.start("Updating AGENTS.md...");
+
+      const agentsPrompt = `You are updating the user's AGENTS.md file to add skill awareness.
+
+## Task
+Read ${agentsPath} and add a Skills section if one doesn't exist. If a skills section exists, update it.
+
+## What to Add
+
+1. **Tool Preferences** - If there's a tool_preferences or similar section, add skills tools:
+   - skills_list - discover available skills
+   - skills_use - load skill for context injection  
+   - skills_read - read full skill content
+
+2. **Skills Section** - Add this (adapt style to match the file):
+
+### Skills (Knowledge Injection)
+
+Skills are reusable knowledge packages. Load them on-demand for specialized tasks.
+
+**When to Use:**
+- Before unfamiliar work - check if a skill exists
+- When you need domain-specific patterns
+- For complex workflows that benefit from guidance
+
+**Usage:**
+\`\`\`
+skills_list()                              # See available skills
+skills_use(name="debugging")               # Load a skill
+skills_use(name="code-review", context="reviewing auth") # With context
+\`\`\`
+
+**Bundled Skills:** agent-patterns, cli-builder, code-review, debugging, learning-systems, mcp-tool-authoring, resilience-patterns, skill-creator, swarm-coordination, tacit-knowledge-extraction, testing-strategies, zod-validation
+
+## Rules
+- Preserve existing content and style
+- Don't duplicate - update if skills section exists
+- Keep tone consistent
+- Place near tool preferences or as logical new section
+
+Edit the file now.`;
+
+      try {
+        const result = Bun.spawnSync(["opencode", "run", agentsPrompt], {
+          stdout: "pipe",
+          stderr: "pipe",
+          timeout: 120000,
+        });
+
+        if (result.exitCode === 0) {
+          s.stop("AGENTS.md updated");
+          p.log.success("Added skill awareness to AGENTS.md");
+        } else {
+          s.stop("Could not update AGENTS.md");
+          p.log.warn("You can manually add skills section later");
+        }
+      } catch {
+        s.stop("Could not update AGENTS.md");
+        p.log.warn("You can manually add skills section later");
+      }
+    }
+  }
+
   p.note(
     'cd your-project\nbd init\nopencode\n/swarm "your task"\n\nSkills: Use skills_list to see available skills',
     "Next steps",
@@ -1351,6 +1424,7 @@ ${cyan("Commands:")}
   swarm doctor    Health check - shows status of all dependencies
   swarm init      Initialize beads in current project
   swarm config    Show paths to generated config files
+  swarm agents    Update AGENTS.md with skill awareness
   swarm update    Update to latest version
   swarm version   Show version and banner
   swarm tool      Execute a tool (for plugin wrapper)
@@ -1525,6 +1599,131 @@ async function listTools() {
   );
 }
 
+// ============================================================================
+// Agents Command - Update AGENTS.md with skill awareness
+// ============================================================================
+
+async function agents() {
+  const home = process.env.HOME || process.env.USERPROFILE || "~";
+  const agentsPath = join(home, ".config", "opencode", "AGENTS.md");
+
+  p.intro(yellow(BANNER));
+
+  // Check if AGENTS.md exists
+  if (!existsSync(agentsPath)) {
+    p.log.warn("No AGENTS.md found at " + agentsPath);
+    p.log.message(
+      dim("Create one first, then run this command to add skill awareness"),
+    );
+    p.outro("Aborted");
+    return;
+  }
+
+  // Check if opencode is available
+  const opencode = await checkCommand("opencode", ["--version"]);
+  if (!opencode.available) {
+    p.log.error("OpenCode not found");
+    p.log.message(dim("Install: npm install -g opencode"));
+    p.outro("Aborted");
+    return;
+  }
+
+  const confirm = await p.confirm({
+    message: "Update AGENTS.md with skill awareness?",
+    initialValue: true,
+  });
+
+  if (p.isCancel(confirm) || !confirm) {
+    p.outro("Aborted");
+    return;
+  }
+
+  const s = p.spinner();
+  s.start("Updating AGENTS.md with skill awareness...");
+
+  const prompt = `You are updating the user's AGENTS.md file to add skill awareness.
+
+## Task
+Read ~/.config/opencode/AGENTS.md and add a Skills section if one doesn't exist.
+
+## What to Add
+Add a section about using skills. Include:
+
+1. **Tool Preferences Update** - Add skills_* tools to the tool priority list:
+   - skills_list - discover available skills
+   - skills_use - load skill for context injection
+   - skills_read - read full skill content
+
+2. **Skills Section** - Add this section (adapt to match the file's style):
+
+### Skills (Knowledge Injection)
+
+Skills are reusable knowledge packages. Load them on-demand for specialized tasks.
+
+**When to Use Skills:**
+- Before starting unfamiliar work - check if a skill exists
+- When you need domain-specific patterns
+- For complex workflows that benefit from guidance
+
+**Available Skills** (run \`skills_list()\` to see current list):
+- agent-patterns: AI agent design patterns
+- cli-builder: TypeScript CLI patterns
+- code-review: Review checklists
+- debugging: Root cause analysis
+- learning-systems: Feedback scoring, pattern maturity
+- mcp-tool-authoring: Building MCP tools
+- resilience-patterns: Error recovery, retries
+- skill-creator: Creating new skills
+- swarm-coordination: Multi-agent workflows
+- tacit-knowledge-extraction: Pattern mining
+- testing-strategies: Vitest patterns
+- zod-validation: Schema validation
+
+**Usage Pattern:**
+\`\`\`
+# Check what's available
+skills_list()
+
+# Load a skill before starting work
+skills_use(name="debugging")
+
+# Load with context
+skills_use(name="code-review", context="reviewing auth changes")
+\`\`\`
+
+## Rules
+- Preserve the existing content and style
+- Add the skills section in a logical place (near tool preferences or as a new section)
+- Don't duplicate if a skills section already exists - update it instead
+- Keep the tone consistent with the rest of the file
+
+Edit the file now.`;
+
+  try {
+    const result = Bun.spawnSync(["opencode", "run", prompt], {
+      stdio: ["inherit", "pipe", "pipe"],
+      timeout: 120000, // 2 minute timeout
+    });
+
+    if (result.exitCode === 0) {
+      s.stop("AGENTS.md updated with skill awareness");
+      p.log.success("Skills section added to " + agentsPath);
+      p.log.message(
+        dim("Skills available: skills_list, skills_use, skills_read"),
+      );
+    } else {
+      const stderr = result.stderr?.toString() || "";
+      s.stop("Failed to update AGENTS.md");
+      p.log.error(stderr || "Unknown error");
+    }
+  } catch (error) {
+    s.stop("Failed to update AGENTS.md");
+    p.log.error(String(error));
+  }
+
+  p.outro("Done");
+}
+
 // ============================================================================
 // Main
 // ============================================================================
@@ -1560,6 +1759,9 @@ switch (command) {
     }
     break;
   }
+  case "agents":
+    await agents();
+    break;
   case "version":
   case "--version":
   case "-v":