Skills

A Skill represents a coherent capability an agent can have. Think of it as professional training — it bundles related tools, knowledge sources, and behavioral guidance into a named, reusable entity.

Structure

type Skill struct {
    cortex.Entity
    ID                   id.SkillID
    Name                 string
    Description          string
    AppID                string
    Tools                []ToolBinding
    Knowledge            []KnowledgeRef
    SystemPromptFragment string
    Dependencies         []string
    DefaultProficiency   Proficiency
    Metadata             map[string]any
}

Tool bindings

Each tool binding associates a tool with mastery level and contextual guidance:

type ToolBinding struct {
    ToolName   string      // name of the tool
    Mastery    Proficiency // how well the agent uses this tool
    Guidance   string      // when/how to use it
    PreferWhen string      // conditions that favor this tool
}

Knowledge references

Knowledge references inject context when a skill is active:

type KnowledgeRef struct {
    Source     string // knowledge source identifier
    InjectMode string // how to inject (e.g., "system", "context")
    Priority   int    // injection priority
}

Proficiency levels

Skills use a five-level proficiency system that maps to numeric weights:

Level	Weight	Description
`novice`	0.2	Basic awareness, needs guidance
`apprentice`	0.4	Can use with supervision
`competent`	0.6	Independent usage (default)
`proficient`	0.8	Deep understanding, handles edge cases
`expert`	1.0	Mastery, can teach others

Proficiency weights influence how strongly a skill affects the agent's system prompt and tool selection.

System prompt fragments

Each skill can contribute a fragment to the agent's system prompt:

skill := &skill.Skill{
    Name: "code-review",
    SystemPromptFragment: "You are an expert code reviewer. Focus on correctness, security, and maintainability. Always explain your reasoning.",
}

When a persona includes multiple skills, their fragments are concatenated into the final system prompt.

Dependencies

Skills can declare dependencies on other skills:

skill := &skill.Skill{
    Name:         "security-audit",
    Dependencies: []string{"code-review"},
}

Store interface

type Store interface {
    CreateSkill(ctx context.Context, skill *Skill) error
    GetSkill(ctx context.Context, skillID id.SkillID) (*Skill, error)
    GetSkillByName(ctx context.Context, appID, name string) (*Skill, error)
    UpdateSkill(ctx context.Context, skill *Skill) error
    DeleteSkill(ctx context.Context, skillID id.SkillID) error
    ListSkills(ctx context.Context, filter *ListFilter) ([]*Skill, error)
}

API routes

Method	Path	Description
`POST`	`/cortex/skills`	Create a skill
`GET`	`/cortex/skills`	List skills
`GET`	`/cortex/skills/{name}`	Get a skill by name
`PUT`	`/cortex/skills/{name}`	Update a skill
`DELETE`	`/cortex/skills/{id}`	Delete a skill

Skills

On this page