Add comprehensive "Integrating skills" guide for client implementors#200
Conversation
Replace the existing `integrate-skills.mdx` page with a thorough, research-backed guide at `client-implementation/integrating-skills.mdx`. The guide covers the full Agent Skills integration lifecycle in five steps: discover, parse, disclose, activate, and manage context. It was developed from analysis of seven real-world implementations (OpenCode, Pi, Gemini CLI, Codex, VS Code Copilot Chat, Goose, OpenHands) and addresses the practical design decisions developers face: progressive disclosure architecture, cross-client `.agents/skills/` interoperability, lenient YAML parsing for compatibility, catalog XML format, behavioral instruction templates (derived from Pi's production prompts), file-read vs. dedicated tool activation, structured wrapping for context compaction, and permission allowlisting for bundled resources. The guide is architecture-neutral — it covers local filesystem agents, cloud-hosted/sandboxed agents, and agents with or without file-read capabilities, framing these as independent design choices rather than rigid categories. Also adds a redirect from the old `/integrate-skills` URL and updates all internal links (`docs.json`, `home.mdx`, `what-are-skills.mdx`). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
| description: "A guide for adding Agent Skills support to an AI agent or development tool." | ||
| --- | ||
|
|
||
| This guide walks through how to add Agent Skills support to an AI agent or development tool. It covers the full lifecycle: discovering skills, telling the model about them, loading their content into context, and keeping that content effective over time. |
There was a problem hiding this comment.
can we add a callout to handle regular people that just want to use skills but have ended up looking in the wrong location?
There was a problem hiding this comment.
We can add a callout, but I'm wondering if it would be better to address the source of confusion, which I assume is the phrase "Integrating skills" — i.e., someone might interpret that as "integrating skills into my workflow" instead of "integrating skills support into a client".
In that case, what do you think about rephrasing as "Supporting skills" or "Adding skills support"?
There was a problem hiding this comment.
i like your suggestions. "Adding skills support" seems like a better direction.
|
|
||
| Two approaches are common: | ||
|
|
||
| **System prompt section**: Add the catalog as a labeled section in the system prompt, preceded by brief instructions on how to use skills. This is the simplest approach and works with any model. |
There was a problem hiding this comment.
This is the simplest approach and works with any model.
i'd say that it works as long as your agent has some kind of "file read" tool.
|
|
||
| For each discovered skill, include `name`, `description`, and optionally `location` (the path to the `SKILL.md` file): | ||
|
|
||
| ```xml |
There was a problem hiding this comment.
I think it'd be worth mentioned that this XML-based format is just a suggestion. The background story is that recent Claude models have been trained on this format, so we do expect it to work better than other formats. But at the end of the day, when I did some testing with Opus 4.6, it didn't matter if we used XML or some other comparable format.
They can also just list them out in a simple bulleted list format like Claude Code does.
- Clarify that the XML catalog format is just one option — JSON or bulleted lists work equally well - Qualify "works with any model" to note it requires a file-reading tool Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Addresses reviewer feedback that "Integrating" could be misread as integrating skills into a workflow rather than into a client. Renames `integrating-skills.mdx` to `adding-skills-support.mdx` and updates all references in `docs.json`, `home.mdx`, and `what-are-skills.mdx`. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace the existing
integrate-skills.mdxpage with a thorough, research-backed guide atclient-implementation/integrating-skills.mdx.The guide covers the full Agent Skills integration lifecycle in five steps: discover, parse, disclose, activate, and manage context. It was developed from analysis of seven real-world implementations (OpenCode, Pi, Gemini CLI, Codex, VS Code Copilot, Goose, OpenHands) and addresses the practical design decisions developers face: progressive disclosure architecture, cross-client
.agents/skills/interoperability, lenient YAML parsing for compatibility, catalog XML format, behavioral instruction templates (derived from Pi's production prompts), file-read vs. dedicated tool activation, structured wrapping for context compaction, and permission allowlisting for bundled resources.The guide is architecture-neutral — it covers local filesystem agents, cloud-hosted/sandboxed agents, and agents with or without file-read capabilities, framing these as independent design choices rather than rigid categories.
Also adds a redirect from the old
/integrate-skillsURL and updates all internal links (docs.json,home.mdx,what-are-skills.mdx).Preview: https://agent-skills-jh-add-client-how-to-guide.mintlify.app/client-implementation/adding-skills-support