# Skills

Load specialized instructions when they are needed.

A skill is a markdown file with YAML frontmatter, a way to ship reusable
instruction packs that load **lazily**. The agent only sees each skill's name
and description in its system prompt. It pulls the full body into context by
calling the `Skill` tool when a request matches.

## Authoring a skill

`skills/commit-message/SKILL.md`:

```markdown
---
name: commit-message
description: Write a conventional commit message for a described change.
---

You write commit messages. Rules:
- Conventional Commits format: type(scope): subject
- Subject in imperative mood, <= 72 chars, no trailing period
- Add a body only when the "why" isn't obvious from the subject
```

A path can be a folder containing `SKILL.md`, or a markdown file directly.

## Loading skills into an agent

```python
from harnessx import Agent, AgentConfig

agent = Agent(
    config=AgentConfig(
        system_prompt=(
            "You are an engineering assistant. When a request matches a "
            "skill in <available-skills>, call the Skill tool first to load "
            "its instructions, then follow them."
        ),
    ),
    skills=["./skills/commit-message", "./skills/code-review"],
)
```

The `skills=` argument accepts a list of paths or a `SkillManager`:

```python
from harnessx import SkillManager

manager = SkillManager.from_paths(["./skills/commit-message"])
agent = Agent(config=AgentConfig(system_prompt="..."), skills=manager)

for s in agent.skills.list():
    print(s.name, "-", s.description)
```

## Reacting to skill invocation

A `SKILL_INVOKED` hook fires when the model loads a skill:

```python
from harnessx import HookContext, HookEvent

async def on_skill(ctx: HookContext):
    if ctx.data.get("found"):
        print(f"loaded skill: {ctx.data['skill']} ({ctx.data['body_chars']} chars)")

agent.hooks.on(HookEvent.SKILL_INVOKED, on_skill)
```

Full demo: `examples/03-skills/skills_interactive.py`, with sample skills under
`examples/skills/`. `examples/03-skills/skills_lazy_loading.py` shows the same
loading with a scripted model and no API key.

Skills carry instructions. To give an agent curated facts with provenance,
load an Open Knowledge Format bundle; see [Knowledge (OKF)](../knowledge/).