Skip to content

Agentic Skills

A skill is packaged know-how that an agent loads when a task calls for it, instead of carrying every instruction in its prompt all the time. AgentGr.id supports two kinds:

Subjective skills Objective skills
What it is Natural-language instructions and reference material A procedure written in a JSON DSL
Run by The LLM, which reads and follows the instructions The SkillInterpreter, step by step
Behavior Flexible, judgement-based Deterministic, inspectable, testable
Good for Style guides, review checklists, domain playbooks Calculations, validations, fixed multi-step procedures that call tools
File SKILL.md (+ resources) skill.json

Both kinds are versioned and shared through the skill store. Everything on this page is in the agents_skills package (libs/agents-skills):

pip install ./libs/agents-skills          # add [yaml] for full YAML front matter, [s3] for the S3 store

Subjective Skills

Writing a Skill

A subjective skill is a folder with a SKILL.md file. The front matter says what the skill is for; the body says how to do it:

contract-review/
├── SKILL.md
└── checklist.md          # optional resources (.md, .txt, .json, .yaml, .csv)
---
name: contract-review
description: Review a commercial contract for risky clauses and missing terms.
version: 1.2.0
tags: [legal, review]
---
# Contract review

1. Identify the parties, term, governing law and termination rights.
2. Flag unlimited liability, one-sided indemnities and auto-renewal.
3. Check every item in checklist.md and report missing ones.
4. Answer with a table: clause, risk (low/medium/high), recommendation.

name and description are required. The description is what the agent sees before it decides to use the skill, so write it as "when to use this".

Using Skills in an Agent

from agents_skills import SkillLibrary

class LegalAgent:
    def __init__(self, subject, context):
        self.context = context
        self.skills = SkillLibrary()
        self.skills.load_dir("/app/skills")             # every sub-folder with a SKILL.md

    def on_preprocess(self, task):
        return [task]

    def on_data(self, task):
        question = task.job_data["question"]
        skill = self.skills.select(question)            # keyword match; see below for LLM selection
        system = "You are a careful legal assistant."
        if skill:
            system += "\n\n" + self.skills.render([skill.name], include_resources=True)
        answer = self.llm.chat_completions(
            session_id=task.task_id, name="default", data={},
            messages=[{"role": "system", "content": system}, {"role": "user", "content": question}])
        return AgentResult(task_id=task.task_id,
                           job_output={"answer": answer["choices"][0]["message"]["content"],
                                       "skill": skill.name if skill else None})
SkillLibrary method Description
load_dir(root) / add(skill) / load_from_store(store, names=None) Load skills
describe() / catalogue_prompt() Short catalogue (name, description, tags), or the same as prompt text, to show the model before a skill is chosen
search(query, limit=3) Keyword ranking over name, tags and description
select(query, selector=None) Best skill for a query. selector can be an agents_llm SelectionEngine, or a function (query, skills) -> name
render(names, include_resources=False) Full instructions of the chosen skills, ready for a system prompt

Choosing with an LLM: skills implement id and get_searchable_representation(), so they work directly with the model-based SelectionEngine:

engine = client.create_selector(name="openai", base_query="Select the skill that best fits the request.")
skill = self.skills.select(question, selector=engine)

Alternatively, put catalogue_prompt() in the system prompt and let the model request a skill by name, then call render([...]) and continue the conversation.


Objective Skills

An objective skill is a procedure in JSON. The interpreter runs its steps in order, so the same input always produces the same, inspectable run.

{
  "kind": "objective",
  "name": "invoice-check",
  "version": "1.0.0",
  "description": "Validate an invoice, total its lines and explain totals above the approval limit.",
  "tags": ["finance"],
  "inputs": {
    "invoice": { "required": true },
    "limit":   { "default": 1000 }
  },
  "steps": [
    { "id": "lines", "op": "call", "handler": "extract_lines", "args": { "doc": "${inputs.invoice}" } },
    { "id": "has_lines", "op": "assert",
      "condition": { "left": "${steps.lines}", "op": "not_empty" }, "message": "invoice has no lines" },
    { "id": "amounts", "op": "foreach", "items": "${steps.lines}", "as": "line",
      "steps": [ { "id": "amount", "op": "set", "value": "${vars.line.amount}" } ] },
    { "id": "total", "op": "call", "handler": "sum", "args": { "values": "${steps.amounts}" } },
    { "id": "note", "op": "if",
      "condition": { "left": "${steps.total}", "op": "gt", "right": "${inputs.limit}" },
      "then": [ { "id": "why", "op": "llm",
                  "prompt": "In one sentence, explain to an approver why an invoice of ${steps.total} needs review." } ],
      "else": [ { "id": "why", "op": "template", "template": "Total ${steps.total} is within the limit." } ] }
  ],
  "output": { "total": "${steps.total}", "note": "${steps.why}" }
}

