oh-my-opencode-slim/src/hooks/filter-available-skills/codemap.md

src/hooks/filter-available-skills/

Responsibility

Implements the skill filtering hook that dynamically filters the <available_skills> block in chat messages based on the current agent's permission rules. This ensures agents only see skills they're authorized to use.

Design

The hook is implemented as an experimental.chat.messages.transform hook that runs just before messages are sent to the API. It does not affect UI display.

Core Components:

• SkillEntry: Represents a single skill with name and XML block
• SkillRule: Permission types ('allow', 'ask', 'deny')
• Permission Rules Cache: Maps agent names to their skill permission rules for performance

Permission Resolution Flow:

1. Agent Detection: Extracts current agent name from message history (defaults to 'orchestrator')
2. Permission Lookup: Retrieves skill rules for the agent from configuration
3. Block Extraction: Uses regex to parse <skill> blocks from <available_skills> XML
4. Filtering: Applies permission rules to each skill entry
5. Reconstruction: Rebuilds the <available_skills> block with only allowed skills

Key Functions:

• getCurrentAgent(): Extracts agent name from message metadata
• extractSkillEntries(): Parses XML skill blocks using regex
• isSkillAllowed(): Evaluates permission rules for a skill
• filterAvailableSkillsText(): Main filtering logic that rewrites the XML block
• createFilterAvailableSkillsHook(): Factory that creates the hook instance

Flow

Message Preparation → Hook Execution → Message Transformation → API Send
                     ↓
            filterAvailableSkillsText()
                     ↓
            Extract skill entries from <available_skills>
                     ↓
            Check each skill against permission rules
                     ↓
            Rebuild XML block with allowed skills only

Detailed Execution Sequence:

1. Hook Creation (createFilterAvailableSkillsHook):

   • Called during plugin initialization
   • Creates a permission rules cache per agent
   • Returns the hook function

2. Hook Execution (experimental.chat.messages.transform):

   • Triggered before each message batch is sent to API
   • Receives the message array with parts
   • Identifies current agent from message metadata
   • Retrieves cached permission rules for that agent

3. Skill Filtering (filterAvailableSkillsText):

   • Scans each message part for <available_skills> XML
   • Extracts individual <skill> blocks using regex
   • For each skill, checks permission rules:
     • Specific skill rule takes precedence
     • Wildcard rule ('*') applies as fallback
   • Reconstructs XML block with only allowed skills
   • Returns "No skills available." if all skills are filtered out

4. Result:

   • Modified messages are sent to API with filtered skill list
   • UI remains unchanged (filtering happens server-side)

Integration

Consumed By:

• Main Plugin: Integrated via src/index.ts plugin initialization
• Configuration System: Depends on src/config/ for agent overrides and skill permissions
• CLI: Uses src/cli/skills.ts for default skill permission definitions

Dependencies:

• @opencode-ai/plugin: Plugin input/output types
• src/config/: Plugin configuration and agent overrides
• src/cli/skills.ts: Default skill permission rules
• OpenCode Core: Injects <available_skills> block globally in messages

Integration Points:

• Message Pipeline: Hooks into experimental.chat.messages.transform lifecycle
• Permission System: Works with disabled_skills and agent-specific skill configurations
• Agent Context: Dynamically adapts to current agent based on message history

Configuration Schema:

• Agent Overrides: Skills can be customized per agent in configuration
• Disabled Skills: Global skill blacklist via disabled_skills config
• Permission Rules: Skill-specific rules override wildcard rules

Example Usage Flow:

User Message → Agent Selection → Skill Filtering → API Request → Response
                     ↓
            filterAvailableSkillsHook runs
                     ↓
            Only authorized skills visible to agent

Performance Considerations

• Permission rules are cached per agent to avoid repeated configuration lookups
• Regex-based parsing is efficient for the relatively small <available_skills> block
• Hook runs only once per message batch, not per message
• No impact on UI rendering performance