Skills Plugin

The Skills Plugin implements the Agent Skills open standard, providing a lightweight portable format for giving the agent reusable capabilities and domain expertise. Skills are invoked via slash commands (e.g., /review, /write-tests).

Overview

The Skills plugin:

Discovers skill definitions from four directory tiers: system (bundled), organization, project, and user
Injects an <available_skills> block into the agent prompt so it knows which skills exist and how to activate them
Intercepts user input to detect slash commands matching skill names
Expands the matched skill's content and appends any user-supplied arguments

Configuration

Basic Configuration

plugins:
  - module: codumentor.plugins.skills
    class: SkillsPlugin
    args:
      enabled: true
      skill_dirs:
        - skills/           # Relative to config file directory

Full Configuration

plugins:
  - module: codumentor.plugins.skills
    class: SkillsPlugin
    args:
      enabled: true
      builtin_enabled: true           # Load bundled system skills (default: true)
      project_skills_enabled: true    # Load skills from .codumentor/skills/ in repos (default: true)
      user_skills_dir: ~/.codumentor/skills  # Personal skills directory
      max_active_skills: 10           # Max skills injected per prompt (default: 10)
      skill_dirs:
        - skills/                     # Organization skill directories
        - /opt/shared-skills
      trust_policy:
        allow_scripts: false          # Allow skill helper scripts (default: false)
        allowed_sources_for_scripts:
          - user
        require_approval_for:
          - organization

Configuration Parameters

Parameter	Type	Default	Description
`enabled`	bool	`true`	Enable/disable the plugin
`builtin_enabled`	bool	`true`	Load skills bundled with Codumentor
`project_skills_enabled`	bool	`true`	Load skills from `.codumentor/skills/` in each indexed repo
`user_skills_dir`	string	`~/.codumentor/skills`	Personal skills directory
`max_active_skills`	int	`10`	Maximum number of skills injected into a single prompt
`skill_dirs`	list	`[]`	Additional organization-level skill directories
`trust_policy`	object	—	Trust settings for skill script execution

Skill Format

A skill is a directory containing a SKILL.md file with YAML frontmatter:

my-review-skill/
├── SKILL.md        # Required: frontmatter + instructions
├── scripts/        # Optional: helper scripts
└── references/     # Optional: reference documents

SKILL.md example:

---
name: review
description: Perform a thorough code review focusing on security and correctness
compatibility: ["codumentor>=1.0"]
license: MIT
---

You are an expert code reviewer. Analyze the provided code for:
1. Security vulnerabilities (injection, auth, secrets)
2. Logic errors and edge cases
3. Performance issues
4. Code style and maintainability

Provide a structured review with severity ratings.

Usage

Activating a Skill

Type a slash command matching a skill name at the start of your message:

/review                    # Activates the 'review' skill
/review src/api.py         # Activates 'review' with an argument
/write-tests MyClass       # Activates 'write-tests' with an argument

When a skill matches, its content is injected as context and the user's arguments are appended. A x-skill-activation-card transcript card shows which skill was activated.

Skill Discovery Priority

Skills are loaded in this order (later sources override earlier ones with the same name):

System — bundled skills shipped with Codumentor
Organization — directories listed in skill_dirs
Project — .codumentor/skills/ inside each indexed repository
User — ~/.codumentor/skills/ (personal skills)

Disabling Skills

Users can disable individual skills via Settings → Agent Skills → Disabled Skills in the Web UI.

UI

The plugin provides a x-skill-activation-card transcript card element that is shown in the conversation when a skill is activated, displaying the skill name, source tier, and description.

Testing

python -m unittest tests.test_skills_plugin -v