Creating Native Skills

Overview

Native skills are written in compiled C# and give you the full power of Rock. A skill is a class that groups related tools together, provides shared instructions to the language model, and can be secured as a unit. This guide covers how to create the skill class and register its tools. For the individual tool patterns (Lookup, List, Get, AddOrUpdate, and so on), see the Native Tools section.

Creating the Skill Class

Create a class that inherits from AgentSkillComponent in the Rock.AI.Agent.Skills namespace. By convention, skills are declared as internal sealed partial class and split across multiple files, with one file per tool. Decorate the class with a few attributes so Rock can discover and describe it. Dependencies such as ILogger<T> are injected through the constructor.

[Description( "This skill provides functionality to manage prayer." )]
[AgentSkillGuid( "0EF2BBFD-52D9-441B-9BE5-F4C5D2B42ED0" )]
[EntityTypeGuid( "6033D65E-C782-45BA-9A74-23F9B9353A27" )]
internal sealed partial class PrayerSkill : AgentSkillComponent
{
    private readonly ILogger _logger;

    public PrayerSkill( ILogger<PrayerSkill> logger )
    {
        _logger = logger ?? throw new ArgumentNullException( nameof( logger ) );
    }
}

• [AgentSkillGuid] - Required. This is the discovery marker. A class without it is never registered as a skill.
• [EntityTypeGuid] - Associates the skill with its entity type.
• [Description] - Administrator-facing description shown while configuring the skill. It is not sent to the language model.
• [AgentSkillName] - Optional. Overrides the skill name. If omitted, the name is derived from the class name.
• [AgentPurpose], [AgentUsage], [AgentGuardrail] - Optional class-level instructions that are sent to the language model. Each can be specified multiple times.

Adding Tools

Each tool is a method on the skill class. Decorate every tool method with an [AgentToolGuid] (this is what registers the method as a tool) and a [Description]. Add any of the optional instruction attributes to guide the model. The method should return an AgentToolResult, which you build with the base-class Success, Error, and NoData helpers. Put a [Description] on each parameter, since parameter descriptions are sent to the model.

[Description( "Lists prayer requests that match the filters." )]
[AgentToolGuid( "99F1EDE0-F431-49BE-80F5-97032710143B" )]
[AgentUsage( "Most filters are optional. If none are provided, the most recent prayer requests are returned." )]
public AgentToolResult ListPrayerRequests(
    [Description( "Optional. The IdKey of the category to filter by." )]
    string categoryIdKey = null,
    int pageNumber = 1 )
{
    var helper = new AgentToolHelper( AgentRequestContext, _logger );

    // Build, filter, and return your results here.
    // See the Native Tools section for the full patterns.

    return NoData();
}

See the Native Tools section for the detailed patterns each kind of tool follows (Lookup, List, Get, AddOrUpdate, AvailableAttributes, Summary, Insights, and Delete), and the Agent Tool Helper article for the helper methods that handle validation, pagination, security, and saving.

Registration

You do not need to wire anything up. At startup Rock reflects over every class that inherits from AgentSkillComponent and carries an [AgentSkillGuid], registers the skill, and registers each method that carries an [AgentToolGuid] as a tool. From there an administrator can add the skill to an agent and secure it.

If your skill needs per-agent options (a default category, a campus, a toggle, and so on), you can expose configuration that administrators set when they add the skill to an agent. See Skill Configuration for details.