Skills

Skills are reusable instruction sets that agents can load dynamically during a conversation. Rather than embedding every possible instruction in an agent's system prompt, skills allow instructions to be modular, maintainable, and shared across agents. An agent sees a skill index in its system prompt and uses the loadSkill tool to fetch detailed instructions when a task requires them.

Overview

The module lives in features/skills/ and provides database-backed skill management, a loadSkill AI SDK tool for runtime loading, prompt injection utilities, markdown import/export, and admin UI for CRUD operations. Skills can be global (available to all tenants) or tenant-scoped.

Key Concepts

SkillRecord -- The database record for a skill:

• slug -- unique identifier (lowercase, alphanumeric + hyphens, 2-64 chars)
• name -- human-readable display name
• description -- optional summary shown in the skill index
• instructions -- the full instruction text loaded into agent context
• category -- organizational grouping (e.g., "analysis", "writing", "general")
• source -- how the skill was created ("manual", "imported", etc.)
• metadata -- arbitrary JSON for additional configuration
• user_invocable -- whether users can request this skill directly in chat
• enabled -- toggle to disable without deleting
• tenant_id -- null for global skills, set for tenant-specific ones

SkillFileRecord -- Skills can have associated files stored via skill_files for reference material.

Skill Resolution -- When looking up a skill by slug, tenant-specific skills take priority over global ones. This allows tenants to override global skills with customized versions.

Agent-Skill Assignment -- Skills are linked to agents via the agent_skills join table with a priority field. Higher-priority skills appear first in the skill index.

How It Works

Skill Index Injection

When an agent's system prompt is built, the buildSkillIndex() function generates a formatted list of available skills:

## Available Skills
You have access to the following skills. Use the `loadSkill` tool with the skill's slug to load its detailed instructions when needed.

- **Data Analysis** (`data-analysis`) -- Structured approach to analyzing datasets
- **Report Writing** (`report-writing`) -- Professional report formatting guidelines

This index tells the agent what skills exist without loading the full instructions. The agent decides when to load a skill based on the current task.

Runtime Loading

The createLoadSkillTool(tenantId) function creates an AI SDK tool that agents call to load skill instructions:

1. Agent calls loadSkill({ slug: "data-analysis" })
2. The tool queries the skills table for the slug (checking both global and tenant-scoped)
3. Returns the skill's name and full instructions
4. Records the invocation in skill_invocations (fire-and-forget)

The agent then incorporates the returned instructions into its reasoning for the current task.

Markdown Import

Skills can be imported from markdown files with YAML frontmatter:

---
slug: data-analysis
name: Data Analysis
description: Structured approach to analyzing datasets
---

Follow these steps when analyzing data:

1. Understand the data structure
2. Identify key metrics
3. Look for patterns and anomalies
...

The importFromMarkdown() function parses the frontmatter (using a built-in YAML parser that handles block scalars, inline lists, and nested mappings), validates the slug format, and returns a SkillImportResult ready for database insertion.

Admin Management

Skills are managed via the Admin > Skills tab:

• SkillAdmin -- top-level admin component
• SkillList -- lists all skills with enable/disable toggles and edit/delete actions
• SkillEditor -- form for creating and editing skills (slug, name, description, instructions, category, user-invocable toggle)
• SkillImport -- file upload for importing markdown skill files

API Reference

Server Actions

Tool Factory

Prompt Utilities

Import

Types

Components

For Agents

Skills are designed specifically for agents. The workflow:

1. Agent sees a skill index in its system prompt listing available skills
2. When a task matches a skill's domain, the agent calls loadSkill(slug)
3. The tool returns the full instructions
4. The agent follows those instructions for the current task

Skills are particularly useful for:

• Standardizing how agents approach specific task types
• Sharing best practices across multiple agents
• Updating agent behavior without modifying system prompts
• Allowing tenant-specific instruction overrides

The user_invocable flag allows users to explicitly request a skill in chat (e.g., "use the data-analysis skill on this dataset").

Related Modules

• Agent System (features/agents/) -- agents reference skills via config and agent_skills table
• Chat (features/chat/) -- loadSkill tool is included in agent tool sets
• Admin -- skill CRUD lives in Admin > Skills tab