Skills System

Skills System#

The Skills System extends agent capabilities with specialized knowledge and workflows using openskills. Skills are modular, self-contained packages that provide domain-specific guidance and tools.

Overview#

Skills transform agents from general-purpose to specialized agents with:

Domain Knowledge: Specialized expertise (e.g., PDF manipulation, spreadsheet analysis)
Workflow Guidance: Step-by-step procedures for complex tasks
Tool Integration: Pre-configured toolchains for specific domains
Filesystem-Based: Transparent, version-controllable approach

When enabled, agents can invoke skills via bash commands to access domain-specific guidance.

Note

Skills complement MCP tools but work via filesystem instead of MCP protocol. This provides better transparency and allows skills to be version-controlled.

Important

Model Recommendations: Skills work best with frontier models (Claude Sonnet/Opus, GPT-5). Smaller models like gpt-5-mini and gpt-5-nano may not reliably recognize when to invoke skills or may skip skill invocation in favor of attempting tasks directly.

Installation#

Install openskills and Anthropic’s skills collection:

# Install openskills CLI
npm install -g openskills

# Install Anthropic's skills collection
openskills install anthropics/skills --universal -y

This creates .agent/skills/ directory with all available skills.

Note

Skills work with both Docker mode (command_line_execution_mode: "docker") and local mode (command_line_execution_mode: "local").

Docker mode: Skills and dependencies (ripgrep, ast-grep) are pre-installed in the container
Local mode: You need to install dependencies manually (brew install ripgrep ast-grep on macOS)

Configuration#

Basic Configuration#

Enable skills in your YAML config:

agents:
  Agent1:
    backend_name: "Anthropic"
    backend_params:
      model: "claude-sonnet-4"
      # REQUIRED: Skills need command line access
      enable_mcp_command_line: true
      command_line_execution_mode: "docker"  # or "local"

orchestrator:
  coordination:
    # Enable skills system
    use_skills: true

    # Optional: Skills directory (default: .agent/skills)
    skills_directory: ".agent/skills"

Important

Skills require command line execution (enable_mcp_command_line: true) to be enabled for at least one agent.

With Task Planning#

Combine skills with task planning (filesystem mode):

orchestrator:
  coordination:
    use_skills: true
    enable_agent_task_planning: true
    task_planning_filesystem_mode: true  # Save tasks to tasks/ directory

This creates a tasks/ directory in the agent workspace:

agent_workspace/
  └── tasks/
      └── plan.json        # Task planning state

With Memory System#

Combine skills with filesystem-based memory:

orchestrator:
  coordination:
    use_skills: true
    enable_memory_filesystem_mode: true

This creates a two-tier memory structure:

agent_workspace/
  └── memory/
      ├── short_term/      # Auto-injected into system prompts
      └── long_term/       # Load on-demand via MCP tools

Complete Setup (All Features)#

For full coordination capabilities:

orchestrator:
  coordination:
    use_skills: true
    enable_agent_task_planning: true
    task_planning_filesystem_mode: true
    enable_memory_filesystem_mode: true

This creates:

agent_workspace/
  ├── memory/
  │   ├── short_term/
  │   └── long_term/
  └── tasks/
      └── plan.json

Built-in Skills#

MassGen includes built-in skills bundled in massgen/skills/:

file-search - Fast text and structural code search (ripgrep/ast-grep)
serena - Symbol-level code understanding using LSP
semtools - Semantic search using embeddings

All skills are invoked the same way using openskills read <skill-name>.

Note

Lightweight Guidance: When command execution is enabled, agents automatically receive lightweight file search guidance (~30 lines) in their system prompt. For comprehensive documentation, invoke: openskills read file-search

File Search#

Fast text and structural code search using ripgrep and ast-grep.

Lightweight Guidance (Always Available):

When command execution is enabled, agents automatically see basic usage:

# Text search with ripgrep
rg "pattern" --type py --type js

# Structural search with ast-grep
sg --pattern 'function $NAME($$$) { $$$ }' --lang js

Full Skill Content:

# Load comprehensive 280-line guide with targeting strategies
openskills read file-search

Best for:

Finding code patterns
Analyzing codebases
Refactoring workflows
Fast keyword searches

Serena#

Symbol-level code understanding using Language Server Protocol (LSP). Provides IDE-like capabilities for finding symbols, tracking references, and making precise code edits.

Prerequisites:

# Use uvx to run serena on-demand (no permanent installation)
uvx --from git+https://github.com/oraios/serena serena --help

# Works in both Docker mode (uv pre-installed) and local mode
# For local mode, install uv first: curl -LsSf https://astral.sh/uv/install.sh | sh

Invocation:

# Load serena skill guidance
openskills read serena

Core Capabilities:

