Skills

A skill is a composable, versioned procedure an agent can load and execute. Skills are the Equip stage of the harness pipeline: encapsulated methodology and knowledge an agent reaches for only when it is relevant.

#What is a skill

A skill packages a methodology — a way of doing something — that an agent can load when a task calls for it. Skills are the Equip stage of the harness pipeline: reusable, versioned procedures kept separate from any single agent's instructions.

Skills follow progressive disclosure. Only a skill's name and description are visible to the model at the start of a run. The full body is loaded only when the agent decides the skill is relevant, so a large library of skills does not bloat every prompt.

#Skill structure

A skill is a directory containing a SKILL.md file. The directory name is the skill's identity, and it must match the name in the file's frontmatter. The frontmatter declares name and description; the body is the procedure itself.

---
name: research-guidelines
description: Structured research methodology. Use when the agent needs to gather, analyze, and synthesize information from files.
---

When doing research:

1. Read all available files in the data directory before forming conclusions
2. Look for patterns, connections, and contradictions across sources
3. Reference specific files and sections when reporting results
4. Group related findings together by topic
5. Cross-reference information across multiple sources when possible

Present findings as:
- Brief summary of the research scope
- Findings organized by topic with direct quotes or data points
- Key takeaways and any unresolved questions

Beyond SKILL.md, a skill directory can carry optional assets the agent loads only when needed:

• scripts/ — executable code the agent can run.
• references/ — reference documents loaded on demand.
• assets/ — templates and lookup data.

#Defining a packaged skill

The directory layout is the normal way to author a skill — the loader assembles it from SKILL.md automatically. For skills constructed inline (tests, synthetic skills), the Platform SDK exposes a definePackagedSkill factory that validates the same frontmatter rules so an invalid skill cannot slip through.

import { definePackagedSkill } from "@kraken-ai/platform";

// The directory loader builds this shape from SKILL.md for you.
// Use the factory for inline / synthetic skills.
const skill = definePackagedSkill(/* AgentSkillPackage */);

#Attaching skills to an agent

An agent declares the skills it can use by importing each skill directory and listing it in the skills array of definePlatformAgent. The import has no file extension — the directory is the identity.

import { definePlatformAgent } from "@kraken-ai/platform";
import filesystem from "../connectors/filesystem";
import researchGuidelines from "../skills/research-guidelines";

export default definePlatformAgent({
  model: "google/gemini-3-flash-preview",
  instructions:
    "You are a research agent. Use the filesystem tools to read and analyze files. Follow the research-guidelines skill for methodology.",
  skills: [researchGuidelines],
  connectors: [filesystem],
});

At run time the agent sees only the skill catalog — names and descriptions. It loads research-guidelines in full only when it decides the methodology applies. See Agents for the rest of the configuration.

#Governance over skills

Skills are governed like every other resource an agent touches. Loading a skill body, a reference file, a script, or an asset is a mediated action: access can be policy-controlled, and every load is recorded in the audit trail alongside the run that requested it.

That means a skill is not implicitly trusted just because it is attached. Policies decide which skills — and which parts of a skill — an agent is allowed to load, the same way they govern connectors and actions. See Governance & Policies.

#Next steps

• Agents — Define an agent, attach skills and connectors, and compose multi-agent teams.
• Connectors — Give agents governed access to data sources, APIs, and MCP servers.
• Governance & Policies — Policy-controlled access to skills, connectors, and actions with full audit.