From fb08d608bcb81be582770fdb79d7d2f56ab13ec4 Mon Sep 17 00:00:00 2001 From: Eric Harmeling Date: Thu, 18 Dec 2025 08:46:08 -0500 Subject: [PATCH] Add documentation --- .claude/hooks/session-start.sh | 8 + .claude/settings.json | 14 + CLAUDE.md | 29 ++ docs/LICENSE | 395 ++++++++++++++++++ docs/README.md | 33 ++ docs/docs.json | 36 ++ docs/favicon.svg | 4 + docs/home.mdx | 105 +++++ docs/images/logos/amp/amp-logo-dark.svg | 3 + docs/images/logos/amp/amp-logo-light.svg | 3 + .../images/logos/block/block-lockup_black.svg | 18 + .../images/logos/block/block-lockup_white.svg | 18 + .../logos/claude-ai/Claude-logo-Ivory.svg | 9 + .../logos/claude-ai/Claude-logo-One-color.svg | 9 + .../logos/claude-ai/Claude-logo-Slate.svg | 9 + .../claude-code/Claude-Code-logo-Ivory.svg | 13 + .../Claude-Code-logo-One-color.svg | 13 + .../claude-code/Claude-Code-logo-Slate.svg | 13 + .../cursor/LOCKUP_HORIZONTAL_2D_DARK.svg | 20 + .../cursor/LOCKUP_HORIZONTAL_2D_LIGHT.svg | 20 + .../logos/github/GitHub_Lockup_Dark.svg | 33 ++ .../logos/github/GitHub_Lockup_Light.svg | 33 ++ .../Letta-logo-RGB_GreyonTransparent.svg | 22 + .../Letta-logo-RGB_OffBlackonTransparent.svg | 22 + .../logos/opencode/opencode-wordmark-dark.svg | 1 + .../opencode/opencode-wordmark-light.svg | 1 + docs/images/logos/vscode/vscode-alt.svg | 57 +++ docs/images/logos/vscode/vscode.svg | 41 ++ docs/integrate-skills.mdx | 81 ++++ docs/specification.mdx | 218 ++++++++++ docs/style.css | 206 +++++++++ docs/what-are-skills.mdx | 70 ++++ 32 files changed, 1557 insertions(+) create mode 100755 .claude/hooks/session-start.sh create mode 100644 .claude/settings.json create mode 100644 CLAUDE.md create mode 100644 docs/LICENSE create mode 100644 docs/README.md create mode 100644 docs/docs.json create mode 100644 docs/favicon.svg create mode 100644 docs/home.mdx create mode 100644 docs/images/logos/amp/amp-logo-dark.svg create mode 100644 docs/images/logos/amp/amp-logo-light.svg create mode 100644 docs/images/logos/block/block-lockup_black.svg create mode 100644 docs/images/logos/block/block-lockup_white.svg create mode 100644 docs/images/logos/claude-ai/Claude-logo-Ivory.svg create mode 100644 docs/images/logos/claude-ai/Claude-logo-One-color.svg create mode 100644 docs/images/logos/claude-ai/Claude-logo-Slate.svg create mode 100644 docs/images/logos/claude-code/Claude-Code-logo-Ivory.svg create mode 100644 docs/images/logos/claude-code/Claude-Code-logo-One-color.svg create mode 100644 docs/images/logos/claude-code/Claude-Code-logo-Slate.svg create mode 100644 docs/images/logos/cursor/LOCKUP_HORIZONTAL_2D_DARK.svg create mode 100644 docs/images/logos/cursor/LOCKUP_HORIZONTAL_2D_LIGHT.svg create mode 100644 docs/images/logos/github/GitHub_Lockup_Dark.svg create mode 100644 docs/images/logos/github/GitHub_Lockup_Light.svg create mode 100644 docs/images/logos/letta/Letta-logo-RGB_GreyonTransparent.svg create mode 100644 docs/images/logos/letta/Letta-logo-RGB_OffBlackonTransparent.svg create mode 100644 docs/images/logos/opencode/opencode-wordmark-dark.svg create mode 100644 docs/images/logos/opencode/opencode-wordmark-light.svg create mode 100644 docs/images/logos/vscode/vscode-alt.svg create mode 100644 docs/images/logos/vscode/vscode.svg create mode 100644 docs/integrate-skills.mdx create mode 100644 docs/specification.mdx create mode 100644 docs/style.css create mode 100644 docs/what-are-skills.mdx diff --git a/.claude/hooks/session-start.sh b/.claude/hooks/session-start.sh new file mode 100755 index 0000000..458b7de --- /dev/null +++ b/.claude/hooks/session-start.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +# Session start hook for agentskills documentation project +echo '{"async":true,"asyncTimeout":15000}' + +# Check if Mintlify CLI is installed +if ! command -v mint &> /dev/null; then + echo "Mintlify CLI not installed. Install with: npm i -g mint" +fi diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..0a01db8 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,14 @@ +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "type": "command", + "command": ".claude/hooks/session-start.sh" + } + ] + } + ] + } +} diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..cde9068 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,29 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. The project defines an open format for teaching AI agents specialized workflows through SKILL.md files. + +## Documentation + +The Agent Skills documentation site, defined in the `docs/` directory, is built with [Mintlify](https://mintlify.com). + +### Quick Start Commands + +```bash +# Install Mintlify CLI (required for local development) +npm i -g mint + +# Run local development server (run from /docs directory) +cd docs && mint dev + +# Update Mintlify CLI if dev server issues occur +mint update +``` + +Local preview available at `http://localhost:3000` + +### Development Notes + +- **Navigation**: Defined in `docs/docs.json` under `navigation.pages` array +- **Adding pages**: Create new `.mdx` file in `/docs`, add filename (without extension) to navigation +- **Deployment**: Automatic on push to `main` branch +- **Troubleshooting**: If page shows 404, ensure you're running `mint dev` from directory containing `docs.json` diff --git a/docs/LICENSE b/docs/LICENSE new file mode 100644 index 0000000..4ea99c2 --- /dev/null +++ b/docs/LICENSE @@ -0,0 +1,395 @@ +Attribution 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution 4.0 International Public License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution 4.0 International Public License ("Public License"). To the +extent this Public License may be interpreted as a contract, You are +granted the Licensed Rights in consideration of Your acceptance of +these terms and conditions, and the Licensor grants You such rights in +consideration of benefits the Licensor receives from making the +Licensed Material available under these terms and conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + d. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + e. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + f. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + g. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + h. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + i. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + j. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + k. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + 4. If You Share Adapted Material You produce, the Adapter's + License You apply must not prevent recipients of the Adapted + Material from complying with this Public License. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material; and + + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..92b6d8e --- /dev/null +++ b/docs/README.md @@ -0,0 +1,33 @@ +# Agent Skills Documentation + +This directory contains the source code for the Agent Skills documentation site, which is built using [Mintlify](https://mintlify.com). + +## Development + +Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally. To install, use the following command: + +``` +npm i -g mint +``` + +Run the following command at the root of your documentation, where your `docs.json` is located: + +``` +mint dev +``` + +View your local preview at `http://localhost:3000`. + +## Publishing changes + +Changes are deployed to production automatically after pushing to the default branch. + +## Need help? + +### Troubleshooting + +- If your dev environment isn't running: Run `mint update` to ensure you have the most recent version of the CLI. +- If a page loads as a 404: Make sure you are running in a folder with a valid `docs.json`. + +### Resources +- [Mintlify documentation](https://mintlify.com/docs) diff --git a/docs/docs.json b/docs/docs.json new file mode 100644 index 0000000..5de63df --- /dev/null +++ b/docs/docs.json @@ -0,0 +1,36 @@ +{ + "$schema": "https://mintlify.com/docs.json", + "theme": "mint", + "name": "Agent Skills", + "colors": { + "primary": "#7f7f7f", + "light": "#bfbfbf", + "dark": "#404040" + }, + "favicon": "/favicon.svg", + "navigation": { + "pages": [ + "home", + "what-are-skills", + "specification", + "integrate-skills" + ] + }, + "contextual": { + "options": [ + "copy", + "view", + "chatgpt", + "claude", + "perplexity", + "mcp", + "cursor", + "vscode" + ] + }, + "footer": { + "socials": { + "github": "https://github.com/agentskills/agentskills" + } + } +} diff --git a/docs/favicon.svg b/docs/favicon.svg new file mode 100644 index 0000000..210d73c --- /dev/null +++ b/docs/favicon.svg @@ -0,0 +1,4 @@ + + + + diff --git a/docs/home.mdx b/docs/home.mdx new file mode 100644 index 0000000..8acdeda --- /dev/null +++ b/docs/home.mdx @@ -0,0 +1,105 @@ +--- +title: "Overview" +description: "A simple, open format for giving agents new capabilities and expertise." +--- + +Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently. + +## Why Agent Skills? + +Agents are increasingly capable, but often don't have the context they need to do real work reliably. Skills solve this by giving agents access to procedural knowledge and company-, team-, and user-specific context they can load on demand. Agents with access to a set of skills can extend their capabilities based on the task they're working on. + +**For skill authors**: Build capabilities once and deploy them across multiple agent products. + +**For compatible agents**: Support for skills lets end users give agents new capabilities out of the box. + +**For teams and enterprises**: Capture organizational knowledge in portable, version-controlled packages. + +## What can Agent Skills enable? + +- **Domain expertise**: Package specialized knowledge into reusable instructions, from legal review processes to data analysis pipelines. +- **New capabilities**: Give agents new capabilities (e.g. creating presentations, building MCP servers, analyzing datasets). +- **Repeatable workflows**: Turn multi-step tasks into consistent and auditable workflows. +- **Interoperability**: Reuse the same skill across different skills-compatible agent products. + +## Adoption + +Agent Skills are supported by leading AI development tools. + +
+ + OpenCode + OpenCode + + + Cursor + Cursor + + + Amp + Amp + + + Letta + Letta + + + Block + Block + + + GitHub + GitHub + + + VS Code + VS Code + + + Claude Code + Claude Code + + + Claude + Claude + +
+ +## Open development + +The Agent Skills format was originally developed by [Anthropic](https://www.anthropic.com/), released as an open standard, and has been adopted by a growing number of agent products. The standard is open to contributions from the broader ecosystem. + +[View on GitHub](https://github.com/agentskills/agentskills) + +## Get started + + + + Learn about skills, how they work, and why they matter. + + + The complete format specification for SKILL.md files. + + + Add skills support to your agent or tool. + + + Browse example skills on GitHub. + + diff --git a/docs/images/logos/amp/amp-logo-dark.svg b/docs/images/logos/amp/amp-logo-dark.svg new file mode 100644 index 0000000..c52b73c --- /dev/null +++ b/docs/images/logos/amp/amp-logo-dark.svg @@ -0,0 +1,3 @@ + + + diff --git a/docs/images/logos/amp/amp-logo-light.svg b/docs/images/logos/amp/amp-logo-light.svg new file mode 100644 index 0000000..15b6f7d --- /dev/null +++ b/docs/images/logos/amp/amp-logo-light.svg @@ -0,0 +1,3 @@ + + + diff --git a/docs/images/logos/block/block-lockup_black.svg b/docs/images/logos/block/block-lockup_black.svg new file mode 100644 index 0000000..bde735c --- /dev/null +++ b/docs/images/logos/block/block-lockup_black.svg @@ -0,0 +1,18 @@ + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/images/logos/block/block-lockup_white.svg b/docs/images/logos/block/block-lockup_white.svg new file mode 100644 index 0000000..fdf9a06 --- /dev/null +++ b/docs/images/logos/block/block-lockup_white.svg @@ -0,0 +1,18 @@ + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/images/logos/claude-ai/Claude-logo-Ivory.svg b/docs/images/logos/claude-ai/Claude-logo-Ivory.svg new file mode 100644 index 0000000..b8b6cef --- /dev/null +++ b/docs/images/logos/claude-ai/Claude-logo-Ivory.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/docs/images/logos/claude-ai/Claude-logo-One-color.svg b/docs/images/logos/claude-ai/Claude-logo-One-color.svg new file mode 100644 index 0000000..1ced12c --- /dev/null +++ b/docs/images/logos/claude-ai/Claude-logo-One-color.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/docs/images/logos/claude-ai/Claude-logo-Slate.svg b/docs/images/logos/claude-ai/Claude-logo-Slate.svg new file mode 100644 index 0000000..7df2b35 --- /dev/null +++ b/docs/images/logos/claude-ai/Claude-logo-Slate.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/docs/images/logos/claude-code/Claude-Code-logo-Ivory.svg b/docs/images/logos/claude-code/Claude-Code-logo-Ivory.svg new file mode 100644 index 0000000..0dc0c2c --- /dev/null +++ b/docs/images/logos/claude-code/Claude-Code-logo-Ivory.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + diff --git a/docs/images/logos/claude-code/Claude-Code-logo-One-color.svg b/docs/images/logos/claude-code/Claude-Code-logo-One-color.svg new file mode 100644 index 0000000..382cbe6 --- /dev/null +++ b/docs/images/logos/claude-code/Claude-Code-logo-One-color.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + diff --git a/docs/images/logos/claude-code/Claude-Code-logo-Slate.svg b/docs/images/logos/claude-code/Claude-Code-logo-Slate.svg new file mode 100644 index 0000000..fce6737 --- /dev/null +++ b/docs/images/logos/claude-code/Claude-Code-logo-Slate.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + diff --git a/docs/images/logos/cursor/LOCKUP_HORIZONTAL_2D_DARK.svg b/docs/images/logos/cursor/LOCKUP_HORIZONTAL_2D_DARK.svg new file mode 100644 index 0000000..5522984 --- /dev/null +++ b/docs/images/logos/cursor/LOCKUP_HORIZONTAL_2D_DARK.svg @@ -0,0 +1,20 @@ + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/images/logos/cursor/LOCKUP_HORIZONTAL_2D_LIGHT.svg b/docs/images/logos/cursor/LOCKUP_HORIZONTAL_2D_LIGHT.svg new file mode 100644 index 0000000..b86ccc7 --- /dev/null +++ b/docs/images/logos/cursor/LOCKUP_HORIZONTAL_2D_LIGHT.svg @@ -0,0 +1,20 @@ + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/images/logos/github/GitHub_Lockup_Dark.svg b/docs/images/logos/github/GitHub_Lockup_Dark.svg new file mode 100644 index 0000000..f75f0fe --- /dev/null +++ b/docs/images/logos/github/GitHub_Lockup_Dark.svg @@ -0,0 +1,33 @@ + + + + + + + + + diff --git a/docs/images/logos/github/GitHub_Lockup_Light.svg b/docs/images/logos/github/GitHub_Lockup_Light.svg new file mode 100644 index 0000000..3879c9f --- /dev/null +++ b/docs/images/logos/github/GitHub_Lockup_Light.svg @@ -0,0 +1,33 @@ + + + + + + + + + diff --git a/docs/images/logos/letta/Letta-logo-RGB_GreyonTransparent.svg b/docs/images/logos/letta/Letta-logo-RGB_GreyonTransparent.svg new file mode 100644 index 0000000..8edf738 --- /dev/null +++ b/docs/images/logos/letta/Letta-logo-RGB_GreyonTransparent.svg @@ -0,0 +1,22 @@ + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/images/logos/letta/Letta-logo-RGB_OffBlackonTransparent.svg b/docs/images/logos/letta/Letta-logo-RGB_OffBlackonTransparent.svg new file mode 100644 index 0000000..c348e4b --- /dev/null +++ b/docs/images/logos/letta/Letta-logo-RGB_OffBlackonTransparent.svg @@ -0,0 +1,22 @@ + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/images/logos/opencode/opencode-wordmark-dark.svg b/docs/images/logos/opencode/opencode-wordmark-dark.svg new file mode 100644 index 0000000..987d393 --- /dev/null +++ b/docs/images/logos/opencode/opencode-wordmark-dark.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/logos/opencode/opencode-wordmark-light.svg b/docs/images/logos/opencode/opencode-wordmark-light.svg new file mode 100644 index 0000000..7a134f4 --- /dev/null +++ b/docs/images/logos/opencode/opencode-wordmark-light.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/images/logos/vscode/vscode-alt.svg b/docs/images/logos/vscode/vscode-alt.svg new file mode 100644 index 0000000..6669915 --- /dev/null +++ b/docs/images/logos/vscode/vscode-alt.svg @@ -0,0 +1,57 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/images/logos/vscode/vscode.svg b/docs/images/logos/vscode/vscode.svg new file mode 100644 index 0000000..c453e63 --- /dev/null +++ b/docs/images/logos/vscode/vscode.svg @@ -0,0 +1,41 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/integrate-skills.mdx b/docs/integrate-skills.mdx new file mode 100644 index 0000000..1039180 --- /dev/null +++ b/docs/integrate-skills.mdx @@ -0,0 +1,81 @@ +--- +title: "Integrate skills into your agent" +sidebarTitle: "Integrate skills" +description: "How to add Agent Skills support to your agent or tool." +--- + +This guide explains how to add skills support to an AI agent or development tool. + +## Integration approaches + +The two main approaches to integrating skills are: + +**Filesystem-based agents** operate within a computer environment (bash/unix) and represent the most capable option. Skills are activated when models issue shell commands like `cat /path/to/my-skill/SKILL.md`. Bundled resources are accessed through shell commands. + +**Tool-based agents** function without a dedicated computer environment. Instead, they implement tools allowing models to trigger skills and access bundled assets. The specific tool implementation is up to the developer. + +## Overview + +A skills-compatible agent needs to: + +1. **Discover** skills in configured directories +2. **Load metadata** (name and description) at startup +3. **Match** user tasks to relevant skills +4. **Activate** skills by loading full instructions +5. **Execute** scripts and access resources as needed + +## Skill discovery + +Skills are folders containing a `SKILL.md` file. Your agent should scan configured directories for valid skills. + +## Loading metadata + +At startup, parse only the frontmatter of each `SKILL.md` file. This keeps initial context usage low. + +### Parsing frontmatter + +``` +function parseMetadata(skillPath): + content = readFile(skillPath + "/SKILL.md") + frontmatter = extractYAMLFrontmatter(content) + + return { + name: frontmatter.name, + description: frontmatter.description, + path: skillPath + } +``` + +### Injecting into context + +Include skill metadata in the system prompt so the model knows what skills are available. + +Follow your platform's guidance for system prompt updates. For example, for Claude models, the recommended format uses XML: + +```xml + + + pdf-processing + Extracts text and tables from PDF files, fills forms, merges documents. + /path/to/skills/pdf-processing/SKILL.md + + + data-analysis + Analyzes datasets, generates charts, and creates summary reports. + /path/to/skills/data-analysis/SKILL.md + + +``` + +For filesystem-based agents, include the `location` field with the absolute path to the SKILL.md file. For tool-based agents, the location can be omitted. + +Keep metadata concise. Each skill should add roughly 50-100 tokens to the context. + +## Security considerations + +Script execution introduces security risks. Consider: + +- **Sandboxing**: Run scripts in isolated environments +- **Allowlisting**: Only execute scripts from trusted skills +- **Confirmation**: Ask users before running potentially dangerous operations +- **Logging**: Record all script executions for auditing diff --git a/docs/specification.mdx b/docs/specification.mdx new file mode 100644 index 0000000..987f631 --- /dev/null +++ b/docs/specification.mdx @@ -0,0 +1,218 @@ +--- +title: "Specification" +description: "The complete format specification for Agent Skills." +--- + +This document defines the Agent Skills format. + +## Directory structure + +A skill is a directory containing at minimum a `SKILL.md` file: + +``` +skill-name/ +└── SKILL.md # Required +``` + + +You can optionally include [additional directories](#optional-directories) such as `scripts/`, `references/`, and `assets/` to support your skill. + + +## SKILL.md format + +The `SKILL.md` file must contain YAML frontmatter followed by Markdown content. + +### Frontmatter (required) + +```yaml +--- +name: skill-name +description: A description of what this skill does and when to use it. +--- +``` + +With optional fields: + +```yaml +--- +name: pdf-processing +description: Extract text and tables from PDF files, fill forms, merge documents. +license: Apache-2.0 +metadata: + author: example-org + version: "1.0" +--- +``` + +| Field | Required | Constraints | +|-------|----------|-------------| +| `name` | Yes | Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. | +| `description` | Yes | Max 1024 characters. Non-empty. Describes what the skill does and when to use it. | +| `license` | No | License name or reference to a bundled license file. | +| `compatibility` | No | Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.). | +| `metadata` | No | Arbitrary key-value mapping for additional metadata. | +| `allowed-tools` | No | Space-delimited list of pre-approved tools the skill may use. (Experimental) | + +#### `name` field + +The required `name` field: +- Must be 1-64 characters +- May only contain unicode lowercase alphanumeric characters and hyphens (`a-z` and `-`) +- Must not start or end with `-` +- Must not contain consecutive hyphens (`--`) +- Must match the parent directory name + +Valid examples: +```yaml +name: pdf-processing +``` +```yaml +name: data-analysis +``` +```yaml +name: code-review +``` + +Invalid examples: +```yaml +name: PDF-Processing # uppercase not allowed +``` +```yaml +name: -pdf # cannot start with hyphen +``` +```yaml +name: pdf--processing # consecutive hyphens not allowed +``` + +#### `description` field + +The required `description` field: +- Must be 1-1024 characters +- Should describe both what the skill does and when to use it +- Should include specific keywords that help agents identify relevant tasks + +Good example: +```yaml +description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction. +``` + +Poor example: +```yaml +description: Helps with PDFs. +``` + +#### `license` field + +The optional `license` field: +- Specifies the license applied to the skill +- We recommend keeping it short (either the name of a license or the name of a bundled license file) + +Example: +```yaml +license: Proprietary. LICENSE.txt has complete terms +``` + +#### `compatibility` field + +The optional `compatibility` field: +- Must be 1-500 characters if provided +- Should only be included if your skill has specific environment requirements +- Can indicate intended product, required system packages, network access needs, etc. + +Examples: +```yaml +compatibility: Designed for Claude Code (or similar products) +``` +```yaml +compatibility: Requires git, docker, jq, and access to the internet +``` + + +Most skills do not need the `compatibility` field. + + +#### `metadata` field + +The optional `metadata` field: +- A map from string keys to string values +- Clients can use this to store additional properties not defined by the Agent Skills spec +- We recommend making your key names reasonably unique to avoid accidental conflicts + +Example: +```yaml +metadata: + author: example-org + version: "1.0" +``` + +#### `allowed-tools` field + +The optional `allowed-tools` field: +- A space-delimited list of tools that are pre-approved to run +- Experimental. Support for this field may vary between agent implementations + +Example: +```yaml +allowed-tools: Bash(git:*) Bash(jq:*) Read +``` + +### Body content + +The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions. Write whatever helps agents perform the task effectively. + +Recommended sections: +- Step-by-step instructions +- Examples of inputs and outputs +- Common edge cases + +Note that the agent will load this entire file once it's decided to activate a skill. Consider splitting longer `SKILL.md` content into referenced files. + +## Optional directories + +### scripts/ + +Contains executable code that agents can run. Scripts should: +- Be self-contained or clearly document dependencies +- Include helpful error messages +- Handle edge cases gracefully + +Supported languages depend on the agent implementation. Common options include Python, Bash, and JavaScript. + +### references/ + +Contains additional documentation that agents can read when needed: +- `REFERENCE.md` - Detailed technical reference +- `FORMS.md` - Form templates or structured data formats +- Domain-specific files (`finance.md`, `legal.md`, etc.) + +Keep individual [reference files](#file-references) focused. Agents load these on demand, so smaller files mean less use of context. + +### assets/ + +Contains static resources: +- Templates (document templates, configuration templates) +- Images (diagrams, examples) +- Data files (lookup tables, schemas) + +## Progressive disclosure + +Skills should be structured for efficient use of context: + +1. **Metadata** (~100 tokens): The `name` and `description` fields are loaded at startup for all skills +2. **Instructions** (< 5000 tokens recommended): The full `SKILL.md` body is loaded when the skill is activated +3. **Resources** (as needed): Files (e.g. those in `scripts/`, `references/`, or `assets/`) are loaded only when required + +Keep your main `SKILL.md` under 500 lines. Move detailed reference material to separate files. + +## File references + +When referencing other files in your skill, use relative paths from the skill root: + +```markdown +See [the reference guide](references/REFERENCE.md) for details. + +Run the extraction script: +scripts/extract.py +``` + +Keep file references one level deep from `SKILL.md`. Avoid deeply nested reference chains. diff --git a/docs/style.css b/docs/style.css new file mode 100644 index 0000000..856a237 --- /dev/null +++ b/docs/style.css @@ -0,0 +1,206 @@ +#content-area { + --font-mono: var(--font-jetbrains-mono), ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; /* via Mintlify theme */ + + h5 { + font-weight: 500; + } + + h6 { + font-weight: 400; + } +} + +#feature-support-matrix-wrapper table { + width: 100%; + table-layout: fixed; + font-size: 0.75rem; +} + +#feature-support-matrix-wrapper td, +#feature-support-matrix-wrapper th { + padding: 0.25rem; + text-align: center; +} + +/* Left align Client column */ +#feature-support-matrix-wrapper td:first-child, +#feature-support-matrix-wrapper th:first-child { + text-align: left; +} + + + +/*** Add automatic section numbers to headings and table of contents items ***/ + +#enable-section-numbers { + display: none; +} + +body:has(#enable-section-numbers) { + #content-area, + #table-of-contents { + counter-reset: h2-counter h3-counter h4-counter h5-counter h6-counter; + } + + #content-area h2[id], + #table-of-contents li[data-depth="0"] { + counter-set: h3-counter h4-counter h5-counter h6-counter; + } + + #content-area h3[id], + #table-of-contents li[data-depth="1"] { + counter-set: h4-counter h5-counter h6-counter; + } + + #content-area h4[id], + #table-of-contents li[data-depth="2"] { + counter-set: h5-counter h6-counter; + } + + #content-area h5[id], + #content-area h5, + #table-of-contents li[data-depth="3"] { + counter-set: h6-counter; + } + + #content-area h2[id]::before, + #table-of-contents li[data-depth="0"] a::before { + counter-increment: h2-counter; + content: counter(h2-counter) ". "; + } + + #content-area h3[id]::before, + #table-of-contents li[data-depth="1"] a::before { + counter-increment: h3-counter; + content: counter(h2-counter) "." counter(h3-counter) " "; + } + + #content-area h4[id]::before, + #table-of-contents li[data-depth="2"] a::before { + counter-increment: h4-counter; + content: counter(h2-counter) "." counter(h3-counter) "." counter(h4-counter) + " "; + } + + #content-area h5[id]::before, + #content-area h5::before, + #table-of-contents li[data-depth="3"] a::before { + counter-increment: h5-counter; + content: counter(h2-counter) "." counter(h3-counter) "." counter(h4-counter) + "." counter(h5-counter) " "; + } + + #content-area h6[id]::before, + #content-area h6::before, + #table-of-contents li[data-depth="4"] a::before { + counter-increment: h6-counter; + content: counter(h2-counter) "." counter(h3-counter) "." counter(h4-counter) + "." counter(h5-counter) "." counter(h6-counter) " "; + } +} + + + +/*** Page: schema reference ***/ + +#schema-reference { + display: none; +} + +body:has(#schema-reference) { + .tsd-comment { + :is(p, ul, ol):first-child { + margin-top: 0; + } + + :is(p, ul, ol):last-child { + margin-bottom: 0; + } + } + + .tsd-signature { + font-family: var(--font-mono); + font-size: 0.875rem; + line-height: 1.5rem; + + /* Based on code blocks rendered by Mintlify **on the production site**. */ + margin: 1.25rem 0; + border: 1px solid; + border-color: light-dark(rgb(var(--gray-950)/.1), rgba(255, 255, 255, 0.1)); + border-radius: 1rem; + padding: 1rem 0.875rem; + + a { + font-weight: normal; + border-bottom: none; + text-decoration: underline; + + &:hover { + text-decoration-thickness: 2px; + } + } + + a[href="#"] { + pointer-events: none; + color: inherit; + text-decoration: none; + } + + .tsd-signature-keyword { + color: light-dark(rgb(207, 34, 46), #9CDCFE); + } + + :is(.tsd-kind-interface, .tsd-kind-type-alias):not(.tsd-signature-type) { + color: light-dark(rgb(149, 56, 0), #4EC9B0); + } + + .tsd-signature-type:not(.tsd-kind-interface, .tsd-kind-type-alias) { + color: light-dark(rgb(5, 80, 174), #DCDCAA); + } + } + + .tsd-member { + margin: 1.25rem 0; + + [data-typedoc-h="3"] { + margin: 0.5rem 0; + + font-family: var(--font-mono); + font-weight: 700; + + scroll-margin-top: 8rem; + } + + & > .tsd-comment, + & > .tsd-type-declaration { + margin-left: 1.25rem; + } + + .tsd-type-declaration { + [data-typedoc-h="4"] { + display: none; + } + + [data-typedoc-h="4"] + ul { + margin-top: 0; + } + + [data-typedoc-h="5"] { + font-family: var(--font-mono); + font-size: 0.875rem; + font-weight: 500; + + width: fit-content; + padding: 0.125em 0.5em; + background-color: light-dark(rgb(var(--gray-100)/.5), rgb(255 255 255/.05)); + } + } + + .tsd-anchor-icon, + .tsd-tag, + .tsd-signature, + .tsd-sources { + display: none; + } + } +} \ No newline at end of file diff --git a/docs/what-are-skills.mdx b/docs/what-are-skills.mdx new file mode 100644 index 0000000..829c938 --- /dev/null +++ b/docs/what-are-skills.mdx @@ -0,0 +1,70 @@ +--- +title: "What are skills?" +description: "Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows." +--- + +At its core, a skill is a folder containing a `SKILL.md` file. This file includes metadata (`name` and `description`, at minimum) and instructions that tell an agent how to perform a specific task. Skills can also bundle scripts, templates, and reference materials. + +```directory +my-skill/ +├── SKILL.md # Required: instructions + metadata +├── scripts/ # Optional: executable code +├── references/ # Optional: documentation +└── assets/ # Optional: templates, resources +``` + +## How skills work + +Skills use **progressive disclosure** to manage context efficiently: + +1. **Discovery**: At startup, agents load only the name and description of each available skill, just enough to know when it might be relevant. + +2. **Activation**: When a task matches a skill's description, the agent reads the full `SKILL.md` instructions into context. + +3. **Execution**: The agent follows the instructions, optionally loading referenced files or executing bundled code as needed. + +This approach keeps agents fast while giving them access to more context on demand. + +## The SKILL.md file + +Every skill starts with a `SKILL.md` file containing YAML frontmatter and Markdown instructions: + +```mdx +--- +name: pdf-processing +description: Extract text and tables from PDF files, fill forms, merge documents. +--- + +# PDF Processing + +## When to use this skill +Use this skill when the user needs to work with PDF files... + +## How to extract text +1. Use pdfplumber for text extraction... + +## How to fill forms +... +``` + +The frontmatter is required: + +- `name`: A short identifier +- `description`: When to use this skill + +The Markdown body contains the actual instructions and has no specific restrictions on structure or content. + +This simple format has some key advantages: + +**Version-controlled**: Skills are files and therefore work naturally with Git. + +**Self-documenting**: A skill author or user can read a `SKILL.md` and understand what it does, making skills easy to audit and improve. + +**Extensible**: Skills can range in complexity, since they can contain text instructions, scripts, assets, templates, or reference docs. + +## Next steps + +- [View the specification](/specification) to understand the full format. +- [Add skills support to your agent](/integrate-skills) to build a compatible client. +- [See example skills](https://github.com/anthropics/skills) on GitHub. +- [Read authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) for writing effective skills.