68 Commits

• Use precise type name for allowed-tools field

  Replace "space-delimited list" with "space-separated string" in both the
  frontmatter table and the `allowed-tools` field section. This better
  reflects that the value is a YAML scalar, per the given example.
  
  Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

  Jonathan Hefner · 2026-03-30 12:11:35 -05:00
  6f92fcdb78
• Merge pull request #279 from jonathanhefner/fix-carousel-logo-takeover

  Add `noZoom` to logo carousel images

  Jonathan Hefner · 2026-03-27 12:12:41 -05:00
  5e7f3e2c4c
• Add noZoom to logo carousel images

  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>

  Jonathan Hefner · 2026-03-27 10:05:14 -05:00
  5343c3f42b
• Replace nested hexagon favicon with solid hexagon

  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>

  Jonathan Hefner · 2026-03-27 09:30:13 -05:00
  85ef34c715
• Replace shuf with $RANDOM in quickstart for broader compatibility

  `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>

  Jonathan Hefner · 2026-03-23 11:25:26 -05:00
  d7dba49441
• Merge pull request #274 from jonathanhefner/discord-link

  Add Discord links to `README.md` and `docs/home.mdx`

  Jonathan Hefner · 2026-03-23 10:44:50 -05:00
  d91d26d0ab
• Add Discord links to README.md and docs/home.mdx

  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>

  Jonathan Hefner · 2026-03-23 10:41:25 -05:00
  84672e62b9
• Merge pull request #261 from nairteashop/add-kiro-logo

  Add Kiro logo to carousel.

  Jonathan Hefner · 2026-03-20 10:40:12 -05:00
  2fbfc322d5
• Merge pull request #253 from jonathanhefner/compatibility-field-show-versioning

  Add runtime version example to `compatibility` field

  Jonathan Hefner · 2026-03-19 18:24:03 -05:00
  5bb99345b3
• Add Kiro logo.
  Arun Nair · 2026-03-19 16:08:01 -07:00
  cc89b9c41a
• Add runtime version example to compatibility field

  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>

  Jonathan Hefner · 2026-03-16 12:05:26 -05:00
  99b8edf685
• Add quickstart guide for skill creators

  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>

  Jonathan Hefner · 2026-03-16 10:35:35 -05:00
  3fccd701c1
• Merge pull request #248 from jonathanhefner/add-gotchas-section-to-best-practices

  Add gotchas section to best practices guide

  Jonathan Hefner · 2026-03-16 09:50:36 -05:00
  e42cbd6f8a
• Merge pull request #240 from jonathanhefner/clarify-skill-eval-file-tree

  Add skill directory to structure diagram in evaluating skills doc

  Jonathan Hefner · 2026-03-16 09:47:42 -05:00
  5cd19050c9
• Add gotchas section to best practices guide

  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>

  Jonathan Hefner · 2026-03-15 17:32:38 -05:00
  4be62ebad0
• Add skill directory to structure diagram in evaluating skills doc

  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>

  Jonathan Hefner · 2026-03-13 10:59:58 -05:00
  7d9e51a92a
• Add best practices guide for skill creators

  Covers grounding skills in real expertise (extracting from tasks,
  synthesizing from project artifacts), iterating with execution feedback,
  managing context budget, calibrating instruction specificity, and
  reusable instruction patterns (templates, checklists, validation loops,
  plan-validate-execute, script bundling).
  
  Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

  Jonathan Hefner · 2026-03-10 14:19:12 -05:00
  db92534bfb
• Remove redundant intro sentence from specification doc

  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>

  Jonathan Hefner · 2026-03-10 14:16:18 -05:00
  8c82ac2a8d
• Add ... entry to directory tree in specification doc

  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>

  Jonathan Hefner · 2026-03-10 14:16:17 -05:00
  fe28cce09e
• Move frontmatter field table above examples in specification doc

  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>

  Jonathan Hefner · 2026-03-10 14:16:17 -05:00
  5d16d72435
• Add SKILL.md filename annotations to code blocks in specification doc

  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>

  Jonathan Hefner · 2026-03-10 14:16:17 -05:00
  7a05447ecb
• Wrap examples in <Card> components in specification doc

  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>

  Jonathan Hefner · 2026-03-10 14:16:16 -05:00
  a9d33af2d5
• Expand directory tree in specification doc

  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>

  Jonathan Hefner · 2026-03-10 14:16:16 -05:00
  cbc354c2ff
• Improve clarity of name field constraints in specification doc

  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>

  Jonathan Hefner · 2026-03-10 14:16:15 -05:00
  08d1d688c1
• Format directory and file names as inline code in specification doc

  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>

  Jonathan Hefner · 2026-03-10 14:16:15 -05:00
  3736fdb995
• Fix example description to include "when to use" guidance

  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.

  Koichi ITO · 2026-03-10 10:41:26 +09:00
  22d6aeb353
• Merge pull request #206 from jonathanhefner/add-optimizing-descriptions-guide

  Add "Optimizing descriptions" guide for skill creators

  Jonathan Hefner · 2026-03-09 11:43:58 -05:00
  f2451a722f
• Add instructionsUrl / sourceCodeUrl fields to LogoCarousel entries

  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>

  Jonathan Hefner · 2026-03-05 14:42:40 -06:00
  caac642012
• Add "Optimizing descriptions" guide for skill creators

  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>

  Jonathan Hefner · 2026-03-05 11:28:23 -06:00
  e9dff6b3d2
• Merge pull request #203 from jonathanhefner/add-evaluating-skills-guide

  Add "Evaluating skills" guide for skill creators

  Jonathan Hefner · 2026-03-05 11:24:53 -06:00
  09055204dd
• Add comprehensive "Integrating skills" guide for client implementors (#200)

  * 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>

  Jonathan Hefner · 2026-03-05 11:24:08 -06:00
  07278fe14a
• Add "Evaluating skills" guide for skill creators

  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>

  Jonathan Hefner · 2026-03-04 09:37:49 -06:00
  863f7c2857
• Add Snowflake logo to Agent Skills logo carousel (#199)

  .... Generated with [Cortex Code](https://docs.snowflake.com/en/user-guide/cortex-code/cortex-code)
  
  Co-authored-by: Cortex Code <noreply@snowflake.com>

  Umesh Unnikrishnan · 2026-03-02 05:02:58 -08:00
  f019a02dbb
• Add package.json to docs for local mint dev dependency (#141)

  * 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>

  lilac · 2026-02-27 17:47:34 -06:00
  fbb6c829fd
• Add "Using scripts" guide for skill creators (#196)

  * 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 · 2026-02-27 15:52:36 -06:00
  6102affec8
• Add Laravel Boost logo to Agent Skills logo carousel (#167)

  Co-authored-by: Jonathan Hefner <jonathan@hefner.pro>

  Pushpak Chhajed · 2026-02-22 13:41:31 -06:00
  201eb2faf3
• Add Emdash logo to LogoCarousel (#132)
  Arne Strickmann · 2026-02-22 13:39:43 -06:00
  0e96f39bf8
• Add openhands logo (#118)

  * 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>

  Jamie Chicago · 2026-02-22 13:38:13 -06:00
  f682292a31
• Add Junie logo to the logos carousel (#116)
  Irina Chichikova · 2026-02-22 13:36:47 -06:00
  b8241441e0
• Fix logo carousel snap at animation loop boundary (#165)

  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>

  Jonathan Hefner · 2026-02-15 16:21:18 -06:00
  b7442eb9ac
• Remove MCP-specific CSS from style.css (#113)

  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>

  Jonathan Hefner · 2026-02-15 13:43:31 -06:00
  fe4fecbb43
• Add Qodo logo to Agent Skills (#123)
  Nnenna Ndukwe · 2026-02-06 07:52:42 -08:00
  e81550daf1
• Fix VT Code logo sizing, centering, and file references in carousel
  Eric Harmeling · 2026-01-27 13:46:41 -05:00
  c9e5df0a28
• Add VT Code logo to LogoCarousel (#104)
  Vinh Nguyen · 2026-01-27 13:46:31 -05:00
  3c6ce2f163
• Add Ona logo to adoption carousel

  Co-Authored-By: Claude <noreply@anthropic.com>

  Eric Harmeling · 2026-01-23 10:40:04 -05:00
  2d0014513b
• Adjust logo widths in adoption carousel for consistent sizing

  Co-Authored-By: Claude <noreply@anthropic.com>

  Eric Harmeling · 2026-01-23 10:36:42 -05:00
  19d5c9fead
• adding Autohand Code on the agentskills.md (#101)
  Igor Costa · 2026-01-23 10:29:40 -05:00
  f8dfba0740
• Adds Roo Code Logo (#99)

  Co-authored-by: Eric Harmeling <eric.harmeling@outlook.com>

  Bruno Bergher · 2026-01-23 10:28:13 -05:00
  4966c3fcbd
• Include Mistral Vibe (#44)

  * 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>

  pandora · 2026-01-23 10:27:41 -05:00
  a88b0c8f56
• Add pi to adoption section (#70)

  Co-authored-by: Michael Renner <terrorobe@github.com>
  Co-authored-by: Eric Harmeling <eric.harmeling@outlook.com>

  Duncan Ogilvie · 2026-01-22 15:34:04 -05:00
  ed20f3a0bf