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

# Skills Loader

> A complete implementation of a skills system similar to Claude Code, demonstrating the power of `nextTurnParams` for context injection.

## Overview

This example shows how to build encapsulated, self-managing tools that inject domain-specific context into conversations. When a skill is loaded, it automatically enriches subsequent turns with specialized instructions.

## Prerequisites

```bash title="npm" lines theme={null}
npm install @openrouter/agent zod
```

```bash title="pnpm" lines theme={null}
pnpm add @openrouter/agent zod
```

```bash title="yarn" lines theme={null}
yarn add @openrouter/agent zod
```

```bash title="bun" lines theme={null}
bun add @openrouter/agent zod
```

```bash title="deno" lines theme={null}
deno add npm:@openrouter/agent npm:zod
```

Create a skills directory:

```bash lines theme={null}
mkdir -p ~/.claude/skills/pdf-processing
mkdir -p ~/.claude/skills/data-analysis
mkdir -p ~/.claude/skills/code-review
```

## Basic Skills Tool

```typescript expandable lines theme={null}
import { OpenRouter, tool } from '@openrouter/agent';
import { readFileSync, existsSync, readdirSync } from 'fs';
import path from 'path';
import { z } from 'zod';

const openrouter = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
});

const SKILLS_DIR = path.join(process.env.HOME || '~', '.claude', 'skills');

// List available skills
const listAvailableSkills = (): string[] => {
  if (!existsSync(SKILLS_DIR)) return [];
  return readdirSync(SKILLS_DIR, { withFileTypes: true })
    .filter((dirent) => dirent.isDirectory())
    .filter((dirent) => existsSync(path.join(SKILLS_DIR, dirent.name, 'SKILL.md')))
    .map((dirent) => dirent.name);
};

const skillsTool = tool({
  name: 'Skill',
  description: `Load a specialized skill to enhance the assistant's capabilities.
Available skills: ${listAvailableSkills().join(', ') || 'none configured'}
Each skill provides domain-specific instructions and capabilities.`,

  inputSchema: z.object({
    type: z.string().describe("The skill type to load (e.g., 'pdf-processing')"),
  }),

  outputSchema: z.string(),

  // This is where the magic happens - modify context for next turn
  nextTurnParams: {
    input: (params, context) => {
      // Prevent duplicate skill loading
      const skillMarker = `[Skill: ${params.type}]`;
      if (JSON.stringify(context.input).includes(skillMarker)) {
        return context.input;
      }

      // The skill name comes from the model, so only load skills that exist under SKILLS_DIR
      if (!listAvailableSkills().includes(params.type)) {
        return context.input;
      }

      // Load the skill's instructions
      const skillPath = path.join(SKILLS_DIR, params.type, 'SKILL.md');

      const skill = readFileSync(skillPath, 'utf-8');
      const skillDir = path.join(SKILLS_DIR, params.type);

      // Inject skill context into the conversation
      const currentInput = Array.isArray(context.input) ? context.input : [context.input];

      return [
        ...currentInput,
        {
          role: 'user',
          content: `${skillMarker}
Base directory for this skill: ${skillDir}

${skill}`,
        },
      ];
    },
  },

  execute: async (params, context) => {
    const skillMarker = `[Skill: ${params.type}]`;

    // Check if already loaded
    if (JSON.stringify(context?.turnRequest?.input || []).includes(skillMarker)) {
      return `Skill ${params.type} is already loaded`;
    }

    const available = listAvailableSkills();
    if (!available.includes(params.type)) {
      return `Skill "${params.type}" not found. Available skills: ${available.join(', ') || 'none'}`;
    }

    return `Launching skill ${params.type}`;
  },
});
```

