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

# Skills Overview

> Pre-packaged tool bundles and learned behaviors for agents.

# Skills

Skills are pre-packaged bundles of tools and instructions that give agents domain expertise.

## Quick Start

```typescript theme={null}
import { Agent, loadSkill, openai } from "@agentium/core";

const agent = new Agent({
  name: "assistant",
  model: openai("gpt-4o"),
  skills: [
    "./skills/shipping",           // local directory
    "@agentium/skill-crm",         // npm package
    "https://skills.example.com/analytics", // remote URL
  ],
});
```

## Skill Sources

### Local Directory

A directory with a `skill.json` manifest and tool modules:

```
skills/shipping/
  skill.json
  tools.ts
  instructions.md
```

```json theme={null}
// skill.json
{
  "name": "shipping",
  "description": "Shipping rate calculation and tracking",
  "version": "1.0.0",
  "main": "tools.ts",
  "instructions": "instructions.md"
}
```

```typescript theme={null}
// tools.ts
import { defineTool } from "@agentium/core";
import { z } from "zod";

export function getTools() {
  return [
    defineTool({
      name: "calculate_shipping_rate",
      description: "Calculate shipping cost",
      parameters: z.object({
        weight: z.number(),
        destination: z.string(),
      }),
      execute: async (args) => {
        // calculation logic
        return `$${(args.weight * 0.5).toFixed(2)}`;
      },
    }),
  ];
}
```

### npm Package

Any npm package that exports tools:

```typescript theme={null}
skills: ["@agentium/skill-crm"]
```

The package must export `getTools()`, `tools`, or a default export returning tool definitions.

### Remote URL

A hosted skill with a `skill.json` manifest:

```typescript theme={null}
skills: ["https://skills.example.com/analytics"]
```

The remote server must serve `skill.json` and the main module at the specified paths.

## Creating a Skill Object

You can also pass pre-built `Skill` objects directly:

```typescript theme={null}
import type { Skill } from "@agentium/core";

const mySkill: Skill = {
  name: "custom",
  description: "Custom skill",
  version: "1.0.0",
  tools: [/* ToolDef[] */],
  instructions: "Use these tools when...",
};

new Agent({ model, skills: [mySkill] });
```

## Lazy Loading

Skills are loaded on the first `run()` or `connect()` call, not at construction time. This avoids blocking agent creation with slow I/O operations.

## Skill Instructions

If a skill has an `instructions` field, it's automatically injected into the system prompt:

```
[Skill: shipping]
Use the calculate_shipping_rate tool when the user asks about shipping costs.
Always ask for weight and destination before calculating.
```