Per Agent Skills

Filter OpenCode skills on a per-agent basis using configurable allowlists and blocklists.

Prevent skill leakage, enforce agent roles, and keep your system prompt clean.

Installation

Add to your OpenCode config:

// opencode.jsonc
{
  "plugin": ["@howaboua/opencode-per-agent-skills@latest"],
}

Using @latest ensures you always get the newest version automatically when OpenCode starts.

Restart OpenCode. The plugin will automatically start filtering skills based on your configuration.

Configuration

The plugin uses its own config file:

• Global: ~/.config/opencode/per-agent-skills.jsonc, created automatically on first run.

{
  // ===========================================================================
  // OpenCode Per-Agent Skills Configuration
  // ===========================================================================

  // 1. Global Filtering (Applies to ALL agents)
  "global": {
    // Skills to show to EVERY agent (overrides agent-specific excludes)
    // "include": ["basic-file-ops"],
    // Skills to hide from EVERY agent
    // "exclude": ["deprecated-skill"]
  },

  // 2. Per-Agent Configuration
  "agents": {
    // Example: Restricted "compaction" agent
    "compaction": {
      "include": ["git-release", "code-summary"],
      "exclude": ["code-modification"],
    },

    // Example: Broad "exploration" agent
    "exploration": {
      "include": ["*-analysis", "*-docs", "file-discovery"],
      "exclude": ["git-push"],
    },
  },

  // 3. Metadata Filters (Advanced)
  "metadataFilters": {
    "category": {
      "review": {
        "include": ["security", "linting"],
      },
    },
  },

  // 4. Debugging
  "verbose": false,
}

Features

• Per-Agent Filtering: Define specific allowlists (include) and blocklists (exclude) for each agent.
• Global Rules: Set baseline rules that apply to all agents.
• Wildcard Support: Use git-*, *-analysis, or * patterns.
• Metadata Filtering: Filter skills based on frontmatter metadata in their SKILL.md files.
• Safe Defaults: If no config exists, all skills are shown.

How It Works

1. Intercept: The plugin hooks into experimental.chat.system.transform.
2. Identify: It determines the current agent from the active session.
3. Filter: It filters the <available_skills> XML block in the system prompt based on your configuration.

Development

To install from source for development:

1. Clone the repository:

   git clone https://github.com/IgorWarzocha/Opencode-per-agent-skills-plugin.git
   cd Opencode-per-agent-skills-plugin
   

2. Install dependencies and build:

   bun install && bun run build
   

3. Link in your OpenCode config:

   {
     "plugins": ["/path/to/Opencode-per-agent-skills-plugin"],
   }
   

License

MIT