```python title="Python" lines theme={null}
import asyncio
import json
import os
from pathlib import Path

from pydantic import BaseModel, Field
from openrouter_agent import OpenRouter, call_model, tool

client = OpenRouter(api_key=os.environ["OPENROUTER_API_KEY"])

SKILLS_DIR = Path.home() / ".claude" / "skills"


# List available skills
def list_available_skills() -> list[str]:
    if not SKILLS_DIR.exists():
        return []
    return [d.name for d in SKILLS_DIR.iterdir() if d.is_dir() and (d / "SKILL.md").exists()]


class SkillInput(BaseModel):
    type: str = Field(description="The skill type to load (e.g., 'pdf-processing')")


# This is where the magic happens - modify context for next turn
# next_turn_params functions receive the raw tool-call arguments as a dict
def next_input(params, context):
    skill_type = params["type"]
    current = context["input"]
    # Prevent duplicate skill loading
    marker = f"[Skill: {skill_type}]"
    if marker in json.dumps(current, default=str):
        return current

    # The skill name comes from the model, so only load skills that exist under SKILLS_DIR
    if skill_type not in list_available_skills():
        return current

    # Load the skill's instructions
    skill = (SKILLS_DIR / skill_type / "SKILL.md").read_text(encoding="utf-8")
    skill_dir = SKILLS_DIR / skill_type

    # Inject skill context into the conversation
    items = current if isinstance(current, list) else [current]
    return [
        *items,
        {
            "role": "user",
            "content": f"{marker}\nBase directory for this skill: {skill_dir}\n\n{skill}",
        },
    ]


def execute(params, ctx):
    marker = f"[Skill: {params.type}]"

    # Check if already loaded
    turn_request = (ctx or {}).get("turn_request") or {}
    if marker in json.dumps(turn_request.get("input", []), default=str):
        return f"Skill {params.type} is already loaded"

    available = list_available_skills()
    if params.type not in available:
        return f'Skill "{params.type}" not found. Available skills: {", ".join(available) or "none"}'

    return f"Launching skill {params.type}"


skills_tool = tool(
    name="Skill",
    description=f"""Load a specialized skill to enhance the assistant's capabilities.
Available skills: {', '.join(list_available_skills()) or 'none configured'}
Each skill provides domain-specific instructions and capabilities.""",
    input_schema=SkillInput,
    next_turn_params={"input": next_input},
    execute=execute,
)


async def main() -> None:
    skills = list_available_skills()
    print("Available skills:", ", ".join(skills) or "none configured")
    skill_name = skills[0] if skills else "pdf-processing"

    result = call_model(
        client,
        {
            "model": "openai/gpt-4o",
            "input": f"Use the Skill tool to load the '{skill_name}' skill, then briefly summarize what it lets you do.",
            "tools": [skills_tool],
        },
    )

    print(await result.get_text())


asyncio.run(main())

```

```go title="Go" lines theme={null}
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"path/filepath"
	"slices"
	"strings"
)

var skillsDir = filepath.Join(os.Getenv("HOME"), ".claude", "skills")

type toolCall struct {
	ID       string `json:"id"`
	Type     string `json:"type"`
	Function struct {
		Name      string `json:"name"`
		Arguments string `json:"arguments"`
	} `json:"function"`
}

type message struct {
	Role       string     `json:"role"`
	Content    any        `json:"content"`
	ToolCalls  []toolCall `json:"tool_calls,omitempty"`
	ToolCallID string     `json:"tool_call_id,omitempty"`
}

// List available skills
func listAvailableSkills() []string {
	entries, err := os.ReadDir(skillsDir)
	if err != nil {
		return nil
	}
	var names []string
	for _, e := range entries {
		if _, err := os.Stat(filepath.Join(skillsDir, e.Name(), "SKILL.md")); e.IsDir() && err == nil {
			names = append(names, e.Name())
		}
	}
	return names
}

func orNone(names []string, fallback string) string {
	if len(names) == 0 {
		return fallback
	}
	return strings.Join(names, ", ")
}

// executeSkill returns the tool output plus a message to inject into the next turn.
func executeSkill(skillType string, messages []message) (string, *message) {
	marker := fmt.Sprintf("[Skill: %s]", skillType)
	history, _ := json.Marshal(messages)
	if strings.Contains(string(history), marker) {
		return "Skill " + skillType + " is already loaded", nil
	}
	// The skill name comes from the model, so only load skills that exist under skillsDir
	available := listAvailableSkills()
	if !slices.Contains(available, skillType) {
		return fmt.Sprintf("Skill %q not found. Available skills: %s", skillType, orNone(available, "none")), nil
	}
	skillDir := filepath.Join(skillsDir, skillType)
	skill, err := os.ReadFile(filepath.Join(skillDir, "SKILL.md"))
	if err != nil {
		return fmt.Sprintf("Skill %q could not be read: %v", skillType, err), nil
	}
	return "Launching skill " + skillType, &message{
		Role:    "user",
		Content: fmt.Sprintf("%s\nBase directory for this skill: %s\n\n%s", marker, skillDir, skill),
	}
}

func main() {
	skillTool := map[string]any{
		"type": "function",
		"function": map[string]any{
			"name": "Skill",
			"description": fmt.Sprintf("Load a specialized skill to enhance the assistant's capabilities.\nAvailable skills: %s\nEach skill provides domain-specific instructions and capabilities.", orNone(listAvailableSkills(), "none configured")),
			"parameters": map[string]any{
				"type": "object",
				"properties": map[string]any{
					"type": map[string]any{"type": "string", "description": "The skill type to load (e.g., 'pdf-processing')"},
				},
				"required": []string{"type"},
			},
		},
	}

	messages := []message{{Role: "user", Content: "Load the pdf-processing skill, then tell me what it lets you do."}}

	for i := 0; i < 5; i++ {
		body, _ := json.Marshal(map[string]any{"model": "openai/gpt-4o-mini", "messages": messages, "tools": []any{skillTool}})
		req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/chat/completions", bytes.NewReader(body))
		req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
		req.Header.Set("Content-Type", "application/json")
		resp, err := http.DefaultClient.Do(req)
		if err != nil {
			panic(err)
		}
		if resp.StatusCode != http.StatusOK {
			b, _ := io.ReadAll(resp.Body)
			panic(fmt.Sprintf("HTTP %d: %s", resp.StatusCode, b))
		}
		var out struct {
			Choices []struct {
				Message message `json:"message"`
			} `json:"choices"`
		}
		err = json.NewDecoder(resp.Body).Decode(&out)
		resp.Body.Close()
		if err != nil || len(out.Choices) == 0 {
			panic(fmt.Sprintf("bad response: %v", err))
		}

		msg := out.Choices[0].Message
		messages = append(messages, msg)
		if len(msg.ToolCalls) == 0 {
			fmt.Println(msg.Content)
			return
		}

		// Run each tool call, then inject loaded skill instructions for the next turn
		var injected []message
		for _, tc := range msg.ToolCalls {
			var args struct {
				Type string `json:"type"`
			}
			json.Unmarshal([]byte(tc.Function.Arguments), &args)
			result, inject := executeSkill(args.Type, messages)
			messages = append(messages, message{Role: "tool", ToolCallID: tc.ID, Content: result})
			if inject != nil {
				injected = append(injected, *inject)
			}
		}
		messages = append(messages, injected...)
	}
}

```

