From f990ba148d8ff2bdc0edd7a56a79b303fbd5727f Mon Sep 17 00:00:00 2001
From: Eric Harmeling <eric.harmeling@outlook.com>
Date: Thu, 18 Dec 2025 10:19:21 -0500
Subject: [PATCH] Document reference SDK (#3)

* Document reference SDK

* Update docs/integrate-skills.mdx

Co-authored-by: Keith Lazuka <klazuka@anthropic.com>

---------

Co-authored-by: Keith Lazuka <klazuka@anthropic.com>
---
 CLAUDE.md => docs/CLAUDE.md |  0
 docs/home.mdx               |  9 ++++++++-
 docs/integrate-skills.mdx   | 18 ++++++++++++++++++
 docs/specification.mdx      | 10 ++++++++++
 docs/what-are-skills.mdx    |  1 +
 5 files changed, 37 insertions(+), 1 deletion(-)
 rename CLAUDE.md => docs/CLAUDE.md (100%)

diff --git a/CLAUDE.md b/docs/CLAUDE.md
similarity index 100%
rename from CLAUDE.md
rename to docs/CLAUDE.md
diff --git a/docs/home.mdx b/docs/home.mdx
index 8acdeda..30447dc 100644
--- a/docs/home.mdx
+++ b/docs/home.mdx
@@ -73,7 +73,7 @@ The Agent Skills format was originally developed by [Anthropic](https://www.anth
 
 ## Get started
 
-<CardGroup cols={2}>
+<CardGroup cols={3}>
   <Card
     title="What are skills?"
     icon="lightbulb"
@@ -102,4 +102,11 @@ The Agent Skills format was originally developed by [Anthropic](https://www.anth
   >
     Browse example skills on GitHub.
   </Card>
+  <Card
+    title="Reference library"
+    icon="wrench"
+    href="https://github.com/agentskills/agentskills/tree/main/skills-ref"
+  >
+    Validate skills and generate prompt XML.
+  </Card>
 </CardGroup>
diff --git a/docs/integrate-skills.mdx b/docs/integrate-skills.mdx
index 1039180..8f48234 100644
--- a/docs/integrate-skills.mdx
+++ b/docs/integrate-skills.mdx
@@ -79,3 +79,21 @@ Script execution introduces security risks. Consider:
 - **Allowlisting**: Only execute scripts from trusted skills
 - **Confirmation**: Ask users before running potentially dangerous operations
 - **Logging**: Record all script executions for auditing
+
+## Reference implementation
+
+The [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) library provides Python utilities and a CLI for working with skills.
+
+For example:
+
+**Validate a skill directory:** 
+```
+skills-ref validate <path>
+```
+
+**Generate `<available_skills>` XML for agent prompts:**
+```
+skills-ref to-prompt <path>...
+```
+
+Use the library source code as a reference implementation.
diff --git a/docs/specification.mdx b/docs/specification.mdx
index 987f631..8fe6577 100644
--- a/docs/specification.mdx
+++ b/docs/specification.mdx
@@ -216,3 +216,13 @@ scripts/extract.py
 ```
 
 Keep file references one level deep from `SKILL.md`. Avoid deeply nested reference chains.
+
+## Validation
+
+Use the [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) reference library to validate your skills:
+
+```bash
+skills-ref validate ./my-skill
+```
+
+This checks that your `SKILL.md` frontmatter is valid and follows all naming conventions.
diff --git a/docs/what-are-skills.mdx b/docs/what-are-skills.mdx
index 829c938..6b52b60 100644
--- a/docs/what-are-skills.mdx
+++ b/docs/what-are-skills.mdx
@@ -68,3 +68,4 @@ This simple format has some key advantages:
 - [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.
+- [Use the reference library](https://github.com/agentskills/agentskills/tree/main/skills-ref) to validate skills and generate prompt XML.