Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.orxhestra.com/llms.txt

Use this file to discover all available pages before exploring further.

Skills are first-class in the composer: declare them under skills: and reference them from an agent’s skills: list. See Composer → skills: for the YAML shape (inline content / directory / MCP-hosted).
Skills are reusable instruction blocks that an agent can discover and load at runtime. orxhestra supports the Agent Skills Protocol — the open standard adopted by Claude Code, Cursor, Gemini CLI, and 30+ other tools.

​
Progressive Disclosure (3-Tier Model)

Skills use progressive disclosure to minimize token cost:
TierWhatToolToken Cost
L1 — CatalogName + descriptionlist_skills~50-100 tokens
L2 — InstructionsFull SKILL.md body + metadataload_skillUp to ~5000 tokens
L3 — ResourcesScripts, references, assets on demandload_skill_resourceVaries
The agent browses the catalog (L1), loads instructions when relevant (L2), and fetches resource files only when needed (L3).

​
Inline Skills

The simplest way to define skills — no files needed: 
from orxhestra.skills import InMemorySkillStore, Skill
from orxhestra.skills import make_list_skills_tool, make_load_skill_tool

store = InMemorySkillStore([
    Skill(
        name="summarization",
        description="How to write concise summaries.",
        content="Extract the 3-5 most important points. Use bullet points. Be concise.",
    ),
    Skill(
        name="code_review",
        description="How to conduct a thorough code review.",
        content="Check correctness, readability, test coverage, and security.",
    ),
])

agent = LlmAgent(
    name="SkillfulAgent",
    model=model,
    tools=[
        make_list_skills_tool(store),   # L1: discover available skills
        make_load_skill_tool(store),    # L2: load a skill's instructions
    ],
)

​
Directory Skills (Agent Skills Protocol)

For richer skills with resources, use the standard directory layout: 
.agents/skills/
└── code-review/
    ├── SKILL.md              # Frontmatter + instructions
    ├── scripts/
    │   └── lint.sh           # Executable scripts
    ├── references/
    │   └── style-guide.md    # Reference documents
    └── assets/
        └── template.json     # Data files

​
SKILL.md Format

---
name: code-review
description: Reviews code for quality and security
license: MIT
compatibility: Python 3.10+
allowed-tools: bash read_file
metadata:
  author: team
  version: "1.0"
---

## Instructions

Review all code changes carefully. Check for:
- Correctness and edge cases
- Security vulnerabilities (OWASP top 10)
- Test coverage
- Code style consistency

​
Loading Directory Skills

from orxhestra.skills import scan_skill_directory, discover_skills

# Load a single skill directory
skill = scan_skill_directory(Path(".agents/skills/code-review"))

# Auto-discover all skills under .agents/skills/
skills = discover_skills(Path("."))

​
On-Demand Resource Loading (L3)

Directory skills can include resource files that the agent loads on demand: 
from orxhestra.skills import (
    InMemorySkillStore,
    make_list_skills_tool,
    make_load_skill_tool,
    make_load_skill_resource_tool,
    discover_skills,
)

skills = discover_skills(Path("."))
store = InMemorySkillStore(skills)

agent = LlmAgent(
    name="SkillfulAgent",
    model=model,
    tools=[
        make_list_skills_tool(store),          # L1: catalog
        make_load_skill_tool(store),           # L2: instructions + resource listing
        make_load_skill_resource_tool(store),  # L3: load individual resource files
    ],
)
When the agent calls load_skill("code-review"), it sees:
  • Full instructions from SKILL.md
  • Allowed tools, compatibility info
  • A list of available resources (e.g. scripts/lint.sh, references/style-guide.md)
It can then call load_skill_resource("code-review", "scripts/lint.sh") to fetch a specific file.
Resource loading includes path traversal protection — resolved paths must stay within the skill’s base directory.

​
Skill Models

​
SkillFrontmatter

Parsed from the YAML header in SKILL.md:
FieldTypeDescription
namestrSkill name
descriptionstrShort description
licensestr | NoneLicense identifier
compatibilitystr | NoneCompatibility requirements
allowed_toolslist[str]Tools the skill may use
metadatadictArbitrary key-value metadata

​
SkillResource

A pointer to a file within the skill directory:
FieldTypeDescription
pathstrRelative path (e.g. scripts/lint.sh)
categorystrscript, reference, or asset

​
Composer YAML

Skills can be defined inline, loaded from MCP, or loaded from a directory: 
skills:
  # Inline
  summarize:
    name: summarize
    description: "Summarize text."
    content: "Extract 3-5 key points."

  # Directory (Agent Skills Protocol)
  code-review:
    name: code-review
    directory: .agents/skills/code-review

  # Remote (FastMCP server)
  pdf:
    name: pdf-processing
    mcp:
      url: "http://localhost:8001/mcp"
Custom backends — Implement BaseSkillStore for any backend (database, API, vector store).