Install & Compatibility
Where this runs
tested against v0.1.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✕ build_error
py 3.9
✕ build_error
✕ build_error
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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`.
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.
Debug
Known issues
gotchaThe `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`.fixFocus 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.
affects: All versions (0.1.x)
breakingAs 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.fixRegularly 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`.
affects: All versions (0.1.x)
gotchaThe '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.fixCarefully 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.
affects: All versions
Upgrade
Version history
0.1.1latest on PyPI · released Jan 10, 2026
Audit
Dependencies
pythonrequiredRequired runtime environment.