Skills Service

TL;DR: Skills are reusable capabilities that define what agents can do. Each skill has an id, name, description, tags, and examples. Multiple agents can share the same skills, making it easy to build specialized agents from a common capability library.

The Problem

Agents need to know what they can do. Without structure, each agent would need its own list of capabilities, leading to duplication and inconsistency. When you improve a capability, you would need to update every agent that uses it.

Skills solve this by defining capabilities once and letting multiple agents reference them. A skill like "content_writing" can be used by a blog agent, a documentation agent, and a general assistant. Improvements to the skill benefit all agents that use it.

Skills also help with discovery. Users and other systems can query available skills by tag or category. This makes it possible to find the right agent for a task without knowing every agent's specific capabilities.

How Skills Work

Skills are defined as YAML files in services/skills/. Each skill lives in its own subdirectory with a config.yaml file and a Markdown instruction body (by convention SKILL.md, referenced by the file field). Skills are auto-discovered from services/skills/<id>/config.yaml at startup and ingested into the database. There is no manifest to maintain and no separate sync step.

When an agent is defined, it references skills by id. At runtime, the agent's system prompt includes information about its skills, and the agent can describe what it can do based on its assigned skills.

Skills are metadata plus instructions. The config.yaml describes the capability, and the Markdown file carries the instructions the agent follows. The actual behavior comes from the agent's system prompt, the AI model, and any tools available through MCP servers.

Directory Structure

services/skills/
├── systemprompt_cli/
│   ├── config.yaml                # Skill definition
│   └── SKILL.md                   # Instruction body
└── inspect_agents/
    ├── config.yaml
    └── SKILL.md

Each skill directory contains a config.yaml file defining that skill and a Markdown file with its instructions. The naming convention is snake_case for directories and ids.

Skill Schema

Every skill has these fields:

id: skill_identifier           # Unique identifier (snake_case)
name: "Human Readable Name"    # Display name
description: "What this skill enables"  # Detailed description
enabled: true                  # Whether skill is active
file: SKILL.md                 # Instruction body (defaults to index.md)

tags:                          # Discoverable tags
  - tag1
  - tag2

category: "category_name"      # Optional grouping

Required Fields

• id - Unique identifier in snake_case. This is how agents reference the skill.
• name - Human-readable display name shown in interfaces.
• description - Clear explanation of what this skill enables.

Optional Fields

• enabled - Boolean to activate or deactivate the skill. Defaults to true.
• file - Name of the Markdown instruction file in the skill directory. Defaults to index.md.
• tags - Array of tags for discovery and categorization.
• category - Free-form grouping label.

Creating a Skill

To create a new skill:

1. Create a directory in services/skills/ with your skill id as the name
2. Create config.yaml in that directory with the skill definition
3. Create the instruction file it references (for example SKILL.md)
4. Restart the server; skills are auto-discovered and ingested at startup

Create services/skills/code_review/config.yaml:

id: code_review
name: "Code Review"
description: "Reviews code for bugs, style issues, and improvements"
enabled: true
file: SKILL.md

tags:
  - code
  - review
  - development
  - quality

category: "development"

Then write the instructions in services/skills/code_review/SKILL.md. No manifest edit is needed; the directory is discovered automatically.

Assigning Skills to Agents

Skills are assigned to agents in the agent's configuration file. Each agent lists the skill ids it should have:

# In services/agents/your-agent.yaml
      skills:
        source: explicit
        include:
          - systemprompt_cli
          - inspect_agents
          - code_review
        exclude: []

The agent's system prompt should describe how to use these skills. Each skill's description and instruction file help the AI understand what kinds of requests it handles.

An agent can have any number of skills. More specialized agents might have just one or two skills, while general-purpose agents might have many.

Managing Skills

Use the CLI to manage skills:

# List all skills
systemprompt core skills list

# List only enabled skills
systemprompt core skills list --enabled

# Show skill details
systemprompt core skills show systemprompt_cli

Skills are read from disk and ingested into the database at startup. To change a skill, edit its YAML or Markdown on disk and restart the server.

Template Skills

The template ships with a set of ready-made skills you can use as examples, including:

systemprompt_cli

The systemprompt_cli skill teaches an agent how to drive the systemprompt CLI: discovering commands with --help, inspecting services, and reading logs.

inspect_agents

The inspect_agents skill covers discovering, validating, and messaging the workspace's agents over A2A, then reading the artifacts and traces they produce.

These skills can be modified or disabled. You can also create additional skills tailored to your specific use cases.

Service Relationships

• Agents reference skills by id in their configuration
• Config service auto-discovers skills from services/skills/<id>/config.yaml
• Skills are metadata plus instructions and do not execute code themselves
• Skill tags enable discovery through the CLI and API

CLI Reference

Command	Description
systemprompt core skills list	List configured skills (--enabled / --disabled filters)
systemprompt core skills show <id>	Show skill details

See systemprompt core skills <command> --help for detailed options. Creating, editing, and deleting skills happens on disk under services/skills/; changes are ingested at the next server startup.

Troubleshooting

Skill not appearing in agent -- Verify the skill id in the agent configuration matches the skill definition exactly. Check that the skill is enabled.

Skill not loading -- Check that the skill's config.yaml has valid YAML syntax and includes all required fields. Verify the directory sits directly under services/skills/ and that the file it references exists.

Changes not taking effect -- Skills are ingested at startup. Restart the server after editing skill YAML or instruction files, and check startup logs for validation errors.