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>
* Add "Using scripts" guide for skill creators
New guide at `docs/skill-creation/using-scripts.mdx` covering how to use
commands and scripts in skills:
- One-off commands with `uvx`, `pipx`, `npx`, `bunx`, `go run`,
`deno run` (tabbed by ecosystem, with pinned version examples)
- Referencing bundled scripts from `SKILL.md` using relative paths
- Self-contained scripts with inline dependency declarations (PEP 723,
Deno `npm:` imports, Bun auto-install, Ruby `bundler/inline` — tabbed
with a common HTML-parsing example)
- Designing scripts for agentic use: non-interactive execution, `--help`
documentation, error messages, structured output, and a compressed
checklist of further considerations
Also updates `docs/docs.json` to organize navigation into groups ("For
skill creators" and "For client implementors").
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Address review feedback on "Using scripts" guide
Relative paths note: Clarify that the convention applies to support
files like `references/*.md`, and explain *why* (the agent runs commands
from the skill root).
Structured output: Reframe motivation around composability with both
agents and standard tools (`jq`, `cut`, `awk`) rather than LLM parsing
ambiguity. Shorten prose; let the code example's inline comments carry
the contrast.
Predictable output size: Add `--output` flag as an alternative strategy
for scripts whose output is large and not amenable to pagination. The
`--output` flag acts as a consent mechanism — the agent must explicitly
choose a file destination or pass `-` to opt in to stdout, preventing
accidental context-window flooding.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Jonathan HefnerandClaude Opus 4.6
Eric HarmelingandGitHub