Skills

What is a Skill?

A Skill is a markdown file with frontmatter that extends an agent’s behavior at runtime. Skills can:

• Add system prompt instructions
• Restrict which tools the agent can use
• Override the LLM model
• Auto-register RAG buckets as tools
• Enforce policies (allowed/blocked tools, constraints)

Skill File Format

Skills are markdown files with YAML frontmatter:

---
name: customer-support
description: Handle customer support inquiries using the knowledge base
model: gpt-4o-mini
allowed-tools:
  - rag_search
  - web_search
blocked-tools:
  - send_email
rag: support-docs
---

You are a customer support agent. Always be polite and helpful.
Search the knowledge base before answering questions.

Frontmatter Fields

Field	Type	Required	Description
name	string	Yes	Kebab-case identifier (1-64 chars)
description	string	Yes	What this skill does (1-1024 chars)
model	string	No	Override LLM model for this skill
allowed-tools	string[]	No	Only these tools are available
blocked-tools	string[]	No	These tools are blocked
procedures	string[]	No	Procedure names (policy enforcement)
constraints	string[]	No	Constraint descriptions (policy enforcement)
rag	string	No	Bucket name — auto-registers as RAG tool

Loading Skills

Use SkillLoader to load skills from a directory:

import { Agent, loadSkills } from "@schift-io/sdk";

const loader = await loadSkills("./skills");

const agent = new Agent({
  name: "Support Bot",
  instructions: "You are a helpful assistant.",
  skills: {
    loader,
    autoResolve: true, // auto-select best skill per query
  },
  transport: schift.transport,
});

Auto-Resolution

When autoResolve is true (default), the agent automatically selects the best matching skill for each user query based on keyword overlap with skill names and descriptions.

When a skill is resolved:

1. Its markdown body is appended to the agent’s instructions
2. The tool set is filtered to the skill’s allowed-tools / blocked-tools
3. The LLM model is overridden if the skill specifies one
4. If the skill has a rag field and a transport is available, a RAG tool is auto-registered

Manual Skill Access

import { SkillLoader } from "@schift-io/sdk";

const loader = new SkillLoader("./skills");
const summaries = await loader.loadAll();
// [{ name: "customer-support", description: "..." }, ...]

const skill = await loader.get("customer-support");
console.log(skill.meta);  // SkillFrontmatter
console.log(skill.body);  // Markdown body

Policy Engine

When a skill is active, the PolicyEngine enforces its tool restrictions:

• Before tool call: blocks tools not in allowed-tools or listed in blocked-tools
• After tool call: can validate tool results (extensible)

Policy violations are emitted as policy_violation events:

agent.on("policy_violation", (event) => {
  console.warn(`Blocked: ${event.reason} (skill: ${event.skillName})`);
});

Directory Structure

skills/
  customer-support.md
  legal-qa.md
  research/
    deep-research.md

The loader recursively finds all .md files. Duplicate skill names across files cause an error.