agent-skills

This repository presents agent-skills, an open and decentralized specification for distributing tools to Large Language Model (LLM) agents. This framework serves as a token-efficient, transparent, immutable, and web-native alternative to traditional models such as MCP.

The core innovation behind agent-skills is the shift from tool data injection to a retrieval model. Rather than loading multiple tools into an agent's context at session start (which can overwhelm the context window), tools are described as SKILL.md files that are hosted at stable URLs. These files are typically stored in a Git repository and served via a Content Delivery Network (CDN). This method allows agents to dynamically discover tools through vector search as needed, maintaining a consistent token cost regardless of the catalog size.

Key Features

• Credential Isolation: Sensitive information is not included in the LLM's context. Skill commands reference environment variables visible only to the shell, enhancing security.
• Transparency: Each skill is available as a markdown file in a public Git repository, allowing users to read, modify, and audit the skills freely.
• Cryptographic Provenance: Skills are tied to specific git commit hashes, ensuring that any changes can be traced, signed, and remain immutable.
• Decentralization: No need for a central registry; the required infrastructure consists of any Git repository and a CDN.
• Composability: Skills can reference and chain other skills through hash relationships, enabling rich functionality.

Architecture Overview

agent-skills operates through a structured architecture that includes:

• Skill Providers: Any git host can serve as a source for skills.
• Discovery Mechanisms: Tools can be found through various community-curated lists and aggregators.
• Local Skill Bank: A conformant implementation that manages subscriptions, indexes, and inquiries.
• Agent Runtime: Executes commands based on user intent while retrieving skills from the local skill bank.

Use Cases and Implementation

The specification is designed to be implementation-agnostic. Infrastructure for usable skill banks can be built on any suitable platform (for example, using filesystem storage paired with vector indexing). A reference runtime is outlined in the related project, just-bash-data, though several implementations are possible, including those built on SQLite, Postgres, or in-memory stores.

Example Usage

Here’s a brief example demonstrating how to subscribe to a skill pack:

# Subscribe to a skill pack (pinned to a hash for immutability)
db skill_subscriptions insert '{
  "_id": "stripe-skills",
  "source_type": "git",
  "repo": "github.com/stripe/agent-skills",
  "ref_requested": "v1.2.0",
  "ref_resolved": "a1b2c3d4e5f67890abcdef1234567890abcdef12",
  "auto_update": false,
  "verify_signature": true,
  "trusted_keys": ["B5A4 9C28 D9F1 ..."]
}'

For detailed implementation guidance, the repository includes an IMPLEMENTATION.md file that covers various aspects necessary to set up and run a fully functional agent skill bank.

Conclusion

agent-skills aims to transform how LLM agents interact with tools by offering a systematic, efficient, and secure way to distribute and manage skills. Interested parties are encouraged to explore the specifications, implementations, and community contributions on this GitHub page.