How-to guide covering the full description optimization workflow:
writing effective descriptions, designing trigger eval queries
(should-trigger and should-not-trigger with near-miss examples), testing
trigger rates with a bash eval script, train/validation splits to avoid
overfitting, and the iterative optimization loop.
The guide is client-agnostic by default but includes a working Claude
Code example in the `check_triggered` function using
`--output-format json` and `jq` to detect `Skill` tool calls.
Adds the page to the "For skill creators" navigation group in
`docs.json`.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* Add comprehensive "Integrating skills" guide for client implementors
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>
* Address PR review feedback on integrating skills guide
- 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>
* Rename "Integrating skills" guide to "Adding skills support"
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>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
A how-to guide for evaluating skill output quality using structured
evals. Covers the full eval workflow: designing test cases, running
with-skill vs. baseline comparisons, writing assertions, LLM-based
grading, aggregating benchmarks, analyzing patterns, human review, and
LLM-driven iterative improvement.
Derived from the workflow implemented by the `skill-creator` Skill, but
written as a standalone guide that readers can follow without using that
tool.
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 Hefner ·
Eric Harmeling ·