```text title="Output" theme={null}
Available skills: docs-sample-skill
"I am the docs sample fixture skill."
```

## Usage

```typescript lines theme={null}
import { OpenRouter } from '@openrouter/sdk';
import { callModel, tool } from '@openrouter/agent';
import { z } from 'zod';
import { existsSync, readdirSync, readFileSync } from 'node:fs';
import { homedir } from 'node:os';
import { join } from 'node:path';

const openrouter = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });

const skillsDir = join(homedir(), '.claude', 'skills');

// List available skills
function listAvailableSkills(): string[] {
  if (!existsSync(skillsDir)) return [];
  return readdirSync(skillsDir, { withFileTypes: true })
    .filter((e) => e.isDirectory() && existsSync(join(skillsDir, e.name, 'SKILL.md')))
    .map((e) => e.name);
}

const available = listAvailableSkills();

const skillsTool = tool({
  name: 'Skill',
  description: `Load a specialized skill to enhance the assistant's capabilities.\nAvailable skills: ${available.join(', ') || 'none configured'}\nEach skill provides domain-specific instructions and capabilities.`,
  inputSchema: z.object({
    type: z.string().describe("The skill type to load (e.g., 'pdf-processing')"),
  }),
  execute: async ({ type }) => {
    // The skill name comes from the model, so only load skills that exist under skillsDir
    const skillDir = join(skillsDir, type);
    const skillPath = join(skillDir, 'SKILL.md');
    if (!available.includes(type)) {
      return { error: `Skill "${type}" not found. Available skills: ${available.join(', ') || 'none'}` };
    }
    return {
      skill: type,
      baseDirectory: skillDir,
      instructions: readFileSync(skillPath, 'utf8'),
    };
  },
});

const result = callModel(openrouter, {
  model: 'anthropic/claude-sonnet-4.5',
  input: 'I need to process a PDF and extract tables from it',
  tools: [skillsTool] as const,
});

const text = await result.getText();
// The model will call the Skill tool, loading pdf-processing context
// Subsequent responses will have access to the skill's instructions
console.log(text);

```

```python title="Python" lines theme={null}
import asyncio
import os
from pathlib import Path

from pydantic import BaseModel, Field
from openrouter_agent import OpenRouter, call_model, tool

skills_dir = Path.home() / ".claude" / "skills"


# List available skills
def list_available_skills() -> list[str]:
    if not skills_dir.exists():
        return []
    return [e.name for e in skills_dir.iterdir() if e.is_dir() and (e / "SKILL.md").exists()]


available = list_available_skills()


class SkillInput(BaseModel):
    type: str = Field(description="The skill type to load (e.g., 'pdf-processing')")


def execute_skill(params: SkillInput, ctx):
    # The skill name comes from the model, so only load skills that exist under skills_dir
    skill_dir = skills_dir / params.type
    skill_path = skill_dir / "SKILL.md"
    if params.type not in available or not skill_path.exists():
        return {"error": f'Skill "{params.type}" not found. Available skills: {", ".join(available) or "none"}'}
    return {
        "skill": params.type,
        "baseDirectory": str(skill_dir),
        "instructions": skill_path.read_text(encoding="utf-8"),
    }


skills_tool = tool(
    name="Skill",
    description=(
        "Load a specialized skill to enhance the assistant's capabilities.\n"
        f"Available skills: {', '.join(available) or 'none configured'}\n"
        "Each skill provides domain-specific instructions and capabilities."
    ),
    input_schema=SkillInput,
    execute=execute_skill,
)


