skills-ref: Agent Skills Reference Library

0.1.1 · active · verified Thu Apr 16

The `skills-ref` library serves as a foundational reference for the Agent Skills open specification, enabling AI agents to dynamically discover, load, and execute specialized capabilities. It defines the structure and format for 'skills,' which are modular packages of instructions, scripts, and resources for AI agents. Currently at version 0.1.1, its development is closely tied to Anthropic's Agent Skills initiative, with active releases focusing on refining the underlying specification.

Common errors

```
ModuleNotFoundError: No module named 'skills_ref.something'
```
cause Attempting to import a specific module or class directly from `skills-ref` that may not exist or is not intended for public consumption. `skills-ref` is a reference/specification library.

fix Review the documentation for the `agent-skills` library or other agent frameworks that integrate with the Agent Skills specification. `skills-ref` itself typically does not expose user-facing Python APIs.
```
Agent fails to load/discover custom SKILL.md file: 'SkillNotFound' or 'InvalidSkillFormat'
```
cause The agent framework (e.g., `agent-skills`) could not correctly parse the `SKILL.md` file due to incorrect YAML frontmatter, missing required fields (like `name` or `description`), or a directory structure that doesn't conform to the specification.

fix Ensure your `SKILL.md` file has valid YAML frontmatter including `name` and `description` fields, and that the skill directory name matches the `name` field in the frontmatter. Verify the agent's skill loading path configuration. Refer to the official Agent Skills specification for exact formatting rules.

Warnings

gotcha The `skills-ref` library is primarily a specification reference. End-users building AI agents will likely interact with higher-level libraries (e.g., `agent-skills`) that implement the specification, rather than directly importing and using components from `skills-ref`.
Fix: Focus on the documentation for agent frameworks like `agent-skills` (from Anthropic) or similar implementations that consume the Agent Skills standard when building agent capabilities in Python.
breaking As a low-version (0.1.1) foundational library for a new open specification, `skills-ref` is subject to frequent and potentially breaking changes in its definitions and internal structures, even in minor versions, as the Agent Skills standard evolves.
Fix: Regularly consult the `anthropics/agentskills` GitHub repository and release notes for `skills-ref` and `agent-skills` to stay updated on specification changes and ensure compatibility. Pin exact versions of the library in `requirements.txt`.
gotcha The 'Agent Skills' concept itself relies heavily on the `SKILL.md` file format for defining agent capabilities. Misunderstandings of this Markdown-based format (YAML frontmatter, instruction structure, referencing external files) can lead to agents failing to correctly discover or execute skills.
Fix: Carefully review the Agent Skills specification and examples provided in the `anthropics/agentskills` GitHub repository for creating `SKILL.md` files, particularly regarding `name`, `description`, and progressive disclosure patterns.

Install

pip install skills-ref Install stable version

Imports

Note on direct imports

This library (skills-ref) primarily defines the Agent Skills specification and does not typically expose high-level Python classes or functions for direct end-user interaction. Practical integration with Agent Skills in Python is generally handled by other libraries, such as `agent-skills` (from `anthropics/agentskills`), which consume the specification defined by `skills-ref`.

Users typically interact with the Agent Skills concept through `SKILL.md` files and higher-level agent frameworks rather than direct Python imports from `skills-ref`.

Quickstart

The `skills-ref` library defines the underlying format for Agent Skills. Therefore, a 'quickstart' for `skills-ref` itself involves understanding the `SKILL.md` file format. Practical interaction with these skills in Python is typically done through a compatible agent framework, such as the `agent-skills` library, which interprets and executes skills conforming to the `skills-ref` specification. The example illustrates the conceptual structure of an Agent Skill and how an agent might load and utilize it.

# The 'skills-ref' library defines the structure, but direct Python usage is typically via an agent framework.
# Here's a conceptual representation of how an agent might 'use' a skill based on the specification.

# Imagine an agent framework loading skill metadata (defined by skills-ref specification):
# from agent_skills import Agent, AgentSkillsToolset # (from related 'agent-skills' library)

# A skill, as defined by the 'skills-ref' specification, is a directory containing a SKILL.md file.
# Example SKILL.md content (conceptual):
# ---
# name: code-reviewer
# description: Reviews Python code for style, errors, and best practices.
# license: Apache-2.0
# ---
# # Code Review Instructions
# 1. Read the provided Python code.
# 2. Check for PEP 8 compliance.
# 3. Identify potential bugs or logical errors.
# 4. Suggest improvements for readability and efficiency.
# 5. Provide a summary of findings.

# In a real agent system (e.g., using 'agent-skills' or similar):
# skills_directory = './my_agent_skills'
# toolset = AgentSkillsToolset(path_to_skills=skills_directory)
# agent = Agent(tools=[toolset])

# user_query = "Review the following Python code for me: def add(a, b): return a + b"
# agent.run(user_query)

# The agent would then (internally) discover the 'code-reviewer' skill based on its description
# and load the instructions from SKILL.md to perform the task.

view raw JSON →