> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypertic.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

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

```python theme={null} theme={null}
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):

```python theme={null} theme={null}
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

```yaml theme={null}
---
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

| File           | Purpose                                         |
| -------------- | ----------------------------------------------- |
| `tools.py`     | Defines tool/toolkit objects the skill can use. |
| `REFERENCE.md` | Reference material (APIs, schemas).             |
| `EXAMPLES.md`  | Extra 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).