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.