Operations

op Fields Result
call handler, args Return value of the registered handler
llm prompt or messages, optional "parse": "json" Model reply (text, or parsed JSON)
set value The resolved value
template template The interpolated string
if condition, then, else Output of the last step of the branch that ran
foreach items, as (default item), steps List of each iteration's last step output. The current element is ${vars.<as>}, its index ${vars.<as>_index}
assert condition, message Stops the run with SkillAssertionError if false

References: ${inputs.<name>}, ${steps.<id>} and ${vars.<name>}, with dotted paths and list indexes (${steps.lines.0.amount}). A value that is exactly one reference keeps its type (number, list, object). References inside longer text are interpolated as text.

Conditions: {"left": ..., "op": ..., "right": ...} with eq, ne, gt, ge, lt, le, in, not_in, contains, truthy, falsy, empty or not_empty.

Inputs: each declared input may be required or have a default. The output template builds the result. Without one, the output of the last step is returned.

Running an Objective Skill

from agents_skills import ObjectiveSkill, SkillInterpreter

interp = SkillInterpreter(
    handlers={
        "extract_lines": lambda doc: doc["lines"],
        "sum": lambda values: sum(values),
    },
    llm=SkillInterpreter.llm_from_client(client, name="openai"),   # used by "llm" steps
)

skill = ObjectiveSkill.from_json(open("invoice-check/skill.json").read())   # validates the spec
run = interp.run(skill, {"invoice": invoice})

run.output        # {"total": 1240, "note": "..."}
run.steps         # output of every step, by id
run.trace         # [{"id": "lines", "op": "call", "ms": 0.4}, ...]

Handlers can be any Python callable: SDK tools, functions from the Tools & Functions registry, generated code (GeneratedTool(...).as_handler()), or calls to other agents through context.delegator.

Error Raised when
SkillValidationError The spec is malformed (unknown op, duplicate step id, missing fields) or a required input is missing
SkillAssertionError An assert step fails. .step_id names the step
SkillExecutionError A handler or model call fails, a reference is missing, or the run exceeds max_steps (default 1000)

The Skill Store

The skill store keeps every version of every skill and lets agents discover them. It works on a local directory or on the Persistent Store:

from agents_skills import SkillStore, LocalBackend, S3Backend, SubjectiveSkill, ObjectiveSkill
from agent_core_libs.storage import S3Storage

store = SkillStore(S3Backend(S3Storage(access_key_id="...", secret_access_key="...",
                                       region_name="us-east-1"), "agent-skills"))
# or, for development / a shared volume:
store = SkillStore(LocalBackend("/data/skills"))

store.publish(SubjectiveSkill.from_dir("skills/contract-review"), publisher="legal-team")
store.publish(ObjectiveSkill.from_json(open("invoice-check/skill.json").read()))

store.list()                              # latest version of every skill (metadata)
store.search("contract", tags=["legal"])  # by text and tags
store.versions("invoice-check")           # ["1.0.0", "1.1.0"]
skill = store.get("invoice-check")        # latest; or store.get("invoice-check", "1.0.0")
Method Description
publish(skill, overwrite=False, publisher=None) Store a version. Publishing an existing version raises SkillExistsError unless overwrite=True
get(name, version=None) Load a skill (latest version by default)
versions(name) / latest_version(name) Versions, sorted numerically (1.10.0 after 1.9.0)
list(kind=None, latest_only=True) Metadata: name, kind, version, description, tags, published_at, publisher
search(text="", tags=None, kind=None) Find skills by words and required tags
delete(name, version) Remove one version

Skill names are lowercase letters, digits, ., _ and -. Storage layout: skills/<kind>/<name>/<version>/ with SKILL.md and res/ (subjective) or skill.json (objective), plus meta.json.

Load subjective skills from the store at start-up with SkillLibrary().load_from_store(store). Skills that the Learner promotes to its Skills bin can be published to the store the same way.