async def main() -> None:
    client = OpenRouter(api_key=os.environ["OPENROUTER_API_KEY"])
    result = call_model(
        client,
        {
            "model": "anthropic/claude-sonnet-4.5",
            "input": "I need to process a PDF and extract tables from it",
            "tools": [skills_tool],
        },
    )
    text = await result.get_text()
    # The model will call the Skill tool, loading pdf-processing context
    # Subsequent responses will have access to the skill's instructions
    print(text)


asyncio.run(main())

```

```go title="Go" lines theme={null}
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"path/filepath"
	"slices"
	"strings"
)

var skillsDir = filepath.Join(os.Getenv("HOME"), ".claude", "skills")

type toolCall struct {
	ID       string `json:"id"`
	Type     string `json:"type"`
	Function struct {
		Name      string `json:"name"`
		Arguments string `json:"arguments"`
	} `json:"function"`
}

type message struct {
	Role       string     `json:"role"`
	Content    any        `json:"content"`
	ToolCalls  []toolCall `json:"tool_calls,omitempty"`
	ToolCallID string     `json:"tool_call_id,omitempty"`
}

// List available skills
func listAvailableSkills() []string {
	entries, err := os.ReadDir(skillsDir)
	if err != nil {
		return nil
	}
	var names []string
	for _, e := range entries {
		if _, err := os.Stat(filepath.Join(skillsDir, e.Name(), "SKILL.md")); e.IsDir() && err == nil {
			names = append(names, e.Name())
		}
	}
	return names
}

func orNone(names []string, fallback string) string {
	if len(names) == 0 {
		return fallback
	}
	return strings.Join(names, ", ")
}

func executeSkill(skillType string, available []string) string {
	// The skill name comes from the model, so only load skills that exist under skillsDir
	skillDir := filepath.Join(skillsDir, skillType)
	var instructions []byte
	err := fmt.Errorf("skill %q is not available", skillType)
	if slices.Contains(available, skillType) {
		instructions, err = os.ReadFile(filepath.Join(skillDir, "SKILL.md"))
	}
	var out map[string]any
	if err != nil {
		out = map[string]any{"error": fmt.Sprintf("Skill %q not found. Available skills: %s", skillType, orNone(available, "none"))}
	} else {
		out = map[string]any{"skill": skillType, "baseDirectory": skillDir, "instructions": string(instructions)}
	}
	b, _ := json.Marshal(out)
	return string(b)
}

func main() {
	available := listAvailableSkills()
	skillsTool := map[string]any{
		"type": "function",
		"function": map[string]any{
			"name":        "Skill",
			"description": fmt.Sprintf("Load a specialized skill to enhance the assistant's capabilities.\nAvailable skills: %s\nEach skill provides domain-specific instructions and capabilities.", orNone(available, "none configured")),
			"parameters": map[string]any{
				"type": "object",
				"properties": map[string]any{
					"type": map[string]any{"type": "string", "description": "The skill type to load (e.g., 'pdf-processing')"},
				},
				"required": []string{"type"},
			},
		},
	}

	messages := []message{{Role: "user", Content: "I need to process a PDF and extract tables from it"}}

	for i := 0; i < 5; i++ {
		body, _ := json.Marshal(map[string]any{"model": "anthropic/claude-sonnet-4.5", "messages": messages, "tools": []any{skillsTool}})
		req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/chat/completions", bytes.NewReader(body))
		req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
		req.Header.Set("Content-Type", "application/json")
		resp, err := http.DefaultClient.Do(req)
		if err != nil {
			panic(err)
		}
		if resp.StatusCode != http.StatusOK {
			b, _ := io.ReadAll(resp.Body)
			panic(fmt.Sprintf("HTTP %d: %s", resp.StatusCode, b))
		}
		var out struct {
			Choices []struct {
				Message message `json:"message"`
			} `json:"choices"`
		}
		err = json.NewDecoder(resp.Body).Decode(&out)
		resp.Body.Close()
		if err != nil || len(out.Choices) == 0 {
			panic(fmt.Sprintf("bad response: %v", err))
		}

		msg := out.Choices[0].Message
		messages = append(messages, msg)
		if len(msg.ToolCalls) == 0 {
			// The model called the Skill tool, loading pdf-processing context;
			// this response has access to the skill's instructions
			fmt.Println(msg.Content)
			return
		}

		for _, tc := range msg.ToolCalls {
			var args struct {
				Type string `json:"type"`
			}
			json.Unmarshal([]byte(tc.Function.Arguments), &args)
			messages = append(messages, message{Role: "tool", ToolCallID: tc.ID, Content: executeSkill(args.Type, available)})
		}
	}
}

```

```text title="Output" theme={null}
I apologize, but it appears that there are no specialized PDF processing skills currently configured in my environment. However, I can still help guide you through the process of extracting tables from PDFs.

To extract tables from a PDF, you would typically need:

