Skip to main content
Skills are modular, filesystem-based capabilities that extend what your agent can do. Each skill packages instructions, metadata, and optional resources (scripts, reference docs, or tools) that the agent uses when relevant to the request. Unlike one-off prompts, skills are loaded from the filesystem and can be reused across conversations. They let you turn a general-purpose agent into a specialist for specific domains, e.g. financial analysis, document workflows, or custom procedures, without repeating the same guidance every time.

​
Why use Skills

  • Specialize the agent – Add domain-specific instructions and workflows (e.g. financial ratios, report templates).
  • Reduce repetition – Define once in a skill; the agent picks it up automatically when the task matches.
  • Compose capabilities – Combine multiple skills and tools for complex workflows.

​
Using Skills

Pass a list of skill names to the agent. Skills are resolved from the filesystem (./skills). You can also restrict which skills are active for a given run with RunOptions(enabled_skills=...).

​
Agent configuration

import asyncio
from dotenv import load_dotenv
from hypertic.agents import Agent, RunOptions
from hypertic.models import OpenAIChat

load_dotenv()

agent = Agent(
    model=OpenAIChat(model="gpt-5.2"),
    tools=[],  # add any toolkits your skills need, e.g. a file loader
    skills=["financial"],
)

​
Run Agent with skills

Use RunOptions(enabled_skills=[...]) to enable only certain skills for a single run (e.g. when streaming): 
async for event in agent.astream(
    "Calculate financial ratios from the file",
    options=RunOptions(enabled_skills=["analyzing-financial-statements"]),
):
    if event.type == "content":
        print(event.content, end="", flush=True)
    elif event.type == "tool_calls":
        print(f"\nTool calls: {event.tool_calls}")
If your skill needs data from a file, pass a tool that provides it (e.g. a file-loading toolkit) in tools; the skill’s instructions tell the agent how to use that data.

​
Skill structure

Every skill must have a SKILL.md file with YAML frontmatter and a body. Optional files include tools.py, REFERENCE.md, and EXAMPLES.md.

​
Required: SKILL.md

---
name: your-skill-name
description: Brief description of what this skill does and when to use it
---
# Your Skill Name

## Instructions
Step-by-step guidance for the agent.

## Examples
Concrete examples of using this skill.
  • name – Required. Lowercase letters, numbers, and hyphens only; max 64 characters. Used as the skill identifier (e.g. in skills=["your-skill-name"]).
  • description – Required. Short summary of the skill’s purpose and when it should be used; max 1024 characters.
Optional frontmatter supported in the implementation includes version and tags.

​
Optional files

FilePurpose
tools.pyDefines tool/toolkit objects the skill can use.
REFERENCE.mdReference material (APIs, schemas).
EXAMPLES.mdExtra examples.
Example layout: 
financial/
├── SKILL.md
├── REFERENCE.md
├── EXAMPLES.md
└── tools.py

​
Security considerations

Skills give the agent instructions and can bundle code (e.g. in tools.py) and reference data. Only use skills from sources you trust (your own or vetted internal ones).

​
Next steps

  • Add a skill under ~/.hypertic/skills or ./skills with a valid SKILL.md, then reference it in Agent(skills=[...]).
  • Use RunOptions(enabled_skills=[...]) when you want only specific skills active for a run (e.g. streaming).