yams-blackboard - SKILL.md Agent Skill

name: yams-blackboard description: Blackboard plugin for OpenCode built on YAMS, enabling agents to share findings, tasks, and context via a persistent knowledge graph. license: GPL-3.0 compatibility: claude-code, opencode metadata: tools: | bb_register_agent, bb_list_agents, bb_post_finding, bb_get_finding, bb_query_findings, bb_search_findings, bb_acknowledge_finding, bb_resolve_finding, bb_create_task, bb_get_ready_tasks, bb_claim_task, bb_update_task, bb_complete_task, bb_fail_task, bb_query_tasks, bb_create_context, bb_get_context_summary, bb_set_context, bb_recent_activity, bb_stats, bb_connections

categories: agent, coordination, blackboard, knowledge-graph

YAMS Blackboard Skill (OpenCode)

Overview

This skill implements the classic blackboard pattern for multi‑agent systems using YAMS as the shared memory layer. Agents can:

Register themselves and publish capabilities.
Post findings (tagged markdown documents) that other agents can query or search.
Create, claim, and complete tasks that coordinate work across agents.
Group related work into contexts and explore relationships via YAMS’ graph commands.

All data is stored in YAMS, so the same powerful search (yams grep, yams search) and graph (yams graph) capabilities are available.

Quick Reference

# Start a YAMS session (optional, auto‑starts on OpenCode session creation)
yams session start --name "opencode-session"

# Register an agent
bb_register_agent '{"id":"scanner","name":"Security Scanner","capabilities":["security","code-review"]}'

# Post a finding
bb_post_finding '{"agent_id":"scanner","topic":"security","title":"SQL Injection","severity":"high","confidence":0.94,"content":"..."}'

# Search findings
bb_search_findings '{"query":"SQL injection"}'

# Create and claim a task
bb_create_task '{"title":"Fix injection","type":"fix","created_by":"coordinator","priority":1}'
bb_claim_task '{"task_id":"t-abc123","agent_id":"fixer"}'

Tools

Tool	Description
`bb_register_agent`	Register an agent with ID, name, and capabilities
`bb_list_agents`	List all registered agents
`bb_post_finding`	Store a finding (markdown front‑matter) on the blackboard
`bb_get_finding`	Retrieve a finding by its ID
`bb_query_findings`	Query findings by topic, agent, severity, etc.
`bb_search_findings`	Semantic search across finding contents
`bb_acknowledge_finding`	Mark a finding as acknowledged by an agent
`bb_resolve_finding`	Mark a finding as resolved with resolution details
`bb_create_task`	Create a new coordination task
`bb_get_ready_tasks`	List pending tasks with no unmet dependencies
`bb_claim_task`	Claim a pending task for an agent
`bb_update_task`	Update task status, findings, or artifacts
`bb_complete_task`	Mark task as completed and optionally attach results
`bb_fail_task`	Mark task as failed with an error message
`bb_query_tasks`	Query tasks by type, status, assignee, etc.
`bb_create_context`	Create a named context to group work
`bb_get_context_summary`	Generate a markdown summary of a context
`bb_set_context`	Set the active context for subsequent operations
`bb_recent_activity`	Retrieve recent findings and tasks
`bb_stats`	Return blackboard statistics (agents, findings, tasks)
`bb_connections`	Explore graph connections for an entity path

Compaction / Context Recovery

This skill auto-injects a blackboard summary into output.context during OpenCode compaction hooks (experimental.session.compacting and session.compacted).
For broader YAMS memory after compaction, use yams list (replaces the removed yams hook): yams list --owner opencode --since 24h --limit 20 --format markdown with optional --pbi, --task, --phase, --metadata key=value (repeatable), and --match-any-metadata.

Example:

yams list --owner opencode --since 24h --limit 20 --format markdown --metadata phase=checkpoint

Owner / multi-agent convention

When registering agents or writing findings/tasks via this plugin, use the shared owner opencode so multiple agents can read the same YAMS records. Retrieval: yams list --owner opencode ....

Canonical agent registration

bb_register_agent '{"id":"opencode-coordinator","name":"OpenCode Coordinator","capabilities":["coordination","routing","summary"]}'

Example Workflow

// Agent A registers and posts a security finding
bb_register_agent({ id: "scanner", name: "Scanner", capabilities: ["security"] })
bb_post_finding({
  agent_id: "scanner",
  topic: "security",
  title: "SQL Injection in auth.ts",
  severity: "high",
  confidence: 0.96,
  content: "Unsanitized user input reaches SQL query...",
})

// Agent B discovers the finding and creates a remediation task
bb_search_findings({ query: "SQL injection" })
bb_create_task({
  title: "Fix SQL injection",
  type: "fix",
  created_by: "coordinator",
  priority: 0,
})

// Agent B claims and works on the task
bb_claim_task({ task_id: "t-123", agent_id: "fixer" })
bb_update_task({ task_id: "t-123", status: "working" })
bb_complete_task({ task_id: "t-123", findings: ["f-xyz"] })

// Resolve the original finding
bb_resolve_finding({ finding_id: "f-abc", agent_id: "fixer", resolution: "Parameterized queries added" })

Development

The TypeScript implementation lives in blackboard.ts. Building the plugin:

bun install
bun run build

Run tests with bun test.

For more details see the plugin’s README.md and the YAMS skill definition at docs/skills/yams/SKILL.md.