1. **The PDF file** - Please upload or share the PDF you want to process
2. **Information about the tables** - Which pages contain the tables, or if you want to extract all tables from the document

If you share your PDF file with me, I can try to help you extract the table data, though my capabilities may be limited without the specialized PDF processing tools.

Alternatively, here are some popular tools you could use:
- **Python libraries**: `tabula-py`, `camelot-py`, or `pdfplumber`
- **Online tools**: Smallpdf, PDFTables, or Adobe Acrobat
- **Command-line tools**: `pdftotext` or `pdf2json`

Would you like to share your PDF file so I can attempt to help you extract the tables?
```

## Example Skill File

Create `~/.claude/skills/pdf-processing/SKILL.md`:

```markdown expandable lines theme={null}
# PDF Processing Skill

You are now equipped with PDF processing capabilities.

## Available Tools
When processing PDFs, you have access to:
- `extract_text`: Extract all text from a PDF
- `extract_tables`: Extract tables as structured data
- `extract_images`: Extract embedded images
- `split_pdf`: Split PDF into individual pages

## Best Practices
1. Always check PDF file size before processing
2. For large PDFs (>50 pages), process in chunks
3. OCR may be needed for scanned documents
4. Tables may span multiple pages - handle accordingly

## Output Formats
- Text: Plain text or markdown
- Tables: JSON, CSV, or markdown tables
- Images: PNG with sequential naming

## Error Handling
- If a PDF is encrypted, request the password
- If OCR fails, suggest alternative approaches
- Report page numbers for any extraction errors
```

## Extended: Multi-Skill Loader

Load multiple skills in a single call:

```typescript expandable lines theme={null}
const multiSkillLoader = tool({
  name: 'load_skills',
  description: 'Load multiple skills at once for complex tasks',

  inputSchema: z.object({
    skills: z.array(z.string()).describe('Array of skill names to load'),
  }),

  outputSchema: z.object({
    loaded: z.array(z.string()),
    failed: z.array(
      z.object({
        name: z.string(),
        reason: z.string(),
      })
    ),
  }),

  nextTurnParams: {
    input: (params, context) => {
      let newInput = Array.isArray(context.input) ? context.input : [context.input];

      for (const skillName of params.skills) {
        const skillMarker = `[Skill: ${skillName}]`;

        // Skip if already loaded
        if (JSON.stringify(newInput).includes(skillMarker)) {
          continue;
        }

        const skillPath = path.join(SKILLS_DIR, skillName, 'SKILL.md');
        if (!existsSync(skillPath)) {
          continue;
        }

        const skillContent = readFileSync(skillPath, 'utf-8');
        const skillDir = path.join(SKILLS_DIR, skillName);

        newInput = [
          ...newInput,
          {
            role: 'user',
            content: `${skillMarker}
Base directory: ${skillDir}

${skillContent}`,
          },
        ];
      }

      return newInput;
    },
  },

  execute: async ({ skills }) => {
    const loaded: string[] = [];
    const failed: Array<{ name: string; reason: string }> = [];

    for (const skill of skills) {
      const skillPath = path.join(SKILLS_DIR, skill, 'SKILL.md');
      if (existsSync(skillPath)) {
        loaded.push(skill);
      } else {
        failed.push({ name: skill, reason: 'Skill not found' });
      }
    }

    return { loaded, failed };
  },
});

// Usage
const result = openrouter.callModel({
  model: 'anthropic/claude-sonnet-4.5',
  input: 'I need to analyze a PDF report and create visualizations',
  tools: [multiSkillLoader],
});
// Model might call: load_skills({ skills: ['pdf-processing', 'data-analysis'] })
```

## Extended: Skill with Options

Skills that accept configuration:

```typescript expandable lines theme={null}
const configurableSkillLoader = tool({
  name: 'configure_skill',
  description: 'Load a skill with custom configuration options',

  inputSchema: z.object({
    skillName: z.string(),
    options: z
      .object({
        verbosity: z.enum(['minimal', 'normal', 'detailed']).default('normal'),
        strictMode: z.boolean().default(false),
        outputFormat: z.enum(['json', 'markdown', 'plain']).default('markdown'),
      })
      .optional(),
  }),

  outputSchema: z.object({
    status: z.enum(['loaded', 'already_loaded', 'not_found']),
    message: z.string(),
    configuration: z.record(z.unknown()).optional(),
  }),

  nextTurnParams: {
    input: (params, context) => {
      const skillMarker = `[Skill: ${params.skillName}]`;
      if (JSON.stringify(context.input).includes(skillMarker)) {
        return context.input;
      }

      const skillPath = path.join(SKILLS_DIR, params.skillName, 'SKILL.md');
      if (!existsSync(skillPath)) {
        return context.input;
      }

      const skillContent = readFileSync(skillPath, 'utf-8');
      const options = params.options || {};

      // Build configuration header
      const configHeader = `
## Skill Configuration
- Verbosity: ${options.verbosity || 'normal'}
- Strict Mode: ${options.strictMode || false}
- Output Format: ${options.outputFormat || 'markdown'}
`;

      // A plain string input must become a message item before appending
      const currentInput =
        typeof context.input === 'string'
          ? [{ role: 'user' as const, content: context.input }]
          : (context.input ?? []);

      return [
        ...currentInput,
        {
          role: 'user' as const,
          content: `${skillMarker}
${configHeader}

${skillContent}`,
        },
      ];
    },

    // Adjust model behavior based on skill
    temperature: (params, context) => {
      // Lower temperature for strict mode
      if (params.options?.strictMode) {
        return 0.3;
      }
      return context.temperature;
    },
  },

  execute: async ({ skillName, options }) => {
    const skillPath = path.join(SKILLS_DIR, skillName, 'SKILL.md');

    if (!existsSync(skillPath)) {
      return {
        status: 'not_found' as const,
        message: `Skill "${skillName}" not found`,
      };
    }

    return {
      status: 'loaded' as const,
      message: `Skill "${skillName}" loaded with configuration`,
      configuration: options || {},
    };
  },
});
```

```python title="Python" lines theme={null}
class SkillOptions(BaseModel):
    verbosity: Literal["minimal", "normal", "detailed"] = "normal"
    strict_mode: bool = False
    output_format: Literal["json", "markdown", "plain"] = "markdown"


