agentskills-core 0.2.1

Storage-agnostic abstractions for discovering, validating, and accessing Agent Skills (https://agentskills.io)

agentskills-core

Core abstractions for the Agent Skills SDK — provider interface, registry, validation, and skill model.

This package provides the foundational building blocks for working with the Agent Skills format. It is storage-agnostic — concrete providers (filesystem, HTTP, database, etc.) live in separate packages.

Installation

pip install agentskills-core

Requires Python 3.12+.

What's Included

Export	Description
SkillProvider	Abstract base class that every skill backend must implement
Skill	Lightweight runtime handle to a single registered skill
SkillRegistry	Unified index with explicit registration and catalog builder
validate_skill	Validates a skill against the Agent Skills specification
split_frontmatter	Parses YAML frontmatter from SKILL.md content
AgentSkillsError	Base exception for all library errors
SkillNotFoundError	Raised when a skill does not exist
ResourceNotFoundError	Raised when a resource within a skill does not exist

Usage

Registering Skills

from agentskills_core import SkillRegistry

registry = SkillRegistry()
await registry.register("incident-response", provider)  # validates on registration

Or register multiple skills at once:

await registry.register([
    ("incident-response", fs_provider),
    ("api-style-guide", http_provider),
])

Batch registration is atomic — if any skill fails validation, none are registered.

Accessing Skills

skill = registry.get_skill("incident-response")
meta = await skill.get_metadata()       # YAML frontmatter as dict
body = await skill.get_body()           # Markdown instructions
script = await skill.get_script("run.sh")

Building a Catalog

Generate a catalog string for system-prompt injection:

xml_catalog = await registry.get_skills_catalog(format="xml")       # <available_skills> XML
md_catalog = await registry.get_skills_catalog(format="markdown")   # Markdown list

Implementing a Custom Provider

from agentskills_core import SkillProvider

class DatabaseSkillProvider(SkillProvider):
    async def get_metadata(self, skill_id: str) -> dict: ...
    async def get_body(self, skill_id: str) -> str: ...
    async def get_script(self, skill_id: str, name: str) -> bytes: ...
    async def get_asset(self, skill_id: str, name: str) -> bytes: ...
    async def get_reference(self, skill_id: str, name: str) -> bytes: ...

All methods are async so implementations backed by network I/O can be non-blocking.

Security

• Frontmatter size limits — split_frontmatter() rejects YAML frontmatter blocks exceeding 256 KB (MAX_FRONTMATTER_BYTES) to prevent memory-exhaustion attacks.
• Metadata validation — validate_skill() checks types of known optional fields (license, compatibility, metadata, allowed-tools) and logs warnings for unknown top-level metadata keys.
• Safe XML generation — get_skills_catalog(format="xml") uses xml.etree.ElementTree for catalog generation, avoiding XML injection via string concatenation.

For the full security policy, see SECURITY.md.

License

MIT