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>
The `logo-scroll` keyframe translated by `-50%`, but flex `gap: 3rem`
means `2N` duplicated items have `2N - 1` gaps — so the track doesn't
split evenly at 50%. The seam between the two copies sits at
`50% + half a gap`. Adjusting to `calc(-50% - 1.5rem)` aligns the
animation endpoint with the start of the second copy, eliminating the
visible jump every 50 seconds.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace the plain bold-text blockquote with GitHub's alert syntax so the
"not for production" notice renders with a colored icon and background,
making it harder to miss.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file was originally copied from the modelcontextprotocol repo.
These styles were specific to MCP documentation pages and are not used
here:
- `#feature-support-matrix-wrapper` table styling
- `#schema-reference` TypeScript documentation styling
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Add top-level LICENSE file (Apache 2.0) and a License section to
README documenting the dual-license structure: Apache 2.0 for code,
CC-BY-4.0 for documentation.
Closes#121
* Create todo.md
* Add files via upload
* Delete docs/images/logos/mistral-vibe/todo.md
* add mistral ai vibe to doc
* added black and white versions
* update whiteblack logos
* add vibe to carousel
* swap light dark
---------
Co-authored-by: jaccolor <jac_color@protonmail.com>
Co-authored-by: Eric Harmeling <eric.harmeling@outlook.com>
* Add Firebender logo
Adds logo for android focused coding agent, Firebender that supports skills
Resolves#71🤖 Generated with [Firebender](https://firebender.com)
Co-Authored-By: Firebender <help@firebender.com>
* fix: replace low-res Firebender SVG logos with high-resolution versions
Updated both light and dark wordmark SVGs with high-resolution exports from Figma.
Old viewBox: ~145x18 / 161x20
New viewBox: 2151x267
This addresses the resolution concerns in PR feedback.
🤖 Generated with [Firebender](https://firebender.com)
Co-Authored-By: Firebender <help@firebender.com>
---------
Co-authored-by: Firebender <help@firebender.com>
Jonathan HefnerandClaude Opus 4.6
Koichi ITO
Arne StrickmannandGitHub
Irina ChichikovaandGitHub
Nnenna NdukweandGitHub
Mahesh MuragandGitHub
Eric Harmeling
Vinh NguyenandEric Harmeling
Igor CostaandGitHub
bl-ueandGitHub