class ConfigureSkillInput(BaseModel):
    skill_name: str
    options: SkillOptions | None = None


class ConfigureSkillOutput(BaseModel):
    status: Literal["loaded", "already_loaded", "not_found"]
    message: str
    configuration: dict[str, Any] | None = None


# The skill name comes from the model, so accept a plain directory name only
def is_skill_name(name: str) -> bool:
    return name not in ("", ".", "..") and os.path.basename(name) == name


def next_input(params, context):
    # next_turn_params functions receive the raw tool-call arguments (a dict)
    params = ConfigureSkillInput.model_validate(params)
    skill_marker = f"[Skill: {params.skill_name}]"
    current = context.get("input")
    if skill_marker in json.dumps(current, default=str):
        return current

    skill_path = os.path.join(SKILLS_DIR, params.skill_name, "SKILL.md")
    if not is_skill_name(params.skill_name) or not os.path.exists(skill_path):
        return current

    with open(skill_path, encoding="utf-8") as f:
        skill_content = f.read()
    options = params.options or SkillOptions()

    # Build configuration header
    config_header = f"""
## Skill Configuration
- Verbosity: {options.verbosity}
- Strict Mode: {options.strict_mode}
- Output Format: {options.output_format}
"""

    # A plain string input must become a message item before appending
    if isinstance(current, str):
        current = [{"role": "user", "content": current}]

    return [
        *(current or []),
        {"role": "user", "content": f"{skill_marker}\n{config_header}\n\n{skill_content}"},
    ]


# Adjust model behavior based on skill
def next_temperature(params, context):
    params = ConfigureSkillInput.model_validate(params)
    # Lower temperature for strict mode
    if params.options and params.options.strict_mode:
        return 0.3
    return context.get("temperature")


def execute_configure(params, ctx):
    skill_path = os.path.join(SKILLS_DIR, params.skill_name, "SKILL.md")
    if not is_skill_name(params.skill_name) or not os.path.exists(skill_path):
        return ConfigureSkillOutput(status="not_found", message=f'Skill "{params.skill_name}" not found')
    return ConfigureSkillOutput(
        status="loaded",
        message=f'Skill "{params.skill_name}" loaded with configuration',
        configuration=params.options.model_dump() if params.options else {},
    )


configurable_skill_loader = tool(
    name="configure_skill",
    description="Load a skill with custom configuration options",
    input_schema=ConfigureSkillInput,
    output_schema=ConfigureSkillOutput,
    next_turn_params={"input": next_input, "temperature": next_temperature},
    execute=execute_configure,
)

```

```go title="Go" lines theme={null}
type skillOptions struct {
	Verbosity    string `json:"verbosity,omitempty"`
	StrictMode   bool   `json:"strictMode,omitempty"`
	OutputFormat string `json:"outputFormat,omitempty"`
}

type configureSkillArgs struct {
	SkillName string        `json:"skillName"`
	Options   *skillOptions `json:"options,omitempty"`
}

var configurableSkillLoader = map[string]any{
	"type": "function",
	"function": map[string]any{
		"name":        "configure_skill",
		"description": "Load a skill with custom configuration options",
		"parameters": map[string]any{
			"type": "object",
			"properties": map[string]any{
				"skillName": map[string]any{"type": "string"},
				"options": map[string]any{
					"type": "object",
					"properties": map[string]any{
						"verbosity":    map[string]any{"type": "string", "enum": []string{"minimal", "normal", "detailed"}, "default": "normal"},
						"strictMode":   map[string]any{"type": "boolean", "default": false},
						"outputFormat": map[string]any{"type": "string", "enum": []string{"json", "markdown", "plain"}, "default": "markdown"},
					},
				},
			},
			"required": []string{"skillName"},
		},
	},
}