find_symbol: Locate class, function, or variable definitions
find_referencing_symbols: Find all locations where a symbol is used
insert_after_symbol: Make precise code insertions at symbol level

Usage:

# Read skill guidance
openskills read serena

# Find symbol definitions (after reading skill)
serena find_symbol --name 'UserService' --type class

# Find all references
serena find_referencing_symbols --name 'authenticate'

# Insert code at symbol location
serena insert_after_symbol --name 'MyClass' --type class --code '...'

Best for:

Understanding symbol relationships and dependencies
Impact analysis before refactoring
Precise code insertions at symbol level
Tracking all usages of functions/classes
Working with large, complex codebases

Supported Languages:

Python, JavaScript, TypeScript, Rust, Go, Java, C/C++, C#, Ruby, PHP, and 20+ more languages through LSP.

Semtools Skill#

Semantic search using embedding-based similarity matching. Find code by meaning, not just keywords.

Prerequisites:

# Install via npm (recommended)
npm install -g @llamaindex/semtools

# Or via cargo
cargo install semtools

# Optional: For document parsing (PDF, DOCX, PPTX)
export LLAMA_CLOUD_API_KEY="your-key"

Invocation:

# Load semtools skill guidance
openskills read semtools

Core Capabilities:

Semantic Search: Find code by meaning, not exact keywords
Workspace Management: Cache embeddings for fast repeated searches
Document Parsing: Convert PDFs, DOCX, PPTX to searchable text (optional)

Usage:

# Read skill guidance
openskills read semtools

# Semantic search by concept (after reading skill)
search "authentication logic" src/

# Search with more results
search "error handling" --top-k 10 --n-lines 5

# Create workspace for large codebases
workspace use my-project
export SEMTOOLS_WORKSPACE=my-project

