autourgos-skills

Dynamic lazy-loading skill middleware for Autourgos agents. A skill is a named instruction/knowledge fragment (Markdown, no tools) — only its name and a short description are shown to the agent upfront; the agent calls load_skill(name) to pull the full content into context when a task actually needs it.

from autourgos_skills import SkillLibraryMiddleware
from autourgos_agent import Agent

middleware = SkillLibraryMiddleware(skills=["./skills/pdf_editing.md", "./skill_library"])
agent = Agent(llm=my_llm, middleware=[middleware])
result = agent.invoke("Extract the text from this PDF")

Features

• Lazy skill loading — the agent sees only skill names/descriptions upfront, full instructions load on demand via load_skill(name)
• Three input formats, one loader — a standalone .md file, a skill_book directory (one skill bundled with its resources), or a folder-of-skill_books (a library)
• Safe to share across agents — one SkillLibraryMiddleware instance can serve multiple concurrent Agents; per-agent state is isolated (autourgos-core's PerAgentRegistry)
• Optional frontmatter — name/description via a ----delimited block; falls back to filename and first line when absent
• Clean state per run — on_agent_end/on_agent_error fully restore the agent's original prompt; concurrent runs against one middleware instance are isolated per agent
• Depends on autourgos-agent; works with any Autourgos agent

Table of Contents

• Why Use This?
• Install
• Quick Start
• Skill Formats
• Frontmatter
• Resources
• License

Why Use This?

Agents that support many different tasks often need many different sets of specialized instructions — PDF editing, spreadsheet formatting, a particular API's quirks, a house writing style. Dumping all of them into the system prompt at once wastes tokens on instructions the agent will never use for a given task, and can push you past the context window before the task even starts. SkillLibraryMiddleware shows only a catalog of names and one-line descriptions upfront, loading a skill's full content only when the agent actually decides it's needed.

Install

pip install autourgos-skills

Quick Start

from autourgos_skills import SkillLibraryMiddleware
from autourgos_agent import Agent

middleware = SkillLibraryMiddleware(skills="./skills/pdf_editing.md")
agent = Agent(llm=my_llm, middleware=[middleware])

result = agent.invoke("Extract the text from this PDF")
print(result)

With Agent(verbose=True), this middleware narrates its own actions into the trace:

[Skills] Loaded skill 'pdf-editing' into agent context.

Skill Formats

skills= accepts a single path, a Skill instance, or a list mixing any of these. Each path is auto-detected as one of three forms:

Standalone .md file — one skill

middleware = SkillLibraryMiddleware(skills="./skills/pdf_editing.md")

skill_book directory — one skill, bundled with resources

A directory containing SKILL.md (the skill's content) plus any number of sibling files — reference docs, examples, templates — listed as resources when the skill loads (not auto-injected; the agent can read them with its own file tools if it has any).

pdf_editing/
├── SKILL.md
├── reference.md
└── example_output.pdf

middleware = SkillLibraryMiddleware(skills="./skills/pdf_editing")

Folder-of-skill_books — a library

A directory whose immediate subdirectories are each a skill_book. Subdirectories without a SKILL.md are skipped (not an error), so a library directory can hold other, unrelated subfolders too.

skill_library/
├── pdf_editing/
│   └── SKILL.md
├── spreadsheet_formatting/
│   ├── SKILL.md
│   └── template.xlsx
└── house_style/
    └── SKILL.md

middleware = SkillLibraryMiddleware(skills="./skill_library")

Frontmatter

A SKILL.md/standalone .md file may start with a ----delimited block giving name/description explicitly:

---
name: pdf-editing
description: Extract text, merge, split, and watermark PDF files.
---

## PDF Editing

Use `pypdf` for text extraction...

Without frontmatter, the skill's name falls back to the filename (without extension) and its description falls back to the first non-empty line of the body.

This is a simple key: value parser, not full YAML — nested lists, multi-line values, and quoted blocks are not supported; only flat string fields.

Resources

Files in a skill_book directory other than SKILL.md are collected as Skill.resources (a list of file paths) and listed to the agent when the skill loads, but their contents are never auto-injected — this keeps a skill's context cost predictable regardless of how many reference files sit alongside it.

Requirements

• Python 3.9+
• Any Autourgos agent with add_tools(), agent.tools, and agent.system_prompt / agent.prompt_template (requires autourgos-agent>=2.0.2)

License

Apache License 2.0, Copyright (c) 2026 Jitin Kumar Sengar