// Tool result: status, message, and optional configuration
func executeConfigureSkill(args configureSkillArgs) map[string]any {
	// The skill name comes from the model, so only accept skills that exist under skillsDir
	if !slices.Contains(listAvailableSkills(), args.SkillName) {
		return map[string]any{"status": "not_found", "message": fmt.Sprintf("Skill %q not found", args.SkillName)}
	}
	var configuration any = map[string]any{}
	if args.Options != nil {
		configuration = args.Options
	}
	return map[string]any{
		"status":        "loaded",
		"message":       fmt.Sprintf("Skill %q loaded with configuration", args.SkillName),
		"configuration": configuration,
	}
}

// Next-turn input: append the skill's instructions once, with a config header
func nextTurnInput(args configureSkillArgs, messages []message) []message {
	skillMarker := fmt.Sprintf("[Skill: %s]", args.SkillName)
	if b, _ := json.Marshal(messages); strings.Contains(string(b), skillMarker) {
		return messages
	}
	if !slices.Contains(listAvailableSkills(), args.SkillName) {
		return messages
	}
	skillContent, err := os.ReadFile(filepath.Join(skillsDir, args.SkillName, "SKILL.md"))
	if err != nil {
		return messages
	}
	opts := skillOptions{}
	if args.Options != nil {
		opts = *args.Options
	}
	if opts.Verbosity == "" {
		opts.Verbosity = "normal"
	}
	if opts.OutputFormat == "" {
		opts.OutputFormat = "markdown"
	}

	// Build configuration header
	configHeader := fmt.Sprintf("\n## Skill Configuration\n- Verbosity: %s\n- Strict Mode: %t\n- Output Format: %s\n",
		opts.Verbosity, opts.StrictMode, opts.OutputFormat)

	return append(messages, message{
		Role:    "user",
		Content: skillMarker + "\n" + configHeader + "\n\n" + string(skillContent),
	})
}

// Adjust model behavior based on skill: lower temperature for strict mode
func nextTurnTemperature(args configureSkillArgs, current *float64) *float64 {
	if args.Options != nil && args.Options.StrictMode {
		t := 0.3
		return &t
	}
	return current
}
```

## Skill Discovery Tool

List and describe available skills:

```typescript expandable lines theme={null}
const skillDiscoveryTool = tool({
  name: 'list_skills',
  description: 'List all available skills with their descriptions',

  inputSchema: z.object({
    category: z.string().optional().describe('Filter by category'),
  }),

  outputSchema: z.object({
    skills: z.array(
      z.object({
        name: z.string(),
        description: z.string(),
        hasConfig: z.boolean(),
      })
    ),
    totalCount: z.number(),
  }),

  execute: async ({ category }) => {
    const availableSkills = listAvailableSkills();
    const skills = [];

    for (const skillName of availableSkills) {
      const skillPath = path.join(SKILLS_DIR, skillName, 'SKILL.md');
      const content = readFileSync(skillPath, 'utf-8');

      // Extract first paragraph as description
      const lines = content.split('\n').filter((l) => l.trim());
      const description = lines.find((l) => !l.startsWith('#')) || 'No description';

      // Check for config file
      const configPath = path.join(SKILLS_DIR, skillName, 'config.json');
      const hasConfig = existsSync(configPath);

      skills.push({
        name: skillName,
        description: description.slice(0, 100),
        hasConfig,
      });
    }

    return {
      skills,
      totalCount: skills.length,
    };
  },
});
```

## Complete Example

Putting it all together:

```typescript expandable lines theme={null}
import { OpenRouter, tool, stepCountIs } from '@openrouter/agent';
import { readFileSync, existsSync, readdirSync } from 'fs';
import path from 'path';
import { z } from 'zod';

const openrouter = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
});

const SKILLS_DIR = path.join(process.env.HOME || '~', '.claude', 'skills');

// ... (include skillsTool, multiSkillLoader, skillDiscoveryTool from above)

// Use all skill tools together
const result = openrouter.callModel({
  model: 'anthropic/claude-sonnet-4.5',
  input: `I have a complex task:
1. First, show me what skills are available
2. Load the appropriate skills for PDF analysis
3. Then help me extract and analyze data from report.pdf`,
  tools: [skillDiscoveryTool, skillsTool, multiSkillLoader],
  stopWhen: stepCountIs(10),
});

const text = await result.getText();
console.log(text);
```

```go title="Go" lines theme={null}
// ... (include skillsTool, multiSkillLoader, skillDiscoveryTool and runTool from above)