# Parse documents (requires API key)
parse research_papers/*.pdf

Best for:

Finding code when you know the concept but not the keywords
Discovering semantically similar implementations
Searching across different terminology/languages
Document analysis and research
Exploratory code discovery

Note:

Semantic search works locally without API keys
Document parsing (PDF/DOCX) requires LlamaIndex Cloud API key
Embeddings are computed locally using model2vec

Choosing Between Search Tools#

MassGen provides three complementary search approaches:

Tool	Search Type	Best For	Example
file-search \| Text/Syntax (ripgrep/ast-grep)\|		Exact keywords, code patterns	Find “LoginService” class
serena	Symbols/References	Finding definitions, tracking usage	Track all uses of authenticate()
semtools	Semantic/Meaning	Concept discovery, similar code	Find “rate limiting” implementations

Search Strategy:

Concept Discovery: Use semtools to find relevant areas
Symbol Tracking: Use serena to track precise definitions and references
Text Search: Use file-search (ripgrep) for exact keyword follow-up

Example Workflow:

# 1. Discover authentication-related code semantically
search "user authentication" src/

# 2. Find exact class definition
uvx --from git+https://github.com/oraios/serena serena find_symbol --name 'AuthService' --type class

# 3. Track all references
uvx --from git+https://github.com/oraios/serena serena find_referencing_symbols --name 'AuthService'

# 4. Search for specific patterns
rg "AuthService\(" --type py src/

External Skills#

Anthropic Skills Collection#

When you install anthropics/skills, you get access to:

pdf: PDF manipulation toolkit
xlsx: Spreadsheet creation and analysis
pptx: PowerPoint presentation generation
docx: Word document processing
skill-creator: Guide for creating custom skills
And more…

Using External Skills#

Discover available skills:

Agents see skills listed in their system prompt automatically.
Invoke a skill:
```
openskills read pdf
```
This loads the PDF skill’s guidance and instructions.
Follow skill guidance:

The skill content provides step-by-step instructions, examples, and best practices.

Creating Custom Skills#

Follow the skill-creator skill guidance:

openskills read skill-creator

Or create manually:

Create skill directory:
```
mkdir .agent/skills/my-skill
```

Create SKILL.md with YAML frontmatter:

---
name: my-skill
description: Brief description of what this skill does
---

# My Skill

Detailed guidance and instructions...

Skill is automatically discovered when use_skills: true

How Skills Work#

Discovery#

When use_skills: true:

MassGen scans .agent/skills/ (external) and massgen/skills/ (built-in)
Parses SKILL.md files for metadata
Builds skills table in agent system prompt

Skills Table#

Agents see available skills in their system prompt:

<skills_system priority="1">

## Available Skills

<available_skills>

<skill>
<name>pdf</name>
<description>PDF manipulation toolkit...</description>
<location>project</location>
</skill>

<skill>
<name>file-search</name>
<description>Fast text and structural code search...</description>
<location>builtin</location>
</skill>

</available_skills>

</skills_system>

Invocation#

Agents invoke skills using bash:

openskills read <skill-name>

This loads the skill’s full content and guidance.

Best Practices#

When to Use Skills#

Use skills when:

Task requires domain-specific knowledge
Workflow is complex and benefits from guidance
Want transparency (filesystem > MCP state)
Multiple agents need to coordinate

Don’t use skills when:

Simple, one-off tasks
MCP tools are sufficient
Command line execution not available

Skill Selection#

Check available skills in the system prompt first
Read skill content before using
Follow skill guidance - they provide best practices
Don’t mix approaches - if using a skill, follow its patterns

Memory Management#

Be selective - only save important information
Use clear names - descriptive filenames
Structured data - JSON for data, Markdown for docs
Clean up - remove outdated memories

File Searching#

Start broad - simple patterns first
Add filters - use file type and directory filters
Use context - -C flag shows surrounding code
Combine tools - ripgrep for text, ast-grep for structure

Troubleshooting#

Skills Not Found#

Error: Skills directory is empty or doesn't exist

Solution:

# Local users: Install openskills
npm install -g openskills
openskills install anthropics/skills --universal -y

# Docker users: Skills should be pre-installed
# If missing, rebuild Docker image

Command Execution Required#

Error: Skills require command line execution

Solution:

Add to agent config:

agents:
  Agent1:
    backend_params:
      enable_mcp_command_line: true
      command_line_execution_mode: "docker"  # or "local"

Skill Not Appearing#

Problem: Installed skill not showing in skills table

Solutions:

Check skills directory path in config
Verify SKILL.md has YAML frontmatter
Check file permissions
Try openskills list to see installed skills

Performance Considerations#

Skill Discovery Cost#

Skills are scanned once at orchestration startup
Minimal overhead for small skill collections
For 50+ skills, consider using specific skills directory

System Prompt Size#

Skills table adds to system prompt length
~100 tokens per skill in the table
Full skill content loaded on-demand via openskills read

Integration with Other Features#

With Filesystem#

Skills work seamlessly with filesystem features:

memory/ for skill-specific memory
temp_workspaces/ for viewing other agents’ skill usage
File tools for creating/reading skill outputs

With MCP Tools#

Skills complement MCP tools:

Use MCP tools for direct actions
Use skills for guidance and workflows
Skills can invoke MCP tools via instructions

With Multi-Turn#

Skills persist across turns:

Memories saved in memory/ available in next turn
Skill outputs visible in temp_workspaces/

Example Workflows#

Complex Refactoring#

# Config: Enable skills with task planning and memory
coordination:
  use_skills: true
  enable_agent_task_planning: true
  task_planning_filesystem_mode: true
  enable_memory_filesystem_mode: true

Agent workflow:

Use file-search skill to find all usages
Store decisions in memory/ for context
Execute refactoring in agent workspace

Multi-Agent Collaboration#

# Config: Skills with memory for cross-agent sharing
coordination:
  use_skills: true
  enable_memory_filesystem_mode: true

Agent collaboration:

Agent 1: Research using external skills, save findings to memory/short_term/
Agent 2: Read Agent 1’s memories from shared reference path (typically temp_workspaces/agent1/memory/)
Agent 2: Build upon findings using same skills

Note

The shared reference path is configurable via agent_temporary_workspace in the orchestrator config. The default is temp_workspaces/ but can be any directory name. Agents see the actual path in their system prompt under “Shared Reference”.

Examples#

massgen/configs/skills/skills_basic.yaml - Basic skills usage
massgen/configs/skills/skills_semantic_search.yaml - Semantic search with serena and semtools
massgen/configs/skills/test_semantic_skills.yaml - Test configuration for semantic skills
massgen/configs/skills/skills_with_task_planning.yaml - With task planning
massgen/configs/skills/skills_organized_workspace.yaml - Organized workspace structure

Skills System

Contents

Skills System#

Overview#

Installation#

Configuration#

Basic Configuration#

With Task Planning#

With Memory System#

Complete Setup (All Features)#

Built-in Skills#

File Search#

Serena#

Semtools Skill#

Choosing Between Search Tools#

External Skills#

Anthropic Skills Collection#

Using External Skills#

Creating Custom Skills#

How Skills Work#

Discovery#

Skills Table#

Invocation#

Best Practices#

When to Use Skills#

Skill Selection#

Memory Management#

File Searching#

Troubleshooting#

Skills Not Found#

Command Execution Required#

Skill Not Appearing#

Performance Considerations#

Skill Discovery Cost#

System Prompt Size#

Integration with Other Features#

With Filesystem#

With MCP Tools#

With Multi-Turn#

Example Workflows#

Complex Refactoring#

Multi-Agent Collaboration#

See Also#

Examples#