The logo carousel previously used a per-logo `width` property (e.g.
`"120px"`, `"200px"`) with a fallback default of `"150px"`. This made
logo sizing an absolute, context-specific value tied to the carousel
layout.
Replace `width` with a relative `scale` multiplier (e.g. `0.8`, `1.33`)
that each consuming component can apply to its own base width. This
prepares for sharing the logo data array between `LogoCarousel` and
other components, where the base width might differ. Logos without a
`scale` property default to 1.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Vendor descriptions sourced verbatim from each client's own website or
GitHub repository. The `description` field is placed immediately after
`name` in each entry, grouping identity metadata together.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Mintlify enables click-to-zoom on all `<img>` elements by default. This
caused clicking a carousel logo to both open the vendor link in a new
tab AND zoom the logo to fullscreen in the original tab. Adding `noZoom`
disables the lightbox so only the link navigation fires.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove the inner hexagon path with white stroke from `docs/favicon.svg`,
leaving a single solid black hexagon to match the updated logo.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
`shuf` is a GNU coreutil which requires `brew install coreutils` on
macOS. Replace it with `echo $((RANDOM % <sides> + 1))` which works in
bash and zsh on both Linux and macOS.
Also reword "true randomness" to "using a random number generator" to
more clearly distinguish programmatic RNG from LLM non-determinism.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds a Discord entry to the Getting Started list in `README.md` and
replaces the standalone "View on GitHub" link in `docs/home.mdx` with a
sentence inviting readers to join on GitHub or Discord.
Also applies minor formatting cleanup in `README.md`: bolds the link
text and switches hyphens to em dashes for consistency.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add a third example showing a Python version requirement alongside `uv`.
This complements the existing examples (product targeting and system
tool requirements) by demonstrating version-pinned runtime requirements
— the kind of non-obvious constraint that the `compatibility` field is
useful for.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds a tutorial-style quickstart guide that walks the reader through
creating their first Agent Skill — a `roll-dice` skill that teaches an
agent to roll dice using true system randomness. The guide covers
creating the `SKILL.md` file, verifying discovery via `/skills` in VS
Code, testing with a "Roll a d20" prompt, and a brief explanation of the
discovery/activation/execution lifecycle. Includes both bash and
PowerShell command variants, and a note about model variation in
tool-use reliability.
Also adds the quickstart as the first page under "For skill creators" in
`docs.json` navigation.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add a new "Gotchas sections" subsection to "Patterns for effective
instructions" in the best practices guide. Covers what a gotcha is
(environment-specific facts that defy reasonable assumptions), how to
structure them (problem/correction pairs), and why they belong directly
in `SKILL.md` rather than a separate reference file.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Show `csv-analyzer/` (containing `SKILL.md` and `evals/evals.json`)
alongside `csv-analyzer-workspace/` so readers can see the full layout
at a glance.
Closes#238. Closes#239.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The frontmatter `description` already serves as the page subtitle in
Mintlify, so the "This document defines the Agent Skills format." line
was just restating it.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The directory listing is not exhaustive — skill authors can include
other files and subdirectories beyond those shown. Adding a `...` entry
makes this explicit.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Place the field constraints table immediately after the `Frontmatter`
heading so readers see the reference before the examples. Also remove
"(required)" from the heading, wrap examples in a `<Card>`, and relabel
"With optional fields:" to "Example with optional fields:".
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The fenced code blocks showing `SKILL.md` content were labeled as `yaml`
or plain `markdown`. Changing them to `markdown SKILL.md` adds a
filename hint and more accurately reflects that they contain full
`SKILL.md` snippets (including `---` frontmatter delimiters), not just
raw YAML.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The `####` field headings didn't stand out enough amongst all the code
blocks, making the page hard to scan. Wrapping each field's examples in
a `<Card>` draws a border around them and adds padding, so each
subsection looks more contained instead of bleeding into the next. Also
bolds the example labels within each card.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Show optional directories (`scripts/`, `references/`, `assets/`)
directly in the directory tree with inline annotations, replacing the
separate `<Tip>` block.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Place inline code examples next to the terms they describe (e.g.,
"`a-z`" next to "alphanumeric characters") rather than grouping them at
the end. Also add the word "hyphen" before the code-formatted `-` for
readability.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Wrap `SKILL.md`, `scripts/`, `references/`, and `assets/` headings in
backticks for consistency with the rest of the document, which already
uses inline code formatting for these names in body text.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The example `description` values in what-are-skills.mdx and
specification.mdx only described what the skill does, but omitted
when to use it. This contradicted the spec's own guidance that
description should cover both. Added a "Use when..." clause while
keeping the line short enough to avoid clipping in the rendered
code block on the docs site.
Add documentation and source code URLs to each client's logo entry in
`LogoCarousel.jsx`. These fields aren't rendered yet, but serve as
structured metadata that future PRs can build on. Including them now
also encourages contributors adding new clients to provide these URLs,
and makes entries easier to verify during review.
Also reformats logo entries from single-line objects to multi-line for
readability.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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 package.json to docs for local mint dev dependency
Allow installing mint as a local dev dependency instead of requiring
a global install, making the setup more reproducible.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Use npx mint dev to avoid mint version bug
Address PR review feedback: the mint package has a bug that causes it
to use the wrong version when installed as an npm dependency. Switch to
npx mint dev, remove the devDependency and package-lock.json, and
simplify docs accordingly.
* Move `package.json` to repo root and clean up docs
Move the `package.json` from `docs/` to the repo root so `npm run dev`
works from anywhere in the repository. Update `CLAUDE.md` instructions
to match, trim boilerplate from `docs/README.md`, and link to the live
documentation site.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Jonathan Hefner <jonathan@hefner.pro>
* 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>
* Add OpenHands logo to adoption carousel
OpenHands is an AI software development platform that natively supports
Agent Skills, enabling users to extend agent capabilities with specialized
knowledge and workflows.
Changes:
- Added openhands-logo-light.svg and openhands-logo-dark.svg to /docs/images/logos/openhands/
- Added OpenHands entry to LogoCarousel.jsx
Website: https://www.all-hands.dev/
* Update OpenHands logos to full color versions
---------
Co-authored-by: jamiechicago312 <jamiechicago312@users.noreply.github.com>
Co-authored-by: openhands <openhands@all-hands.dev>
Replace the placeholder `[yyyy] [name of copyright owner]` with
`2025 Anthropic, PBC` to match the project's origin date and maintainer.
Closes#145
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Covers types of welcome contributions (docs, bug reports, proposals),
ecosystem listing & logo request process, development setup for the docs
site, submitting changes, and AI contribution disclosure policy (adapted
from the MCP project).
Directs proposals and feature requests to GitHub Discussions, reserving
Issues for bug reports. Notes that `skills-ref/` is not accepting code
contributions and that skill submissions and major architectural changes
are not being accepted at this time.
License section reflects dual licensing: Apache 2.0 for code and spec,
CC-BY 4.0 for documentation.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Jonathan HefnerandClaude Opus 4.6
Arun Nair
Koichi ITO
Arne StrickmannandGitHub
Irina ChichikovaandGitHub