// Use all skill tools together
messages := []message{{Role: "user", Content: `I have a complex task:
1. First, show me what skills are available
2. Load the appropriate skills for PDF analysis
3. Then help me extract and analyze data from report.pdf`}}
tools := []any{skillDiscoveryTool, skillsTool, multiSkillLoader}

// Stop after at most 10 steps
for step := 0; step < 10; step++ {
	body, _ := json.Marshal(map[string]any{
		"model":    "anthropic/claude-sonnet-4.5",
		"messages": messages,
		"tools":    tools,
	})
	req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/chat/completions", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	var out struct {
		Choices []struct {
			Message message `json:"message"`
		} `json:"choices"`
	}
	err = json.NewDecoder(resp.Body).Decode(&out)
	resp.Body.Close()
	if err != nil || len(out.Choices) == 0 {
		log.Fatalf("bad response (status %d): %v", resp.StatusCode, err)
	}

	msg := out.Choices[0].Message
	messages = append(messages, msg)
	if len(msg.ToolCalls) == 0 {
		fmt.Println(msg.Content)
		break
	}
	for _, tc := range msg.ToolCalls {
		messages = append(messages, message{
			Role:       "tool",
			ToolCallID: tc.ID,
			Content:    runTool(tc.Function.Name, tc.Function.Arguments),
		})
	}
}
```

## Key Patterns

### 1. Idempotency

Always check if a skill is already loaded:

```typescript lines theme={null}
nextTurnParams: {
  input: (params, context) => {
    const marker = `[Skill: ${params.type}]`;
    if (JSON.stringify(context.input).includes(marker)) {
      return context.input; // Don't add again
    }
    // ... add skill
  },
},
```

```python title="Python" lines theme={null}
# Next-turn input: skip if the skill is already loaded
def next_turn_input(params, messages):
    marker = f"[Skill: {params['type']}]"
    if marker in json.dumps(messages):
        return messages  # Don't add again
    # ... add skill

```

```go title="Go" lines theme={null}
// Next-turn input: skip if the skill is already in the conversation
func nextTurnInput(args loadSkillArgs, messages []message) []message {
	marker := fmt.Sprintf("[Skill: %s]", args.Type)
	if b, _ := json.Marshal(messages); strings.Contains(string(b), marker) {
		return messages // Don't add again
	}
	// ... add skill
	return messages
}

```

### 2. Graceful Fallbacks

Handle missing skills gracefully:

```typescript lines theme={null}
execute: async (params) => {
  if (!existsSync(skillPath)) {
    return `Skill not found. Available: ${listAvailableSkills().join(', ')}`;
  }
  // ...
},
```

```python title="Python" lines theme={null}
# Tool execute: report available skills when the requested one is missing
def execute(params):
    if not os.path.exists(skill_path):
        return f"Skill not found. Available: {', '.join(list_available_skills())}"
    # ...

```

```go title="Go" lines theme={null}
// Execute: if the skill is missing, list the ones that exist
func execute(args loadSkillArgs) string {
	available := listAvailableSkills()
	if !slices.Contains(available, args.Type) {
		return fmt.Sprintf("Skill not found. Available: %s", strings.Join(available, ", "))
	}
	// ...
	return ""
}
```

### 3. Context Preservation

Always preserve existing input:

```typescript lines theme={null}
nextTurnParams: {
  input: (params, context) => {
    const currentInput = Array.isArray(context.input)
      ? context.input
      : [context.input];
    return [...currentInput, newMessage]; // Append, don't replace
  },
},
```

```python title="Python" lines theme={null}
# Next-turn input: append the skill message, never replace existing input
def next_turn_input(params, messages):
    current_input = messages if isinstance(messages, list) else [messages]
    return [*current_input, new_message]  # Append, don't replace

```

```go title="Go" lines theme={null}
// Next-turn input: append the skill message to the existing conversation
func nextTurnInput(args loadSkillArgs, messages []message) []message {
	newMessage := buildSkillMessage(args)
	return append(messages, newMessage) // Append, don't replace
}

```

### 4. Clear Markers

Use unique markers to identify injected content:

```typescript lines theme={null}
const skillMarker = `[Skill: ${params.type}]`;
// Makes detection reliable and content clearly labeled
```

```python title="Python" lines theme={null}
skill_marker = f"[Skill: {params['type']}]"
# Makes detection reliable and content clearly labeled
```

```go title="Go" lines theme={null}
skillMarker := fmt.Sprintf("[Skill: %s]", args.Type)
// Makes detection reliable and content clearly labeled

```

## See Also

* **[nextTurnParams Guide](https://openrouter.ai/docs/agent-sdk/call-model/next-turn-params.md)** - Context injection patterns
* **[Dynamic Parameters](https://openrouter.ai/docs/agent-sdk/call-model/dynamic-parameters.md)** - Adaptive behavior
* **[Tools](https://openrouter.ai/docs/agent-sdk/call-model/tools.md)** - Multi-turn orchestration
