feat(plugin): enhance context management and skill invocation (#239 )

* fix(shellcheck): declare and assign separately in router.sh (SC2155)

* feat(plugin): enhance context management and skill invocation

- Update .context-manifest.json to include profile and detailed source information.
- Revise context-scout.md to clarify context root discovery and navigation.
- Modify commands to replace deprecated skills with updated ones (brainstorming → approach, systematic-debugging → debugger).
- Streamline install-context.md for clarity and remove interactive profile selection.
- Improve oac-status.md to provide a more comprehensive status report.
- Add OAC system paths to session-start.sh for better context management.
- Remove obsolete skills and improve documentation for existing commands.

2026-02-23 12:12:29 +00:00

4.3 KiB

Raw Blame History

Standard: Agent YAML Frontmatter

Purpose: Valid OpenCode agent frontmatter structure and common mistakes to avoid
Priority: CRITICAL - Load this before creating or modifying agent files

Core Principle

Agent frontmatter must contain ONLY valid OpenCode fields. All other metadata (id, name, category, tags, dependencies) belongs in .opencode/config/agent-metadata.json.

Why: OpenCode validates frontmatter strictly. Extra fields cause validation errors.

Valid OpenCode Fields

Required

---
name: AgentName                      # Display name
description: "What this agent does"  # When to use
mode: subagent                       # primary, subagent, or all
---

Optional

temperature: 0.1                     # Response randomness (0.0-1.0)
model: anthropic/claude-sonnet-4     # Model override
maxSteps: 50                         # Max iterations
disable: false                       # Disable agent
hidden: false                        # Hide from autocomplete
prompt: "{file:./prompts/custom.txt}" # Custom prompt

tools:                               # Tool access
  read: true
  write: false
  edit: false
  bash: false
  task: false

permission:                          # Permission rules (v1.1.1+)
  "*": "ask"                         # Catch-all (last-match-wins)
  read: "allow"                      # Specific override
  bash:
    "*": "deny"
    "git status*": "allow"
  edit:
    "**/*.env*": "deny"
  task:
    contextscout: "allow"
    "*": "deny"

skills:                              # Skills to load
  - task-management

Complete Example

---
name: TestEngineer
description: Test authoring and TDD agent
mode: subagent
temperature: 0.1
tools:
  read: true
  grep: true
  edit: true
  write: true
  bash: true
  task: true
permission:
  bash:
    "npx vitest *": "allow"
    "pytest *": "allow"
    "sudo *": "deny"
    "*": "deny"
  edit:
    "**/*.env*": "deny"
  task:
    contextscout: "allow"
    "*": "deny"
---

Common Mistakes (Fixed in 18 Agents)

1. Duplicate Keys ❌

tools:
  read: true
  read: {"**/*": "allow"}  # ❌ Duplicate key

Fix: Use only one declaration per key

2. Orphaned List Items ❌

tools:
  read: true
  - write: false  # ❌ No parent key

Fix: Proper YAML structure (no orphaned items)

3. Wrong Field Names ❌

permissions:  # ❌ Deprecated - use 'permission' (singular)
  bash:
    "*": "deny"

Fix: Use correct field name permission: (singular, v1.1.1+)

4. Extra Delimiter Blocks ❌

---
name: MyAgent
---
# Content
---  # ❌ Extra delimiter
More content

Fix: Only one --- block at top

5. Invalid OpenCode Fields ❌

---
id: my-agent          # ❌ Not valid
category: development # ❌ Not valid
type: agent           # ❌ Not valid
version: 1.0.0        # ❌ Not valid
tags: [coding]        # ❌ Not valid
dependencies: []      # ❌ Not valid

Fix: Move to .opencode/config/agent-metadata.json:

{
  "agents": {
    "my-agent": {
      "id": "my-agent",
      "category": "development",
      "type": "agent",
      "version": "1.0.0",
      "tags": ["coding"],
      "dependencies": []
    }
  }
}

Validation Checklist

Only valid OpenCode fields?
No duplicate keys?
No orphaned list items?
Correct field names (permission not permissions)?
Only one --- delimiter at top?
Metadata moved to agent-metadata.json?
Valid YAML syntax?

Validation Commands

# Check YAML syntax
yq eval '.opencode/agent/category/agent.md' > /dev/null

# Find duplicate keys
grep -A 50 "^---$" agent.md | grep -E "^[a-z_]+:" | sort | uniq -d

# List all frontmatter keys
grep -A 50 "^---$" agent.md | grep -E "^[a-z_]+:" | cut -d: -f1

Valid keys: name, description, mode, temperature, model, maxSteps, disable, hidden, prompt, tools, permission, skills

Agent Metadata: core-concepts/agent-metadata.md
Subagent Structure: standards/subagent-structure.md
Adding Agents: guides/adding-agent.md
OpenCode Docs: https://opencode.ai/docs/agents/

Last Updated: 2026-01-31 | Version: 1.0.0

4.3 KiB Raw Blame History