{"owner":"ChilliCream","repo":"graphql-platform","hasSkills":true,"totalSkillsCount":15,"totalTokensCount":26598,"categories":["root-instruction","anthropic-skill","mcp-config","plugin-manifest","command-prompt"],"hasMcp":true,"mcpConfig":{"mcpServers":{"graphql-platform":{"command":"npx","args":["-y","@modelcontextprotocol/server-graphql-platform"]}}},"found":["website/AGENTS.md","website/content/docs/skills/getting-started.md","AGENTS.md","website/content/docs/skills/authoring-skills.md",".vscode/mcp.json","website/content/docs/skills/index.md","website/content/docs/skills/installing-skills.md","website/content/docs/skills/troubleshooting.md","website/content/docs/skills/reference.md","website/content/docs/skills/structure.yaml","src/HotChocolate/CostAnalysis/tools/oracle/LICENSE-graphql-static-analysis-rs.md","src/HotChocolate/CostAnalysis/tools/oracle/README.md","src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/ReplyMailCommandTests.Reply_Should_ThreadUnderOriginalMessage_AndInheritRootSubject_When_JsonOutputIsRequested.md","src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/SendMailCommandTests.Send_Should_ReturnSendResult_When_JsonOutputIsRequested.md","src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Tasks/__snapshots__/TaskStoreTests.ReleaseAssigneeAsync_Should_ReleaseInProgressTasksAndAppearInReady.md"],"skills":{"website/AGENTS.md":"<!-- BEGIN:nextjs-agent-rules -->\n\n# This is NOT the Next.js you know\n\nThis version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.\n\n<!-- END:nextjs-agent-rules -->\n\n# Authoring markdown content\n\nWhen creating or editing content under `content/docs/` or `content/blog/`, follow\nthe conventions in [README.md → Authoring Markdown Content](./README.md#authoring-markdown-content).\nIt covers frontmatter, `structure.yaml` sidebars, links, images, YouTube videos,\nadmonitions, Mermaid diagrams, and MDX gotchas.\n\nWhen creating or editing a video under `content/videos/`, also follow\n[README.md → Videos](./README.md#videos) for the file name and frontmatter.\n\n# Components\n\nThis site is built to be extended agent-first: adding a page or component should\nbe mechanical and consistent. Keep the quality bar high; do not cut corners\nbecause an agent is doing the work.\n\n## Where code lives\n\n- **Pages**: `app/` route segments. Content/marketing routes live under\n  `app/(content)/`. Keep page files thin: compose section components, do not\n  inline large markup.\n- **Reusable components**: `src/components/`, one component per file\n  (PascalCase filename).\n- **Design-system primitives** (Button, Input, Image, Typography, ...):\n  `src/design-system/`.\n- **Icons and inline SVG art**: `src/icons/`, one per file.\n- A component that is only a child of one parent and is not reused elsewhere may\n  live in the parent's file. As soon as it is reused or is independently\n  meaningful, move it to its own file under `src/components/`.\n\n## Props\n\n- Declare props as an `interface` named `<Component>Props`.\n- Every property is `readonly`.\n- Do **not** export the props interface; it is the component's own\n  implementation detail.\n\n```tsx\ninterface ButtonProps {\n  readonly label: string;\n  readonly onClick?: () => void;\n}\n\nexport function Button({ label, onClick }: ButtonProps) {\n  // ...\n}\n```\n\n## SVG and icons\n\n- Add SVGs as inline React components in `src/icons/` that return `<svg>…</svg>`\n  directly, so the markup is inlined into the HTML.\n- Do **not** add raw `.svg` files to `public/` to load via `<img>` / `Image`:\n  the image pipeline does not process SVG, and inlining lets icons inherit\n  `currentColor` and be sized/positioned with CSS.\n- Accept `className` (and `style` when the caller positions the icon). Default\n  decorative icons to `aria-hidden=\"true\"`.\n- If the SVG uses element ids (e.g. gradient ids), prefix them per icon so\n  several inlined icons on the same page do not collide.\n\n## Typography\n\nUse the type scale from `app/globals.css` (`@theme`): the `text-hero` /\n`text-h1`…`text-h6` / `text-lead` / `text-body` / `text-caption` utilities (each\nships its line-height), the `font-heading` / `font-body` families (Tailwind\n`font-sans` maps to the body voice), and the `.hero` / `.lead` / `.caption`\nhelper classes. Avoid ad-hoc `text-4xl`-style sizes for display headings.\n\n## Before you finish\n\n- Verify visually against the running dev server (`npm run dev`).\n- `npx eslint <changed files>` must pass.\n- `npm run format` must be run and `npm run format:check` must pass (Prettier\n  formatting, including Tailwind class sorting, is enforced in CI).\n","website/content/docs/skills/getting-started.md":"---\ntitle: \"Getting Started\"\ndescription: \"Run the `skills` CLI with `dnx` and add your first Agent Skill to Claude Code or another AI coding agent in five minutes using `dnx skills add`.\"\n---\n\nBy the end of this guide you will have run `skills` and added your first skill to your agent.\n\n`skills` is a .NET CLI that installs, updates, and authors [Agent Skills](https://agentskills.io/home), the portable `SKILL.md` files that extend AI coding agents like Claude Code, Cursor, and GitHub Copilot. You point it at a source (a GitHub repo, a git URL, or a local folder), and it places the skill where your agent looks for it. Your agent then loads the skill on demand when a task matches it.\n\nThis page takes you from zero to one working skill. It takes about five minutes.\n\n# Prerequisites\n\nBefore you start, make sure you have the following:\n\n| Requirement                                                   | Why you need it                                                                                                                                                             |\n| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [.NET 10 SDK or newer](https://dotnet.microsoft.com/download) | To run `skills` with `dnx`, the way these docs show it. The `dnx` command ships with the .NET 10 SDK.                                                                       |\n| An AI coding agent                                            | The target for your skill. This guide uses [Claude Code](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview). The `skills` CLI supports 55+ agents. |\n\nThese docs run `skills` with `dnx`, so there is nothing to install first. If you would rather have `skills` on your `PATH`, install the global tool instead (it needs only the .NET SDK 8.0 or newer). See [Install as a global tool](#install-as-a-global-tool).\n\n# Run `skills`\n\nThese docs run `skills` with `dnx`, which needs no install. You can also install it as a global tool if you prefer `skills` on your `PATH`.\n\n## Run with dnx\n\n`dnx` ships with the .NET 10 SDK and runs a tool straight from NuGet, the way `npx` runs a package from npm. Nothing is installed up front.\n\n```shell\ndnx skills add anthropics/skills --agent claude-code\n```\n\nOn the first run, `dnx` prompts you to confirm the package download before it proceeds:\n\n```text\nTool package skills@<version> will be downloaded from source https://api.nuget.org/v3/index.json.\nProceed? [y/n] (y):\n```\n\nAfter you confirm, the install proceeds and prints the summary shown in [Add your first skill](#add-your-first-skill). The first run downloads the package into your NuGet cache; later runs reuse it and start immediately. `dnx skills` is shorthand for `dotnet tool exec skills`.\n\nTo skip the download prompt (for example in CI), pass `--yes`:\n\n```shell\ndnx --yes skills add anthropics/skills --agent claude-code\n```\n\nYou can control the `skills` version that `dnx` runs and where it fetches it from:\n\n| Command                                      | What it does                        |\n| -------------------------------------------- | ----------------------------------- |\n| `#!shell dnx skills@0.3.0 add ...`           | Runs an exact version.              |\n| `#!shell dnx skills@0.3.* add ...`           | Runs the latest 0.3.x version.      |\n| `#!shell dnx --prerelease skills add ...`    | Allows prerelease versions.         |\n| `#!shell dnx --source <feed> skills add ...` | Fetches from a specific NuGet feed. |\n\nIf your repository has a `.config/dotnet-tools.json` manifest that lists `skills`, `dnx` honors the pinned version from the manifest, which keeps one-shot runs consistent with the version your team committed.\n\n## Install as a global tool\n\nIf you would rather have `skills` on your `PATH`, install it as a global [.NET tool](https://learn.microsoft.com/dotnet/core/tools/global-tools). This needs the .NET SDK 8.0 or newer.\n\n```shell\ndotnet tool install -g skills\n```\n\n```text\nYou can invoke the tool using the following command: skills\nTool 'skills' (version '0.3.0') was successfully installed.\n```\n\nWith the global tool you run `skills` directly: drop the `dnx` prefix from every example in these docs (`dnx skills add ...` becomes `skills add ...`). Confirm the install with `skills --version`, which prints a value like `0.3.0+<git-sha>` (the trailing suffix records the exact commit the build came from).\n\nTo pin `skills` to a version your whole team shares, install it as a local tool through a manifest instead. From the repository root:\n\n```shell\ndotnet new tool-manifest\ndotnet tool install skills\n```\n\nLocal tools are restored with `dotnet tool restore` and run through `dotnet skills`. Check the manifest (`./.config/dotnet-tools.json`) into source control so every collaborator uses the same version.\n\n# Add your first skill\n\nYou are ready to install a skill. The example below installs skills from [anthropics/skills](https://github.com/anthropics/skills), Anthropic's reference repository, targeting Claude Code.\n\n```shell\ndnx skills add anthropics/skills --agent claude-code\n```\n\nAgent names are case-sensitive. Use `claude-code`, not `claude` or `Claude`. For GitHub Copilot the name is `github-copilot`.\n\nThe `skills` CLI fetches the source, discovers the skills, installs them, and prints a summary:\n\n```text\nSource: https://github.com/anthropics/skills.git\nFound 2 skill(s)\n\n┌─Installation Summary─────────────────────────────────────────────────────────┐\n│ Canonical: /your-project/.agents/skills                                      │\n│ Symlinked:  Claude Code                                                      │\n└──────────────────────────────────────────────────────────────────────────────┘\n┌─Installed 2 skill(s)─────────────────────────────────────────────────────────┐\n│ ✓ pdf                                                                        │\n│   → /your-project/.claude/skills/pdf                                         │\n│ ✓ docx                                                                       │\n│   → /your-project/.claude/skills/docx                                        │\n└──────────────────────────────────────────────────────────────────────────────┘\n\nDone!  Review skills before use; they run with full agent permissions.\n```\n\n> The trailing line is a deliberate safety nudge. A skill can include scripts that the agent runs with your agent's full permissions. Install skills only from sources you trust, and read a new skill before you use it.\n\nIf you omit `--agent`, the CLI runs interactively and lets you pick which agents to target from the ones it detects on your machine. To install only specific skills from a multi-skill source, add `--skill <name>` (repeatable). For the full set of source forms, scopes, and flags, see [Installing Skills](./installing-skills.md).\n\n**Checkpoint.** If everything worked, you should see the `Installed 2 skill(s)` panel and the `Done!` line, with no error. If you saw an `Invalid agents` panel, you misspelled the agent name (it is case-sensitive). If you saw `No valid skills found`, the source had no `SKILL.md` with both a `name` and a `description`. See [Troubleshooting](./troubleshooting.md) for more.\n\n# See what is installed\n\nTo confirm what landed in your project, list the installed skills:\n\n```shell\ndnx skills list\n```\n\n```text\nProject Skills\n\nSkill  Path                   Agents\npdf    ./.claude/skills/pdf   Claude Code\ndocx   ./.claude/skills/docx  Claude Code\n```\n\nThe table shows each skill's name, where it lives on disk, and the agents linked to it (shown by their display name, `Claude Code`). To list global skills instead, add `-g`. For machine-readable output, add `--json`.\n\n# Use the skill\n\nThe skill now lives where your agent looks for it. You do not need to do anything else.\n\nYour agent loads each installed skill's `name` and `description` at startup, then reads the full skill only when a task matches the description. This is [progressive disclosure](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview): the description is the trigger, and the body loads on demand. Start a task that matches the skill, and your agent picks it up automatically.\n\n# Update or remove the global tool\n\nIf you run `skills` with `dnx`, you never update it yourself: each run fetches the version you ask for. The commands below apply when you installed the global tool.\n\nTo update the global `skills` tool to the latest version:\n\n```shell\ndotnet tool update -g skills\n```\n\n```text\nTool 'skills' was successfully updated from version '0.3.0' to version '<new>'.\n```\n\nTo uninstall it:\n\n```shell\ndotnet tool uninstall -g skills\n```\n\n```text\nTool 'skills' (version '0.3.0') was successfully uninstalled.\n```\n\nNote that `dotnet tool update` updates the `skills` CLI, not your installed skills. To check your skills for updates, use the `dnx skills update` command, covered in [Installing Skills](./installing-skills.md).\n\n# Next steps\n\n- [Installing Skills](./installing-skills.md): every source form, project versus global scope, picking agents and skills, symlink versus copy, and checking for skill updates.\n- [Authoring Skills](./authoring-skills.md): scaffold a `SKILL.md` with `dnx skills init`, write a good description, and publish your skill.\n- [Reference](./reference.md): the complete command and flag surface.\n","AGENTS.md":"# AGENTS.md\n\nThis file provides guidance to coding agents when working with this repository.\n\n## Attribution\n\n- Do not add `Co-authored-by` trailers or other co-author attribution for agents.\n\n## Pull Requests\n\n- Start a bug fix PR title with `Fix`: `Fix the gateway ignoring subgraph timeouts`. The title becomes the squash commit subject and the release note entry.\n- Area prefixes are optional. Write them in title case (`[Fusion]`, not `[fusion]`), and put `Fix` after one: `[Fusion] Fix the gateway ignoring subgraph timeouts`.\n\n## Build\n\n### Website\n\nUse `npm`.\n\n```bash\ncd website\nnpm ci\n```\n\nnpm 11 before 11.21.1 and npm 12 before 12.2.1 write `allowScripts` entries from `npm install-scripts approve` that npm cannot match under the linked install strategy ([npm/cli#9939](https://github.com/npm/cli/issues/9939)), so on those versions add approvals by hand as `\"<package>@<version>\": true`.\n\n### C# Source Code\n\nBuilds report IDE code-style violations (`IDE*`) as build errors, the same as CI does. Fix every reported style error.\n\nBuild the full solution:\n\n```bash\ndotnet build src/All.slnx\n```\n\nEach area has its own solution file, so you can build or test a subset directly:\n\n```bash\ndotnet test src/HotChocolate/Fusion\n```\n\n## Updating .NET\n\nWhen a change edits `TargetFrameworks` in `src/Directory.Build.props` or the SDK version in `global.json`, work through [docs/updating-dotnet.md](docs/updating-dotnet.md) before handoff.\n\n## Code Quality\n\n### C# / .NET\n\n- Always use curly braces for loops and conditionals, no exceptions.\n- Use file-scoped namespaces and 4-space indentation.\n- Test naming: `Method_Should_Outcome_When_Condition`.\n- No vacuous assertions (`Assert.NotNull` alone is not a test).\n- If a test requires excessive stubs and reflection, you're at the wrong test tier.\n- Do not use em dash style sentences in docs, comments, or XML documentation. Use commas, periods, parentheses, or colons instead.\n- XML docs should describe the contract and concepts, not internals like pooling or iteration mechanics, and should not leak other implementation details.\n- XML docs and comments are 1-2 sentences stating the contract: what it is, what null or edge values mean. No rationale, no use-case examples, no design justification. If a sentence explains why the design is right instead of what the member promises, delete it. The same applies to docs pages: every sentence must inform the reader, none may justify the design.\n- Do not make new parameters optional just to avoid updating call sites. A parameter should only be optional when it has a sensible semantic default and the API is frequently used (where call-site brevity outweighs explicitness). If a parameter is logically required, make it required and update all call sites.\n\n### Testing\n\n- Prefer snapshot tests over manual `Assert` calls, use **CookieCrumble** for snapshots.\n- CookieCrumble has native snapshot support for `IExecutionResult`, `GraphQLHttpResponse`, and other core types.\n- For smaller snapshots, prefer **inline snapshots** (`MatchInlineSnapshot`) over snapshot files.\n- For a collection of results (for example a stream of subscription events), snapshot the list with `MatchInlineSnapshots` (a parallel list of per-element inline snapshots). Do NOT concatenate with `string.Join(\"---\", values).MatchInlineSnapshot(...)`: a manual separator hides element boundaries and reinvents what the collection overload does natively.\n- For tests with multiple assertions, use **Markdown snapshots** (`MatchMarkdownSnapshot`).\n- Hard limit: a single test method must contain at most 5 `Assert.*` calls. Anything beyond that is too hard to reason about in review, switch to a snapshot (Markdown for multi-shape state, inline or file for a single output).\n- Use the AAA section marker style. Each section starts with a single-line comment, the test name documents intent, no paragraph-style block comments above sections:\n\n  ```csharp\n  // arrange\n  // optional one-line description, only when the next code is non-obvious\n  ... arrange code ...\n\n  // act\n  ... act code ...\n\n  // assert\n  ... assert code ...\n  ```\n\n- Avoid `Assert.DoesNotContain` as it is a weak assertion that easily goes out of date, it only proves something is absent without verifying what *is* present. Prefer `Assert.Equal` to check the entire string value, or `Assert.Collection` to verify the complete contents of a collection.\n- Snapshot tests: update from `__mismatch__/` directory, understand ordering issues before updating.\n- Filter tests during iteration, never run the full suite unnecessarily.\n- Use real databases in integration tests, not mocks (unless explicitly instructed otherwise).\n\n## Performance\n\n### C# / .NET\n\nThis is framework code, performance matters. Aim for zero allocations on hot paths.\n\n- Use `ChunkedArrayWriter` or `PooledArrayWriter` when you need an `IBufferWriter<byte>` for in-memory byte writing.\n\n## Tools\n\n### C# / .NET\n\nIf you need to search for packages on nuget.org, use the `dotnet` CLI, e.g. `dotnet package search HotChocolate`.\n\n### Profiling\n\nThe dev container has `dotnet-trace`, `dotnet-counters`, `dotnet-gcdump`, `dotnet-dump`, `dotnet-symbol`, `dottrace` and `dotmemory` installed. Versions are pinned in `.devcontainer/dockerfile`, and `docs/profiling.md` has the full commands and caveats. The tools attach to a running process in the same container. Write outputs to `perf/<label>-<git-short-sha>/`, which is gitignored.\n\n```bash\nOUT=perf/<label>-$(git rev-parse --short HEAD); mkdir -p \"$OUT\"\ndotnet-trace ps\ndotnet-trace collect -p <pid> --duration 00:00:00:30 --format speedscope -o \"$OUT/cpu.nettrace\"\ndotnet-trace report \"$OUT/cpu.nettrace\" topN -n 25 --inclusive\ndotnet-trace collect -p <pid> --profile gc-verbose --duration 00:00:00:15 -o \"$OUT/alloc.nettrace\"\ndotnet-gcdump collect -p <pid> -o \"$OUT/heap.gcdump\" && dotnet-gcdump report \"$OUT/heap.gcdump\" > \"$OUT/heap-report.txt\"\ndotnet-counters collect -p <pid> --format json -o \"$OUT/counters.json\" --duration 00:00:00:20 --counters System.Runtime,Microsoft.AspNetCore.Hosting,System.Net.Http\n```\n\n- Profile Release builds. Debug builds distort time and allocations.\n- Sampling gives time, not call counts. Call counts need dotTrace Tracing mode, which only `dottrace start` offers; `dottrace attach` is limited to Sampling and Timeline.\n- On Linux, EventPipe samples measure thread time. Ignore idle thread pool frames such as `LowLevelLifoSemaphore.WaitForSignal` and `WaitHandle.WaitOneNoCheck`.\n- `.dtp` (dotTrace) and `.dmw` (dotMemory) snapshots are for Rider on the host. Use the `dotnet-trace` and `dotnet-gcdump` outputs for analysis inside the container.\n\n### Nitro persisted operations (Fusion Aspire)\n\nAfter adding or editing any `.graphql` document under `src/HotChocolate/Fusion/src/Fusion.Aspire/Nitro/Operations`, regenerate the `.sha256` sidecars and verify them:\n\n```bash\n.github/scripts/nitro-aspire-operations.sh update \\\n    --source src/HotChocolate/Fusion/src/Fusion.Aspire/Nitro/Operations\n.github/scripts/nitro-aspire-operations.sh verify \\\n    --source src/HotChocolate/Fusion/src/Fusion.Aspire/Nitro/Operations \\\n    --output /tmp/nitro-aspire-operations.json\n```\n\nNever hand-write or hand-edit a `.sha256` sidecar. The `update` command is the only source of sidecar content, and `verify` must pass before handoff.\n\n## Components\n\n### All components\n\n#### Exceptions\n\nCreate exceptions through the `ThrowHelper` class of the project you are editing instead of inlining `throw new ...`. Each project keeps its own, which centralizes exception messages.\nExample: `src/HotChocolate/Fusion/src/Fusion.Execution/Execution/ThrowHelper.cs`\n\n#### GraphQL errors\n\nCreate GraphQL errors through the `ErrorHelper` class of the project you are editing instead of inlining `ErrorBuilder` calls. Each project keeps its own, which centralizes error messages.\nExample: `src/HotChocolate/AspNetCore/src/AspNetCore.Pipeline/Utilities/ErrorHelper.cs`\n\n### src/Fusion\n\n#### Execution nodes\n\nWhen you add a value to `ExecutionNodeType`, map it in two places:\n\n- `ExecutePlanNodeSpan.KindValues` in `src/HotChocolate/Fusion/src/Fusion.Diagnostics/Spans/ExecutePlanNodeSpan.cs`\n- `GraphQL.Operation.Step.KindValues` in `src/HotChocolate/Diagnostics/src/Diagnostics.Core/SemanticConventions.cs`, if the kind needs a new constant. Tag values are snake_case.\n\n`KindValues` supplies the `graphql.operation.step.kind` tag on the step span. An unmapped type does not fail execution. `ExecutePlanNodeSpan.Start` falls back to an untagged span, so the node silently loses its kind in traces. The guard test `StepSpan_Should_MapEveryExecutionNodeTypeToAKindValue` in `src/HotChocolate/Fusion/test/Fusion.Diagnostics.Tests/FusionActivityExecutionDiagnosticListenerTests.cs` fails until the mapping exists.\n\n#### Operation planner version\n\n`OperationPlanner.Version` identifies planning behavior and is independent of the package version. Bump the minor version when an existing operation can plan differently, the major version when consumers must react to a new plan structure. Refactors, performance work and fixes that cannot change a plan do not bump it.\n\n#### Operation plan JSON format\n\n`JsonOperationPlanFormatter` in `src/HotChocolate/Fusion/src/Fusion.Execution/Execution/Nodes/Serialization/JsonOperationPlanFormatter.cs` writes the plan document that tooling consumes. Its shape is published as a JSON schema, so any change to the emitted JSON is a two part change:\n\n1. Bump `JsonOperationPlanFormatter.FormatVersion`. It is written as the root `version` property and is the discriminator consumers pin against. Additive optional properties bump the minor version, anything that changes or removes an existing property bumps the major version.\n2. Add the matching variant to `website/public/schemas/fusion/operation-plan.json`, published at `https://chillicream.com/schemas/fusion/operation-plan.json`. Add a `#/$defs/<version>_plan` entry and the `allOf` branch that selects it for that root `version`, and list the new version in the root `version` enum. Every other definition is unprefixed and shared across versions. When a version changes one of them, fork only that definition to `<version>_<name>` and point the new plan at the fork, so a released version keeps validating exactly what it validated before.\n\nThe root `version` enum and the `allOf` branch that selects `v1_0_0_plan` are the pattern to copy: a new version adds one enum entry, one branch and one plan definition.\n\nThe internal `Format(IBufferWriter<byte>, Operation, ImmutableArray<ExecutionNode>)` overload feeds the SHA-256 that becomes `OperationPlan.Id`. It deliberately omits the `version` property, so leave it alone unless you intend to change every plan id.\n","website/content/docs/skills/authoring-skills.md":"---\ntitle: \"Authoring Skills\"\ndescription: \"Author Agent Skills with the `skills` CLI: scaffold a folder with `dnx skills init`, write the SKILL.md frontmatter and instructions, and publish through git.\"\n---\n\nPackage your team's conventions once, and any agent can pick them up. A skill is a folder with a `SKILL.md` file that tells an agent how to do something the way your team does it: your release checklist, your code review rules, your API client patterns. You write it once, push it to a git repo, and your teammates install it with one command. From then on, every agent they run loads that knowledge on demand, no copy-pasting prompts into each session.\n\nThis page teaches you to scaffold a skill, write a correct `SKILL.md`, add supporting files, and publish it so others can install it with [`dnx skills add`](./installing-skills.md). The skill format is the open [Agent Skills](https://agentskills.io/home) standard, so what you write here works across [55+ agents](./index.md), not only the one you author it in.\n\n# Scaffold a skill\n\n> Prerequisite: the .NET 10 SDK. See [Getting Started](./getting-started.md) before running the commands below.\n\nTo create a new skill in its own folder, run `dnx skills init` with a name.\n\n```shell\ndnx skills init my-skill\n```\n\n```text\nInitialized skill: my-skill\n\nCreated:\n  my-skill/SKILL.md\n\nNext steps:\n  1. Edit my-skill/SKILL.md to define your skill instructions\n  2. Update the name and description in the frontmatter\n\nPublishing:\n  GitHub: Push to a repo, then skills add <owner>/<repo>\n  URL:    Host the file, then skills add https://example.com/my-skill/SKILL.md\n```\n\nThis creates `my-skill/SKILL.md`. If everything worked, you have a folder named `my-skill` with one file inside it.\n\nTo scaffold a skill in the current directory instead, run `dnx skills init` with no name. The CLI derives the skill name from the folder you are in and writes `SKILL.md` next to your other files.\n\n```shell\ndnx skills init\n```\n\n```text\nInitialized skill: my-skill\n\nCreated:\n  SKILL.md\n\nNext steps:\n  1. Edit SKILL.md to define your skill instructions\n  2. Update the name and description in the frontmatter\n\nPublishing:\n  GitHub: Push to a repo, then skills add <owner>/<repo>\n  URL:    Host the file, then skills add https://example.com/my-skill/SKILL.md\n```\n\n`dnx skills init` never overwrites an existing skill. If `SKILL.md` is already present, it leaves your file untouched and tells you so.\n\n```text\nSkill already exists at my-skill/SKILL.md\n```\n\n## The generated template\n\n`dnx skills init` writes a spec-compliant starting point: the two required frontmatter fields, then a body with a heading and the sections most skills need.\n\n```markdown\n---\nname: my-skill\ndescription: A brief description of what this skill does\n---\n\n# my-skill\n\nInstructions for the agent to follow when this skill is activated.\n\n## When to use\n\nDescribe when this skill should be used.\n\n## Instructions\n\n1. First step\n2. Second step\n3. Additional steps as needed\n```\n\nReplace the placeholder `description`, then fill in the body. The next sections explain each part.\n\n# Structure a SKILL.md\n\nA `SKILL.md` has two parts: YAML frontmatter between `---` fences, and a Markdown body below it. The frontmatter is metadata the agent reads to decide whether your skill is relevant. The body is the instructions the agent follows once it decides to use the skill.\n\nThe \"Required frontmatter\" and \"Optional frontmatter\" subsections below are reference material: field-by-field constraint tables you can scan when you fill in the frontmatter. For the complete, authoritative field list see the [Reference](./reference.md).\n\n## Required frontmatter\n\nEvery skill needs `name` and `description`. The CLI skips any skill that is missing either field, so getting these right is the difference between a skill that installs and one that silently disappears.\n\n| Field         | Constraints                                                                                                                                                                                                                                               |\n| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `name`        | 1 to 64 characters. Lowercase letters, digits, and hyphens only. No leading or trailing hyphen. No consecutive hyphens. Should match the skill's folder name. Must not contain XML tags, and must not contain the reserved words `anthropic` or `claude`. |\n| `description` | 1 to 1024 characters. Must say BOTH what the skill does AND when to use it. Include specific trigger keywords that match the tasks where the skill applies. Must not contain XML tags.                                                                    |\n\nThe `description` is the single most important field you write. At startup the agent loads only your `name` and `description` (not the body), then matches the user's request against that description to decide whether to read the rest. A vague description means the agent never triggers your skill. Front-load what the skill does, then state the conditions that should activate it, and name the tools, file types, or commands involved.\n\n```markdown\n---\nname: release-checklist\ndescription: Runs our release checklist before publishing a NuGet package. Use when cutting a release, bumping a version, or preparing a package for nuget.org.\n---\n```\n\nThese constraints are the union of two authorities: the open spec at [agentskills.io/specification](https://agentskills.io/specification) (which adds the \"match the folder name\" and \"no consecutive hyphens\" rules) and the [Anthropic platform rules](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) (which add the reserved-word and XML-tag prohibitions). Honoring both keeps your skill portable across every agent.\n\n## Optional frontmatter\n\nAdd these fields only when you need them. The open spec at [agentskills.io/specification](https://agentskills.io/specification) is the authoritative field list; the most useful fields are below.\n\n| Field           | Purpose                                                                                                                                                                     |\n| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `license`       | A license name or a reference to a bundled license file. Keep it short.                                                                                                     |\n| `compatibility` | Up to 500 characters describing environment needs (intended product, system packages, network access). Most skills do not need it. Example: `Requires git, docker, and jq`. |\n| `metadata`      | A string-to-string map for client-defined properties the spec does not cover, such as `author` or `version`. Use distinctive key names to avoid collisions.                 |\n| `allowed-tools` | A space-separated list of pre-approved tools, for example `Bash(git:*) Read`.                                                                                               |\n\nFor the exhaustive list of frontmatter fields and their constraints, see the [Reference](./reference.md).\n\n> [!WARNING]\n> **`allowed-tools` is experimental.** Support varies between agents, and `dnx skills init` does not emit it. Treat it as a hint that some agents honor and others ignore, not a security boundary.\n\n## The instructions body\n\nThe body is plain Markdown the agent follows when your skill activates. There are no format restrictions, so write it the way you would brief a new teammate: step-by-step instructions, input and output examples, and the edge cases people get wrong.\n\nKeep `SKILL.md` focused. The recommendation from both [Anthropic](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) and the open spec is to keep the body under roughly 500 lines and move long detail into supporting files (see the next section). A tight body loads fast and keeps the agent on the steps that matter.\n\n# Add supporting files\n\nA skill folder can hold more than `SKILL.md`. Three conventional subdirectories cover most needs.\n\n```text\nmy-skill/\n├── SKILL.md          # Required: frontmatter + instructions\n├── references/       # Docs loaded on demand (REFERENCE.md, API.md, ...)\n├── scripts/          # Code the agent runs\n└── assets/           # Templates, data files, schemas\n```\n\nThe CLI copies or symlinks the whole folder as a unit, so every supporting file ships with the skill. (A few build artifacts are excluded automatically, including `.git`, `node_modules`, and `__pycache__`.)\n\nThese directories exist because of [progressive disclosure](./index.md#how-skills-load-progressive-disclosure): the agent loads your skill in stages so a large skill costs almost nothing until it is needed.\n\n- At startup the agent loads only `name` and `description`.\n- When the skill triggers, the agent reads the `SKILL.md` body.\n- A file under `references/`, `scripts/`, or `assets/` loads only when the body points the agent at it.\n\nThis is why moving detail out of `SKILL.md` and into `references/` is free: that material never enters the context window until the agent actually follows a link to it. Reference your supporting files with relative paths one level deep (for example `references/api.md`), and avoid deep nesting chains. For more on the three-stage model, see the [Introduction](./index.md#how-skills-load-progressive-disclosure) and [Anthropic's overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).\n\n# How installed skills are named\n\nWhen someone installs your skill, the CLI derives the on-disk directory name by sanitizing the `name` field. It lowercases the name, replaces every run of characters outside `a-z`, `0-9`, `.`, and `_` with a single hyphen, and trims leading and trailing dots and hyphens.\n\nFor a clean lowercase-hyphen name like `release-checklist`, the on-disk name is identical, with no surprises. A name with spaces or uppercase letters gets rewritten (`My Skill` becomes `my-skill`), which can mismatch what you and your teammates expect on disk and during removal. Pick a clean lowercase-hyphen name that already satisfies the [required frontmatter rules](#required-frontmatter), and the install name matches your folder name exactly.\n\n# Publish and install\n\nA skill is a folder in a git repo, so publishing is committing and pushing. Any repository the CLI can reach with git works.\n\nTo publish, commit your skill folder and push it to GitHub, GitLab, or any git remote. Then anyone installs it with `dnx skills add` pointed at the repo. The forms below show what an installer runs against your published skill; for the full add workflow, including expected output, scoping, and agent targeting, see [Installing Skills](./installing-skills.md).\n\n```shell\n# install every skill in the repo\ndnx skills add my-org/my-skills\n\n# install only one skill from a multi-skill repo\ndnx skills add my-org/my-skills@release-checklist\n\n# install a single SKILL.md hosted at a URL\ndnx skills add https://example.com/my-skill/SKILL.md\n```\n\nPrivate repositories work with no extra configuration. The CLI shells out to your own `git`, so it uses your existing credentials (SSH agent keys, a git credential helper, or `gh auth`). If you can `git clone` the repo, `skills` can install from it. When authentication fails, see [Troubleshooting](./troubleshooting.md).\n\nTo keep a work-in-progress skill out of default discovery, set `metadata.internal` to `true` in the frontmatter. The CLI hides internal skills unless the installer explicitly opts in (by filtering for the skill by name, or by setting the `INSTALL_INTERNAL_SKILLS` environment variable).\n\n```markdown\n---\nname: experimental-skill\ndescription: An in-progress skill. Use when testing new conventions before rollout.\nmetadata:\n  internal: \"true\"\n---\n```\n\n# Validate a skill\n\nTo check a skill against the open spec before you publish, use the reference validator `skills-ref` from the [agentskills/agentskills](https://github.com/agentskills/agentskills) repository. It validates your frontmatter and naming conventions.\n\n```shell\nskills-ref validate ./my-skill\n```\n\nIt reports a clean pass when the skill is valid, or names the offending field and rule when it is not (for example, an empty `description` or a `name` that breaks the naming rules).\n\nRunning it after `dnx skills init` and again before you push catches a malformed `name` or an empty `description` while it is still fast to fix, rather than discovering that the CLI skipped your skill on install.\n\n# Next steps\n\n- [Installing Skills](./installing-skills.md): install your published skill, target specific agents, and choose project or global scope.\n- [Reference](./reference.md): the complete command and flag surface, including `dnx skills init`.\n",".vscode/mcp.json":"{\n  \"servers\": {\n    \"microsoft.docs.mcp\": {\n      \"type\": \"http\",\n      \"url\": \"https://learn.microsoft.com/api/mcp\"\n    },\n    \"nuget\": {\n      \"type\": \"stdio\",\n      \"command\": \"dotnet\",\n      \"args\": [\n        \"dnx\",\n        \"NuGet.Mcp.Server\",\n        \"--source\",\n        \"https://api.nuget.org/v3/index.json\",\n        \"--yes\"\n      ]\n    },\n    \"lighthouse\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@danielsogl/lighthouse-mcp@latest\"]\n    },\n    \"playwright\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@playwright/mcp@latest\"]\n    },\n  }\n}\n","website/content/docs/skills/index.md":"---\ntitle: Skills\nmetaTitle: \"Skills: Agent Skills CLI for .NET\"\ndescription: \"The `skills` .NET CLI installs, updates, and authors Agent Skills: portable SKILL.md files you can share across Claude Code, Cursor, and 55+ agents.\"\n---\n\n`skills` is the .NET CLI that installs, updates, and authors [Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills): portable `SKILL.md` files that teach an AI coding agent how you work. Stop re-explaining your conventions every session. Package the knowledge once, then hand the same skill to Claude Code, Cursor, GitHub Copilot, or another of the 55+ supported agents with a single command.\n\nRun it with `dnx`, which ships with the .NET 10 SDK, so there is nothing to install first:\n\n```shell\ndnx skills add anthropics/skills --agent claude-code\n```\n\n```text\nSource: https://github.com/anthropics/skills.git\nFound 2 skill(s)\n\n┌─Installation Summary─────────────────────────────────────────────────────────┐\n│ Canonical: /your-project/.agents/skills                                      │\n│ Symlinked:  Claude Code                                                      │\n└──────────────────────────────────────────────────────────────────────────────┘\n┌─Installed 2 skill(s)─────────────────────────────────────────────────────────┐\n│ ✓ pdf                                                                        │\n│   → /your-project/.claude/skills/pdf                                         │\n│ ✓ docx                                                                       │\n│   → /your-project/.claude/skills/docx                                        │\n└──────────────────────────────────────────────────────────────────────────────┘\n\nDone!  Review skills before use; they run with full agent permissions.\n```\n\nThe CLI detects the agents you have installed, then symlinks the skill into each one from a single canonical store. The agent loads the skill on its own when a task matches.\n\nThese docs show every command as `dnx skills`. Prefer `skills` on your `PATH`? Install the global tool with `#!shell dotnet tool install -g skills`, then drop the `dnx` prefix and run `skills` directly.\n\nNeed the prerequisites or a step-by-step walkthrough? See [Get started](./getting-started.md). The [source repository](https://github.com/ChilliCream/skills) and [`skills` package on NuGet](https://www.nuget.org/packages/skills) are public.\n\n# What are Agent Skills\n\nA skill is a folder with a single `SKILL.md` file. That file has YAML frontmatter (a `name` and a `description`) followed by a Markdown body of instructions. Optional subfolders carry supporting material the agent reads only when it needs it.\n\nThink of a skill as an onboarding guide for a new team member. You write down a procedure once (how to run your test suite, how your commit messages are formatted, which API your team prefers), and the agent references the relevant section when a task calls for it. A general-purpose agent becomes a specialist in your codebase without bespoke prompt engineering on every request.\n\nSkills differ from prompts. A prompt is conversation-level guidance you paste in for one task. A skill loads on demand across every conversation, so you never repaste the same instructions again.\n\nThe `SKILL.md` format is an open standard created by Anthropic and adopted across the ecosystem. The same file works in 55+ supported agents, including Claude Code, Cursor, and GitHub Copilot. To go deeper, read Anthropic's [Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) and the [open specification](https://agentskills.io/specification) at agentskills.io.\n\n# How skills load: progressive disclosure\n\nSkills stay out of the agent's context window until they are needed. The format loads in three levels, each at a different time. This is the single most important idea to understand, because it is why you can install many skills without paying a context penalty.\n\n| Level                 | What loads                                            | When                                    | Token cost            |\n| --------------------- | ----------------------------------------------------- | --------------------------------------- | --------------------- |\n| Level 1: Metadata     | The `name` and `description` from the frontmatter     | Always, at startup                      | ~100 tokens per skill |\n| Level 2: Instructions | The `SKILL.md` Markdown body                          | When the skill is triggered             | Keep under ~5k tokens |\n| Level 3: Resources    | Bundled files in `references/`, `scripts/`, `assets/` | On demand, when the body points to them | Effectively unlimited |\n\nAt startup the agent loads only each skill's `name` and `description`. The `description` is what the agent matches against your request to decide whether to activate the skill, so write it to describe both what the skill does and when to use it. When a request matches, the agent reads the full body. Bundled resources never enter context until the body references them, which is why supporting material can be effectively unbounded.\n\nThe open standard frames the same flow as Discovery, Activation, and Execution. For the full model, see Anthropic's [overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) and the [agentskills.io home page](https://agentskills.io/home).\n\n# What a skill looks like\n\nA skill is, at minimum, a folder containing one `SKILL.md` file. Everything else is optional and loaded only when referenced:\n\n```text\nmy-skill/\n├── SKILL.md       # Required: frontmatter (name + description) + Markdown instructions\n├── references/    # Optional: extra docs the agent reads on demand\n├── scripts/       # Optional: code the agent runs via the shell\n└── assets/        # Optional: templates, schemas, images, data files\n```\n\nThe folder name should match the `name` in the frontmatter. Here is a minimal, valid `SKILL.md` with the two required fields:\n\n```markdown\n---\nname: roll-dice\ndescription: Rolls one or more dice and returns the results. Use when the user asks to roll dice, flip for a decision, or pick a random number in a range.\n---\n\n# Roll dice\n\nWhen the user asks to roll dice, parse the count and number of sides (default to one six-sided die),\nthen return each roll and the total.\n```\n\nThe `dnx skills init` command scaffolds this layout for you; [Authoring Skills](./authoring-skills.md) walks through it with the generated `SKILL.md` and folder tree. The full field reference, including optional frontmatter, lives in the [open specification](https://agentskills.io/specification) and in [Authoring Skills](./authoring-skills.md).\n\n# Why Skills\n\nThe `skills` CLI brings the install-once, run-anywhere skill workflow to the .NET SDK. Three things make it worth adding to your toolbox.\n\nProject-scoped installs are recorded in a `skills-lock.json` file in your working directory. Commit it, and your whole team shares one reproducible skill set, the same way a lock file pins your package dependencies.\n\nOne install reaches every detected agent. The CLI materializes each skill once in a canonical store, then links it into the directory each installed agent expects. You do not manage per-agent copies by hand.\n\nPersonal skills install globally with `--global`. Those live outside any single project and follow you across every repository you work in.\n\n# The ecosystem\n\nThe Agent Skills world has three distinct layers. Knowing which is which helps you find what you need.\n\n| Layer         | What it is                                | Where                                                                                                             |\n| ------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| Format / spec | The open `SKILL.md` standard              | [agentskills.io](https://agentskills.io/specification), [anthropics/skills](https://github.com/anthropics/skills) |\n| Discovery     | A directory of published skills to browse | [skills.sh](https://www.skills.sh/)                                                                               |\n| Installers    | CLIs that fetch and install skills        | `skills` (.NET), [npx skills](https://github.com/vercel-labs/skills) (Node)                                       |\n\nThe `skills` CLI brings the [npx skills](https://github.com/vercel-labs/skills) workflow to the .NET SDK via `dnx`, so you can run it without a global install. The command surface deliberately mirrors what Node developers already know. The CLI has no registry of its own: you point `dnx skills add` at any git repository or local folder, and you discover skills to install from directories like [skills.sh](https://www.skills.sh/).\n\n# Next steps\n\n- [Get started](./getting-started.md): run `skills` and add your first skill end to end.\n- [Author a skill](./authoring-skills.md): scaffold a `SKILL.md`, write a strong description, and publish it.\n","website/content/docs/skills/installing-skills.md":"---\ntitle: \"Installing Skills\"\ndescription: \"Install Agent Skills from GitHub repos, git URLs, or local folders with `dnx skills add`: the CLI finds every SKILL.md and wires it into your agents.\"\n---\n\n`dnx skills add` installs skills from a source into the AI coding agents you already have. Point it at a GitHub repository and the CLI discovers every `SKILL.md`, detects your agents, and wires the skill into each one.\n\n```shell\ndnx skills add anthropics/skills\n```\n\nThat single command fetches [Anthropic's reference skills](https://github.com/anthropics/skills), then either prompts you to choose which skills and agents you want or, when it is running inside an agent, installs non-interactively. This page walks the full lifecycle: choosing a source, narrowing to specific skills and agents, picking a scope, keeping skills current, and removing them.\n\nIf you have not installed the CLI yet, start with [Getting Started](./getting-started.md).\n\n> [!WARNING]\n> **Skills run with your agent's full permissions.** A skill is executable instructions plus optional scripts that your agent runs on your machine. Install only from sources you trust, and review a skill before you use it. After every successful install, `skills` reminds you: `Review skills before use; they run with full agent permissions.`\n\n# Choose a source\n\nThe `source` argument tells the CLI where to fetch skills from. It infers the kind of source from the string, so you pass one positional value and nothing else.\n\nThe most common form is a GitHub `owner/repo` shorthand:\n\n```shell\ndnx skills add anthropics/skills\n```\n\nEvery source form below is accepted. The first matching rule wins, and clones are always shallow (the CLI fetches only the latest commit, not the full history).\n\n| Source form            | Example                                                                      | What it does                                                              |\n| ---------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------- |\n| GitHub `owner/repo`    | `#!shell dnx skills add anthropics/skills`                                   | Installs from the repository root. The default shorthand.                 |\n| GitHub subpath         | `#!shell dnx skills add anthropics/skills/document-skills/pdf`               | Installs only the skill at that path in the repo.                         |\n| GitHub branch or tag   | `#!shell dnx skills add owner/repo#main`                                     | Installs from a specific ref (`#branch` or `#tag`).                       |\n| GitHub skill filter    | `#!shell dnx skills add owner/repo@my-skill`                                 | Installs only the skill named `my-skill` from the repo.                   |\n| GitHub URL             | `#!shell dnx skills add https://github.com/owner/repo`                       | Full URL, with or without a trailing `.git`.                              |\n| GitHub `tree` URL      | `#!shell dnx skills add https://github.com/owner/repo/tree/main/skills/foo`  | A `/tree/<ref>/<path>` URL pins the ref and subpath.                      |\n| GitLab shorthand       | `#!shell dnx skills add gitlab:group/project`                                | Installs from GitLab. Subgroups are supported (`group/subgroup/project`). |\n| GitLab URL             | `#!shell dnx skills add https://gitlab.com/group/project/-/tree/main/skills` | GitLab uses `/-/tree/` (note the `-` segment).                            |\n| Generic git or SSH     | `#!shell dnx skills add git@github.com:owner/repo.git`                       | Any `https`, `ssh://`, `git://`, or scp-style git transport.              |\n| Local directory        | `#!shell dnx skills add ./my-skills`                                         | A local path: `./`, `../`, an absolute path, or a Windows drive path.     |\n| Well-known HTTP(S) URL | `#!shell dnx skills add https://example.com/skills`                          | A non-git site that serves skills via `.well-known` discovery.            |\n\nA few notes that save time:\n\n- A bare name like `my-skills` (no `./` prefix) is treated as `owner/repo` shorthand, not a local path. Use `./my-skills` when you mean a local directory.\n- You can combine a ref and a skill filter: `owner/repo#main@my-skill`.\n- Any credentials embedded in a URL are stripped before they appear in output or in the lock file. The `Source:` line that the CLI prints shows `https://<redacted>@host/...`.\n\n> A well-known HTTP source fetches a `.well-known/agent-skills/index.json` (or `.well-known/skills/index.json`) discovery document from the site and downloads the listed skills. Every fetch is pinned to the same origin as the index, and indexes verify a SHA-256 digest per skill.\n\n# Choose which skills to install\n\nA source can contain many skills. By default, when you do not pass any filter, the CLI lists what it found and lets you select interactively. To narrow the set up front, use the options below.\n\nTo preview the available skills without installing anything, pass `--list` (or `-l`):\n\n```shell\ndnx skills add anthropics/skills --list\n```\n\n```text\nSource: https://github.com/anthropics/skills.git\nFound 2 skill(s)\n\nAvailable Skills\n  pdf\n    the pdf skill\n  docx\n    the docx skill\n\nUse --skill <name> to install specific skills\n```\n\nTo install one or more specific skills by name, pass `--skill` (or `-s`). The option is repeatable:\n\n```shell\ndnx skills add anthropics/skills --skill pdf --skill docx\n```\n\nYou can also embed a single skill filter in the source string with `@name`:\n\n```shell\ndnx skills add anthropics/skills@pdf\n```\n\nTo install every skill from the source into every detected agent, non-interactively, pass `--all`:\n\n```shell\ndnx skills add anthropics/skills --all\n```\n\nA successful run prints the `Installation Summary` and `Installed N skill(s)` panels followed by the safety reminder, the same shape shown under [How skills reach each agent](#how-skills-reach-each-agent).\n\n`--all` is a shortcut: it selects all skills, targets all agents, and skips every prompt.\n\nIf a `--skill` filter matches nothing, the CLI lists what was available so you can correct the name, and exits with a non-zero code:\n\n```text\nSource: /home/you/my-skills\nFound 2 skill(s)\nNo matching skills found for: nope\nAvailable skills:\n  alpha\n  beta\n```\n\nA skill is any folder that contains a `SKILL.md` with both a `name` and a `description`. If the source contains no valid skills, the CLI reports `No valid skills found. Skills require a SKILL.md with name and description.` and exits non-zero. See [Authoring Skills](./authoring-skills.md) for the format.\n\n# Choose which agents\n\nBy default, the CLI detects which agents are installed on your machine and targets them. To choose explicitly, pass `--agent` (or `-a`). The option is repeatable and accepts multiple values per token, and `*` means every supported agent:\n\n```shell\n# repeated flags\ndnx skills add anthropics/skills --agent claude-code --agent cursor\n\n# space-separated values in one token\ndnx skills add anthropics/skills --agent claude-code cursor\n\n# every supported agent\ndnx skills add anthropics/skills --agent \"*\"\n```\n\nA valid `--agent` run prints the `Installation Summary` and `Installed N skill(s)` panels shown under [How skills reach each agent](#how-skills-reach-each-agent), naming each agent that was linked or copied.\n\nThe CLI resolves the target agents like this:\n\n- **Running inside an agent.** When the CLI runs inside an agent (for example, when your agent invokes it for you), it goes non-interactive and targets that agent plus the shared store.\n- **Run from your shell, one agent installed.** The CLI auto-selects that agent plus the shared store.\n- **Run from your shell, several agents installed.** The CLI prompts you to choose, pre-selecting your last-used agents (or the common defaults `claude-code`, `codex`, `opencode` on a first run).\n- **`--agent` passed.** The CLI uses exactly what you specify, after validation.\n\nThese are the headline agent identifiers. Names are case-sensitive.\n\n| Agent          | `--agent` identifier |\n| -------------- | -------------------- |\n| Claude Code    | `claude-code`        |\n| Cursor         | `cursor`             |\n| GitHub Copilot | `github-copilot`     |\n| Codex          | `codex`              |\n| Continue       | `continue`           |\n| Gemini CLI     | `gemini-cli`         |\n| Windsurf       | `windsurf`           |\n\nThe `skills` CLI supports 55+ agents. For the complete list, plus the exact directory each agent installs into, see the [Reference](./reference.md).\n\nBecause identifiers are case-sensitive, `copilot` and `Claude-Code` are not valid. An invalid value fails fast and lists every valid name so you can copy the right one:\n\n```text\n┌─Invalid agents───────────────────────────────────────────────────────────────┐\n│ Invalid agents: bogus                                                        │\n│                                                                              │\n│ Valid agents: adal, aider-desk, amp, antigravity, augment, bob, claude-code, │\n│ cline, codearts-agent, codebuddy, codemaker, codestudio, codex,              │\n│ command-code, continue, cortex, crush, cursor, deepagents, devin, dexto,     │\n│ droid, firebender, forgecode, gemini-cli, github-copilot, goose,             │\n│ hermes-agent, iflow-cli, junie, kilo, kimi-cli, kiro-cli, kode, mcpjam,      │\n│ mistral-vibe, mux, neovate, openclaw, opencode, openhands, pi, pochi, qoder, │\n│ qwen-code, replit, roo, rovodev, tabnine-cli, trae, trae-cn, universal,      │\n│ warp, windsurf, zencoder                                                     │\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\n# Project and global scope\n\nThe CLI installs into one of two scopes. Understanding the difference tells you where skills live and who shares them.\n\n**Project scope is the default.** The CLI records the installed skills in a `skills-lock.json` file in your working directory and materializes the skill folders under `./.agents/skills`. Commit `skills-lock.json` so everyone who clones the repository shares the same skill set. This is the right scope for skills your whole team should use on a given project.\n\n**Global scope (`--global` or `-g`) installs skills for your user account**, across every project.\n\n```shell\ndnx skills add anthropics/skills --global\n```\n\nIn global scope the lock file lives at `~/.local/share/skills/.skill-lock.json` (honoring `XDG_DATA_HOME` if you set it), and the skill folders are materialized under `~/.agents/skills`.\n\nIn both scopes, the CLI materializes each skill once in a canonical store, then makes each targeted agent point at it.\n\n# How skills reach each agent\n\nBy default, the CLI writes each skill once into the canonical store and creates a symlink from every targeted agent's directory back to it. Editing the one canonical copy updates the skill for every agent at once, so you maintain a single source of truth.\n\n```mermaid\nflowchart LR\n  S[\"Source (repo, URL, or local path)\"] --> C[\"Canonical store (.agents/skills)\"]\n  C -. \"symlink\" .-> A1[\".claude/skills\"]\n  C -. \"symlink\" .-> A2[\".windsurf/skills\"]\n  C --> A3[\"Universal agents (.agents/skills is the store)\"]\n```\n\nSome agents read directly from the shared `.agents/skills` store, so their skills directory _is_ that store and no symlink is needed. The [Reference](./reference.md) lists which agents read from the shared store and the directory each agent installs into.\n\nTo copy files instead of symlinking, pass `--copy`. Use it for sandboxed agents that cannot follow symlinks (for example, agents running in containers where symlinks across mounts break):\n\n```shell\ndnx skills add anthropics/skills --copy --agent claude-code --agent windsurf\n```\n\nThe CLI also copies automatically in two cases, so you rarely need `--copy` by hand:\n\n- When a symlink cannot be created (for example, on Windows without the symlink privilege), the CLI falls back to copying for that agent.\n- When every targeted agent shares one skills directory, the CLI copies, because symlinking only makes sense across distinct directories.\n\nA successful install reports which agents were linked or copied and where each skill landed:\n\n```text\nSource: https://github.com/owner/skills.git\nFound 1 skill(s)\n\n┌─Installation Summary─────────────────────────────────────────────────────────┐\n│ Canonical: /your-project/.agents/skills/alpha                                │\n│ Symlinked:  Claude Code, Windsurf                                            │\n└──────────────────────────────────────────────────────────────────────────────┘\n┌─Installed 1 skill(s)─────────────────────────────────────────────────────────┐\n│ ✓ alpha                                                                      │\n│   → /your-project/.claude/skills/alpha                                       │\n└──────────────────────────────────────────────────────────────────────────────┘\n\nDone!  Review skills before use; they run with full agent permissions.\n```\n\nIf everything worked, you should see the `Installation Summary` panel followed by an `Installed N skill(s)` panel and the safety reminder. To confirm later, run `dnx skills list` (see the [Reference](./reference.md)).\n\n# Scan nested skills with --full-depth\n\nBy default, the CLI installs the skill at the source root if one exists there. If the root is not itself a skill, it discovers every nested skill instead. That fast path covers most repositories.\n\nTo find skills in nested and curated directories that the default scan does not reach, pass `--full-depth`:\n\n```shell\ndnx skills add owner/curated-skills --full-depth\n```\n\nThe install reports the same `Installation Summary` and `Installed N skill(s)` panels shown under [How skills reach each agent](#how-skills-reach-each-agent); only the set of discovered skills differs.\n\n`--full-depth` widens _discovery_: it scans nested directories and curated locations (such as `skills/.curated`) so the CLI finds skills the default scan would skip. It does not change clone depth. Clones are always shallow regardless of this flag.\n\n# Install from a private repository\n\nThe CLI never manages or prompts for credentials. It shells out to `git`, which uses your own setup: SSH agent keys, a git credential helper, `gh` authentication, or `~/.netrc`. To avoid hanging on a missing credential, it sets `GIT_TERMINAL_PROMPT=0`, so an unauthenticated clone fails fast with a clear error instead of waiting at a prompt.\n\nTo install from a private repository, make sure your normal git auth already works, then run `add` as usual:\n\n```shell\ndnx skills add owner/private-skills --agent claude-code\n```\n\nThis prints the same `Installation Summary` and `Installed N skill(s)` panels shown under [How skills reach each agent](#how-skills-reach-each-agent), once the clone authenticates.\n\nBefore you install, verify your access with one of:\n\n```shell\nssh -T git@github.com   # confirm your SSH key reaches GitHub\ngh auth login           # or authenticate the GitHub CLI\n```\n\nA working SSH key prints the well-known success line (GitHub closes the connection because it does not provide shell access):\n\n```text\nHi <user>! You've successfully authenticated, but GitHub does not provide shell access.\n```\n\nIf a clone fails with an authentication error, the CLI prints guidance pointing you back to your git credentials. See [Troubleshooting](./troubleshooting.md) for the full list of clone and auth failures.\n\n# Keep skills up to date\n\n`dnx skills update` checks your installed skills for newer versions. It has the aliases `upgrade` and `check`.\n\n```shell\ndnx skills update -g\n```\n\n```text\nChecking for skill updates...\n\nChecking global skill 1/1: my-skill\nFound 1 global update(s)\n\nUpdate available: my-skill\n  Run: skills add owner/repo/skills/my-skill -g -y\n\nUpdates available for 1 skill(s); no updates were applied.\n```\n\n**`update` only reports; it never applies changes.** It prints the exact `skills add ... -y` command to run for each skill that has an update (prefix it with `dnx` when you run through `dnx`). Copy that command and run it yourself to apply the update. The output is explicit: `no updates were applied.`\n\nScope the check the same way you scope an install:\n\n- `-g` (or `--global`) checks global skills only.\n- `-p` (or `--project`) checks project skills only.\n- Pass both, or name specific skills, to check both scopes.\n- With no scope flag in an interactive shell, the CLI prompts you to choose. Non-interactively (for example with `-y`), it checks both scopes.\n\nWhen there is nothing to update, you get a clean report:\n\n```text\nChecking for skill updates...\n\nChecking global skill 1/1: my-skill\nAll global skills are up to date\n```\n\nThe update check calls the GitHub API. If you hit a rate limit, set a `GITHUB_TOKEN` or `GH_TOKEN` environment variable (or sign in with `gh auth login`) and the CLI uses it for the check. See [Troubleshooting](./troubleshooting.md) for rate-limit and timeout details.\n\n# Remove skills\n\n`dnx skills remove` uninstalls skills. It unlinks each agent's copy and removes the canonical store entry once no remaining agent references it, then updates the lock file.\n\nTo remove specific skills by name, list them:\n\n```shell\ndnx skills remove alpha --yes\n```\n\n```text\nSuccessfully removed 1 skill(s)\n```\n\nTo remove everything, pass `--all`:\n\n```shell\ndnx skills remove --all\n```\n\n```text\nSuccessfully removed 1 skill(s)\n```\n\nTo limit removal to specific agents, add `--agent`. To target your user-level skills, add `--global`.\n\nRun `dnx skills remove` with no names to remove interactively: the CLI shows a multi-select prompt, then a confirmation that defaults to **no**. Declining cancels and removes nothing:\n\n```text\n$ dnx skills remove\n\nRemoval cancelled\n```\n\nIf a named skill is not installed, the CLI tells you and exits cleanly without changing anything:\n\n```text\nNo matching skills found for: nope\n```\n\n# Next steps\n\n- [Authoring Skills](./authoring-skills.md): write and publish your own `SKILL.md` with `dnx skills init`.\n- [Reference](./reference.md): every command, flag, the full list of 55+ agents, and per-agent install directories.\n- [Troubleshooting](./troubleshooting.md): clone failures, authentication errors, rate limits, and symlink fallbacks.\n","website/content/docs/skills/troubleshooting.md":"---\ntitle: \"Troubleshooting\"\ndescription: \"Troubleshoot `skills` CLI errors: each section maps the exact message the CLI prints to its cause and a copy-pasteable fix for installing and updating skills.\"\n---\n\nThis page maps the errors and surprises you hit when running `skills` to their cause and fix. Each section starts with the exact message the CLI prints (where one exists), explains why it happens, and gives you a copy-pasteable way out.\n\nIf you are new to `skills`, start with [Getting Started](./getting-started.md). For the full command and flag surface, see the [Reference](./reference.md). For what each agent identifier means and where skills land, see [Installing Skills](./installing-skills.md).\n\n# \"No valid skills found. Skills require a SKILL.md with name and description.\"\n\nYou ran `dnx skills add <source>` and the CLI reached the source but found nothing to install:\n\n```text\n$ dnx skills add ./my-skills --yes --agent claude-code\n# exit 1\n\nSource: /home/you/my-skills\nNo valid skills found. Skills require a SKILL.md with name and description.\n```\n\nCause: a skill is a directory that contains a `SKILL.md` file with both `name` and `description` in its YAML frontmatter. The CLI silently skips any folder that is missing the file, missing either field, or whose `name`/`description` collapses to empty. By default, it only looks at the source root (or the subpath you pointed it at), so a `SKILL.md` buried in a nested directory is not discovered.\n\nTo see exactly what the CLI finds without installing anything, run `--list`:\n\n```shell\ndnx skills add owner/repo --list\n```\n\n```text\nSource: https://github.com/owner/repo.git\nFound 2 skill(s)\n\nAvailable Skills\n  alpha\n    the alpha skill\n  beta\n    the beta skill\n\nUse --skill <name> to install specific skills\n```\n\nIf `--list` reports `Found 0 skill(s)`, work through these in order:\n\n| Check                                                     | Fix                                                                                                                            |\n| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| Is your path or subpath pointing at the right folder?     | Point at the directory that contains `SKILL.md`, or add the repo subpath: `#!shell dnx skills add owner/repo/skills/my-skill`. |\n| Does the `SKILL.md` have both `name:` and `description:`? | Add the missing field. Both must be non-empty. See [Authoring Skills](./authoring-skills.md).                                  |\n| Are the skills in nested directories?                     | Add `--full-depth` to scan nested directories: `#!shell dnx skills add owner/repo --full-depth --list`.                        |\n\n> `--full-depth` widens discovery so the CLI scans nested directories for skills. It does not change how much of the repository is cloned. Clones are always shallow regardless of this flag.\n\n# \"Invalid agents: &lt;name&gt;\"\n\nYou passed an `--agent` value that the CLI does not recognize:\n\n```text\n$ dnx skills add ./my-skills --yes --agent bogus\n# exit 1\n\nSource: /home/you/my-skills\nFound 1 skill(s)\n\n┌─Invalid agents───────────────────────────────────────────────────────────────┐\n│ Invalid agents: bogus                                                        │\n│                                                                              │\n│ Valid agents: adal, aider-desk, amp, antigravity, augment, bob, claude-code, │\n│ cline, codearts-agent, codebuddy, codemaker, codestudio, codex,              │\n│ command-code, continue, cortex, crush, cursor, deepagents, devin, dexto,     │\n│ droid, firebender, forgecode, gemini-cli, github-copilot, goose,             │\n│ hermes-agent, iflow-cli, junie, kilo, kimi-cli, kiro-cli, kode, mcpjam,      │\n│ mistral-vibe, mux, neovate, openclaw, opencode, openhands, pi, pochi, qoder, │\n│ qwen-code, replit, roo, rovodev, tabnine-cli, trae, trae-cn, universal,      │\n│ warp, windsurf, zencoder                                                     │\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\nCause: the value is misspelled or uses the wrong case. Agent identifiers are case-sensitive, and several differ from the product's marketing name. The most common mistakes:\n\n| You typed                   | Use instead      |\n| --------------------------- | ---------------- |\n| `copilot`, `github_copilot` | `github-copilot` |\n| `Claude-Code`, `claude`     | `claude-code`    |\n| `gemini`                    | `gemini-cli`     |\n| `roo-code`                  | `roo`            |\n\nThe error panel always prints every valid identifier, so copy the correct one from the list. The same `Invalid agents: <name>` message appears (without the panel) from `dnx skills list` and `dnx skills remove`. For the full table of identifiers and where each one installs skills, see [Installing Skills](./installing-skills.md) and the [Reference](./reference.md).\n\n# Cloning a private repository fails with \"Authentication failed\"\n\n`dnx skills add` reports an authentication error and stops before installing.\n\nCause: the CLI never prompts for credentials. It shells out to your own `git`, which uses your existing setup (SSH agent keys, a git credential helper, `gh` auth, or `~/.netrc`). When git cannot authenticate, the CLI surfaces the failure instead of hanging. Any credentials embedded in a URL are redacted from the output, so secrets never appear in errors or in the lock file.\n\nTo fix it, confirm your machine can reach the repository, then retry the same `dnx skills add` command.\n\nFor SSH sources (`git@github.com:owner/repo.git`):\n\n```shell\nssh -T git@github.com\n# Hi <you>! You've successfully authenticated, but GitHub does not provide shell access.\n```\n\nFor HTTPS sources, authenticate with the GitHub CLI or configure a git credential helper. These are one-time setup commands whose output varies by environment:\n\n```shell\ngh auth login                         # uses the gh credential helper\n# or\ngit config --global credential.helper store\n```\n\nAfter `gh auth login` completes, it confirms the authenticated account.\n\nOnce `git clone <repo>` succeeds on its own, `dnx skills add <repo>` will succeed too.\n\n# The clone times out\n\nA large repository can exceed the default clone budget and cause the CLI to abort the fetch.\n\nCause: the CLI caps each clone at 5 minutes (300000 ms). The clone is always shallow (latest commit only), but a very large repository or a slow connection can still run past the limit.\n\nTo raise the timeout, set `SKILLS_CLONE_TIMEOUT_MS` in milliseconds before running the command:\n\n```shell\nSKILLS_CLONE_TIMEOUT_MS=600000 dnx skills add owner/big-repo --agent claude-code   # 10 minutes\n```\n\nWith the longer budget the clone finishes and the install completes with the usual `Installed 1 skill(s)` panel.\n\nAlternatively, clone the repository yourself and point `skills` at the local copy. This skips the network step entirely:\n\n```shell\ngit clone --depth 1 https://github.com/owner/big-repo.git\ndnx skills add ./big-repo --agent claude-code\n```\n\nPointing `skills` at the local clone installs the skill without touching the network and prints the same `Installed 1 skill(s)` panel.\n\n# A skill does not appear for one agent\n\n`dnx skills add` reports success, the skill shows up in `dnx skills list`, but one of your agents does not see it.\n\nCause: agents that keep skills in their own directory (for example `.claude/skills` for Claude Code or `.windsurf/skills` for Windsurf) only get a link when that agent's directory already exists in your project. The CLI will not create a config directory for an agent you do not use. When the directory is missing, it skips the link for that agent but still materializes the skill in the shared `.agents/skills` store, so the skill is installed; it is only the per-agent link that is missing.\n\nPick whichever fix matches your intent:\n\n| Goal                                                           | Fix                                                                                                                                   |\n| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |\n| You do use that agent in this project                          | Create its directory, then re-run the install: `#!shell mkdir -p .claude && dnx skills add owner/repo --agent claude-code`.           |\n| You want a self-contained copy regardless of agent directories | Add `--copy` to write the skill straight into each agent's directory: `#!shell dnx skills add owner/repo --agent claude-code --copy`. |\n| You meant a different agent                                    | Re-run with the correct `--agent` value. See [Installing Skills](./installing-skills.md).                                             |\n\nAfter the directory exists, re-running the install links the skill into `.claude/skills`. The Installation Summary then lists `Symlinked:  Claude Code` instead of skipping that agent.\n\nAgents that share the universal `.agents/skills` store (Cursor, Codex, GitHub Copilot, Gemini CLI, and others) always see the skill because their directory is the canonical store.\n\n# Symlinks are not created (Windows)\n\nOn Windows, `skills` copies skills into agent directories instead of linking them.\n\nCause: creating a symlink on Windows requires either an elevated process or Developer Mode. When the CLI cannot create the link, it automatically falls back to copying the skill so the install still succeeds. The skill works either way; the only difference is that copies do not share a single editable source of truth the way symlinks do.\n\nTo get symlinks instead of copies, choose one:\n\n- Enable Developer Mode (Settings, \"For developers\", \"Developer Mode\"), then re-run the command.\n- Run your terminal elevated (\"Run as administrator\") and re-run the command.\n\nIf you prefer copies and want the CLI to copy without attempting a symlink first, pass `--copy` explicitly:\n\n```shell\ndnx skills add owner/repo --agent claude-code --copy\n```\n\nThe output shows the skill was copied rather than linked: the Installation Summary lists `Copied:  Claude Code`, and the skill is written directly into `.claude/skills`.\n\n# \"skills update\" cannot check a skill or hits a rate limit\n\n`dnx skills update` reports that one or more skills could not be checked:\n\n```text\n$ dnx skills update -g\n\nChecking for skill updates...\n\n\n1 skill(s) cannot be checked automatically:\n  * legacy (Private or deleted repo)\n    To update: skills add https://github.com/owner/repo -g -y\n```\n\nCause: `update` checks for newer versions by calling the GitHub API, and unauthenticated calls are rate-limited. It also cannot diff every kind of source. Skills installed from a local path, a generic git URL, a well-known HTTP source, or a private or deleted repository have no checkable remote tree, so they are reported as \"cannot be checked automatically\" with a manual refresh hint.\n\nTo raise the rate limit, give `skills` a GitHub token and re-run. The CLI reads `GITHUB_TOKEN`, then `GH_TOKEN`, then falls back to `gh auth token`:\n\n```shell\nexport GITHUB_TOKEN=ghp_...   # or: gh auth login\ndnx skills update\n```\n\nWith the token in place the rate limit clears and the check completes:\n\n```text\nChecking for skill updates...\n\nAll skills are up to date.\n```\n\nFor sources that can never be checked automatically, re-install with `dnx skills add` to refresh them. The `update` output prints the exact command to run for each one:\n\n```shell\ndnx skills add owner/repo/skills/my-skill -y\n```\n\nThe refresh re-installs the skill from its source and prints the usual `Installed 1 skill(s)` panel.\n\n> `dnx skills update` only checks for and reports available updates. It never applies them. Whatever it finds, it prints the precise `skills add ...` command for you to run (prefix it with `dnx` when you use `dnx`). The aliases `dnx skills upgrade` and `dnx skills check` behave identically. See the [Reference](./reference.md).\n\n# \"... is newer than this skills supports\"\n\nA command refuses to write to a lock file and reports that the on-disk version is newer than this version of `skills` supports.\n\nCause: the lock file (`skills-lock.json` in your project, or the global `.skill-lock.json`) was written by a newer version of `skills` than the one you are running. The CLI reads newer lock files but refuses to modify them, so it does not corrupt state written by a version it does not understand.\n\nTo fix it, update `skills` to the latest release:\n\n```shell\ndotnet tool update -g skills\n```\n\nA successful upgrade reports the version change:\n\n```text\nTool 'skills' was successfully updated from version 0.1.0 to version 0.3.0.\n```\n\nIf you no longer need the existing lock state and want to start fresh, delete the lock file and re-install your skills. The project lock lives at `skills-lock.json` in your working directory; the global lock lives at `~/.local/share/skills/.skill-lock.json` (or under `$XDG_DATA_HOME/skills` if that variable is set).\n\n> [!WARNING]\n> **Deleting a lock file discards update tracking.** The CLI uses the lock file to know what is installed and to check for updates. After deleting it, run `dnx skills add` again for each skill so the CLI can rebuild the lock. The installed skill folders themselves are not removed by deleting the lock.\n\n# Bundled binary assets are missing from a skill\n\nA skill installs, but a binary file it ships (an image, a model, a compiled tool) is a tiny placeholder or absent.\n\nCause: the CLI disables Git LFS while cloning, so only LFS pointer files are fetched, not the large binaries they track. This keeps clones fast and shallow, but it means LFS-tracked assets do not arrive with the skill.\n\nTo fix it, change how the skill stores its assets:\n\n- Store skill assets without Git LFS so they travel as ordinary files in the repository.\n- Vendor the assets directly into the skill folder (commit the real files alongside `SKILL.md`).\n\nIf you author the skill yourself, see [Authoring Skills](./authoring-skills.md) for how to lay out bundled resources.\n\n# \"Failed to remove\" a skill\n\n`dnx skills remove` reports that it could not remove a skill:\n\n```text\n$ dnx skills remove \"My Skill\" --yes\n# exit 1\n\nFailed to remove 1 skill(s)\n  My Skill: ...\n```\n\nCause: the CLI removes a skill by the sanitized, lowercase, hyphenated name it uses on disk (for example `my-skill`). A folder created outside `skills` whose name does not match that sanitized form is not something the CLI will delete automatically, so it reports the failure rather than falsely claiming success. The CLI also refuses to delete a real non-empty directory or file it did not create, which protects your own data.\n\nTo fix it, delete the folder yourself from the skills directory. For a project install that is `./.agents/skills/<folder>`; for the corresponding agent directory it is, for example, `./.claude/skills/<folder>`. For a global install the canonical store is `~/.agents/skills/<folder>`.\n\n```shell\nrm -rf \"./.agents/skills/My Skill\"\n```\n\nRun `dnx skills list` afterward to confirm the skill is gone. The listing no longer shows the removed skill:\n\n```text\n$ dnx skills list\n\nNo project skills found.\nTry listing global skills with -g\n```\n\n# Next steps\n\n- [Reference](./reference.md): every command, flag, exit code, and environment variable in one place.\n- [Installing Skills](./installing-skills.md): sources, scopes, agent targeting, and the symlink versus copy model.\n- Still stuck? Ask in the [ChilliCream Slack](https://slack.chillicream.com/).\n","website/content/docs/skills/reference.md":"---\ntitle: \"Reference\"\ndescription: \"Complete `skills` CLI reference covering every command and flag, JSON output, exit codes, environment variables, file locations, and supported agents.\"\n---\n\nThis page is the complete, precise reference for the `skills` command surface, JSON output, exit codes, environment variables, file locations, and supported agents. It is meant for lookup, not for learning. To learn by doing, start at [Installing Skills](./installing-skills.md) and [Authoring Skills](./authoring-skills.md).\n\nEvery command prints the same per-command help at the terminal. Run `dnx skills <command> --help` to see the synopsis, arguments, and options for that command.\n\n```shell\ndnx skills add --help\n```\n\n```text\nDescription:\n  Add a skill from a source\n\nUsage:\n  skills add [<source>] [options]\n\nArguments:\n  <source>  Source to fetch skills from (e.g., owner/repo, URL, local path)\n\nOptions:\n  -g, --global    Install globally\n  -a, --agent     Target agent(s)\n  -s, --skill     Skill name filter(s)\n  -y, --yes       Skip prompts (non-interactive)\n  --all           Install all skills to all agents\n  --copy          Copy instead of symlinking\n  --full-depth    Scan nested directories for skills\n  -l, --list      List available skills without installing\n  -?, -h, --help  Show help and usage information\n```\n\n> The binary on your PATH is `skills`. Install it with `#!shell dotnet tool install -g skills`, or run it without installing via `dnx skills <command>` (requires the .NET 10 SDK or later). Both forms accept the same commands, arguments, and options documented below.\n\n# Commands\n\n`skills` has five commands: `add`, `remove`, `list`, `update`, and `init`. Each command's options are independent. There are no shared global options beyond `--help` and `--version` (see [Global flags](#global-flags)).\n\n## skills add &lt;source&gt;\n\nAdd skills from a source. Skills are discovered at the source, then materialized into a canonical store and linked into each target agent's skills directory.\n\n```text\ndnx skills add <source> [options]\n```\n\n### Arguments\n\n| Argument | Arity | Required | Description                                                                                                                                                        |\n| -------- | ----- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `source` | one   | yes      | Source to fetch skills from (for example `owner/repo`, a full git URL, or a local path). If omitted, the command exits 1 with `Missing required argument: source`. |\n\n### Options\n\n| Option         | Alias  | Type                | Default         | Description                                                                                                                                                                                         |\n| -------------- | ------ | ------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--global`     | `-g`   | bool                | `false`         | Install to the global scope (your home directory) instead of the current project.                                                                                                                   |\n| `--agent`      | `-a`   | string (repeatable) | (auto-detected) | Target agent(s). Repeatable and space-separated (`--agent claude-code cursor` or `--agent claude-code --agent cursor`). `--agent *` targets every agent. See [Supported agents](#supported-agents). |\n| `--skill`      | `-s`   | string (repeatable) | (all)           | Install only skills whose name matches the given filter(s). Repeatable.                                                                                                                             |\n| `--yes`        | `-y`   | bool                | `false`         | Skip all prompts and run non-interactively.                                                                                                                                                         |\n| `--all`        | (none) | bool                | `false`         | Install all skills to all agents. Implies `--skill *`, `--agent *`, and `--yes`.                                                                                                                    |\n| `--copy`       | (none) | bool                | `false`         | Copy skill files into each agent directory instead of symlinking. Use for agents that do not follow symlinks.                                                                                       |\n| `--full-depth` | (none) | bool                | `false`         | Widen discovery to scan nested directories in the source, not only the source root. This does not change the git clone (clones are always shallow).                                                 |\n| `--list`       | `-l`   | bool                | `false`         | List the available skills at the source without installing anything, then exit.                                                                                                                     |\n\nThe default install mode is symlink: the CLI materializes each skill once into a canonical store and creates a relative symlink from each agent directory back to it. Pass `--copy` to copy instead. When every selected agent shares one skills directory, copy is used automatically.\n\nFor sources, scopes, and install mechanics, see [Installing Skills](./installing-skills.md). For agent targeting, see [Supported agents](#supported-agents).\n\n## skills remove [skills...]\n\nRemove installed skills. With no skill names and an interactive terminal, the CLI prompts you to select which skills to remove.\n\n```text\ndnx skills remove [skills...] [options]\n```\n\n### Arguments\n\n| Argument | Arity        | Required | Description                                                                                          |\n| -------- | ------------ | -------- | ---------------------------------------------------------------------------------------------------- |\n| `skills` | zero or more | no       | Skill names to remove. Matched case-insensitively. With no names and no `--all`, runs interactively. |\n\n### Options\n\n| Option     | Alias  | Type                | Default | Description                                                  |\n| ---------- | ------ | ------------------- | ------- | ------------------------------------------------------------ |\n| `--global` | `-g`   | bool                | `false` | Remove from the global scope instead of the current project. |\n| `--agent`  | `-a`   | string (repeatable) | (all)   | Limit removal to specific agent(s). Repeatable.              |\n| `--yes`    | `-y`   | bool                | `false` | Skip prompts and run non-interactively.                      |\n| `--all`    | (none) | bool                | `false` | Remove every installed skill.                                |\n\nIn interactive mode, the CLI shows a multiselect prompt followed by a confirmation prompt. The confirmation defaults to no. Declining the confirmation prints `Removal cancelled` and exits with code 130 (see [Exit codes](#exit-codes)).\n\n```text\n$ dnx skills remove alpha\n# exit 130\n\nRemoval cancelled\n```\n\n## skills list\n\nList installed skills. With no options, lists the current project's skills.\n\n```text\ndnx skills list [options]\n```\n\nThis command takes no positional arguments.\n\n### Options\n\n| Option     | Alias  | Type                | Default | Description                                                                           |\n| ---------- | ------ | ------------------- | ------- | ------------------------------------------------------------------------------------- |\n| `--global` | `-g`   | bool                | `false` | List skills in the global scope instead of the current project.                       |\n| `--agent`  | `-a`   | string (repeatable) | (none)  | Filter the listing to specific agent(s). Repeatable.                                  |\n| `--format` | (none) | `text` \\| `json`    | `text`  | Output format. `json` emits a JSON array to stdout (see [JSON output](#json-output)). |\n| `--json`   | (none) | bool                | `false` | Shorthand for `--format json`.                                                        |\n\nJSON output is enabled when either `--json` is present or `--format json` is set (case-insensitive). Enabling JSON suppresses the banner and writes the array to stdout.\n\n## skills update [skills...]\n\nCheck for available updates and print the exact command to apply each one.\n\n```text\ndnx skills update [skills...] [options]\n```\n\n> Aliases: `upgrade` and `check`. `dnx skills upgrade` and `dnx skills check` are identical to `dnx skills update`.\n\n> [!WARNING]\n> **`update` only reports.** It never modifies files or lock files. For each skill that has an update, it prints a `skills add ...` command you can copy and run to apply it (run it as `dnx skills add ...` if you use `dnx`). The command always exits 0, even when updates are available. Its output ends with `no updates were applied.`\n\n### Arguments\n\n| Argument | Arity        | Required | Description                                                                                                        |\n| -------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------ |\n| `skills` | zero or more | no       | Optional skill names to check. Scope is resolved the same way with or without names (see the scope options below). |\n\n### Options\n\n| Option      | Alias | Type | Default | Description                                                                |\n| ----------- | ----- | ---- | ------- | -------------------------------------------------------------------------- |\n| `--global`  | `-g`  | bool | `false` | Check global skills only.                                                  |\n| `--project` | `-p`  | bool | `false` | Check project skills only.                                                 |\n| `--yes`     | `-y`  | bool | `false` | Skip the interactive scope prompt. Non-interactive runs check both scopes. |\n\nWith neither `-g` nor `-p`, an interactive terminal prompts you to choose Project, Global, or Both. Passing both flags, or running non-interactively, checks both scopes.\n\n```text\n$ dnx skills update -g\n\nChecking for skill updates...\n\nChecking global skill 1/1: my-skill\nFound 1 global update(s)\n\nUpdate available: my-skill\n  Run: skills add owner/repo/skills/my-skill -g -y\n\nUpdates available for 1 skill(s); no updates were applied.\n```\n\n## skills init [name]\n\nScaffold a new skill directory containing a `SKILL.md` template. This command has no options.\n\n```text\ndnx skills init [name]\n```\n\n### Arguments\n\n| Argument | Arity       | Required | Description                                                                                                                                                       |\n| -------- | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `name`   | zero or one | no       | Skill name. Creates `<name>/SKILL.md`. The name is sanitized to a slug. With no name, derives the slug from the current directory and writes `SKILL.md` in place. |\n\nIf the target `SKILL.md` already exists, the CLI does not overwrite it. It prints `Skill already exists at <path>` and exits 0.\n\n```text\n$ dnx skills init my-skill\n\nInitialized skill: my-skill\n\nCreated:\n  my-skill/SKILL.md\n\nNext steps:\n  1. Edit my-skill/SKILL.md to define your skill instructions\n  2. Update the name and description in the frontmatter\n\nPublishing:\n  GitHub: Push to a repo, then skills add <owner>/<repo>\n  URL:    Host the file, then skills add https://example.com/my-skill/SKILL.md\n```\n\nSee [Authoring Skills](./authoring-skills.md) for the `SKILL.md` format and publishing workflow.\n\n## Global flags\n\nThese are provided on the root command and on every subcommand.\n\n| Option      | Aliases    | Type | Description                                            |\n| ----------- | ---------- | ---- | ------------------------------------------------------ |\n| `--help`    | `-h`, `-?` | bool | Show help. On a subcommand, shows that command's help. |\n| `--version` | (none)     | bool | Print the installed CLI version and exit 0.            |\n\nRunning `skills` with no arguments shows the banner and exits 0. Running `#!shell dnx skills --help` shows curated top-level help. A bare `--` token is removed before parsing, so `#!shell dnx skills add --agent codex -- owner/repo` parses the same as without it.\n\n# JSON output\n\n`#!shell dnx skills list --json` (equivalently `#!shell dnx skills list --format json`) prints a JSON array to stdout. Each element describes one installed skill.\n\n```shell\ndnx skills list --json\n```\n\n```json\n[\n  {\n    \"name\": \"alpha\",\n    \"path\": \"/home/you/project/.agents/skills/alpha\",\n    \"scope\": \"project\",\n    \"agents\": [\"Claude Code\", \"Windsurf\"]\n  }\n]\n```\n\n| Field    | Type     | Description                                                                                                                |\n| -------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |\n| `name`   | string   | The skill's sanitized name (its on-disk directory name).                                                                   |\n| `path`   | string   | Absolute path to the skill in the canonical store.                                                                         |\n| `scope`  | string   | `\"project\"` or `\"global\"`. `\"global\"` when listed with `-g`, otherwise `\"project\"`.                                        |\n| `agents` | string[] | Display names of agents linked to this skill (for example `Claude Code`). Empty when the skill is not linked to any agent. |\n\nThe array is written to stdout, so you can pipe it to a tool such as `jq`. Banner and progress output are suppressed in JSON mode.\n\n# Exit codes\n\n`skills` uses exactly three exit codes.\n\n| Code  | Name      | Meaning                                                                                                                                        |\n| ----- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| `0`   | Success   | The command completed. Note that `update` exits 0 even when updates are available, and `remove` exits 0 when there is nothing to remove.       |\n| `1`   | Failure   | The command failed (for example an invalid agent name, no valid skills found, or a file system error). The error message is written to stderr. |\n| `130` | Cancelled | The operation was cancelled, either by declining an interactive confirmation or by pressing Ctrl+C.                                            |\n\n# Environment variables\n\n| Variable                  | Default          | Effect                                                                                                                                                            |\n| ------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `SKILLS_CLONE_TIMEOUT_MS` | `300000`         | Git clone timeout in milliseconds (5 minutes). Must parse to a positive integer, otherwise the default is used. Raise it for large repositories or slow networks. |\n| `GITHUB_TOKEN`            | (unset)          | A GitHub API token. Used only by `update` to raise GitHub API rate limits when checking for updates. Not used for cloning.                                        |\n| `GH_TOKEN`                | (unset)          | Fallback GitHub API token. Consulted by `update` after `GITHUB_TOKEN`. Same effect.                                                                               |\n| `INSTALL_INTERNAL_SKILLS` | (unset)          | Set to `1` or `true` to include skills their authors marked as internal in discovery. By default such skills are hidden.                                          |\n| `CLAUDE_CONFIG_DIR`       | `~/.claude`      | Overrides the Claude Code configuration directory used for detection and global installs.                                                                         |\n| `CODEX_HOME`              | `~/.codex`       | Overrides the Codex configuration directory used for detection and global installs.                                                                               |\n| `VIBE_HOME`               | `~/.vibe`        | Overrides the Mistral Vibe configuration directory used for detection and global installs.                                                                        |\n| `XDG_DATA_HOME`           | `~/.local/share` | Root for the global lock location. The global lock lives at `$XDG_DATA_HOME/skills/.skill-lock.json`.                                                             |\n\n`XDG_CONFIG_HOME` (default `~/.config`) and `XDG_STATE_HOME` (default `~/.local/state`) affect where the CLI keeps its own configuration and logs, and where several agents resolve their global directories.\n\nFor private repositories, the CLI shells out to `git` and uses your existing git credentials (SSH agent, credential helper, `gh` auth). See [Troubleshooting](./troubleshooting.md) for authentication and rate-limit guidance.\n\n# File locations\n\nThe CLI writes a lock file per scope and materializes skills into a canonical store. Project scope is the current working directory; global scope is your home directory.\n\n| Scope   | Lock file                                                                              | Canonical skills store |\n| ------- | -------------------------------------------------------------------------------------- | ---------------------- |\n| Project | `skills-lock.json` (in the current working directory)                                  | `./.agents/skills`     |\n| Global  | `~/.local/share/skills/.skill-lock.json` (or `$XDG_DATA_HOME/skills/.skill-lock.json`) | `~/.agents/skills`     |\n\nNon-universal agents receive a symlink from their own directory (for example `.claude/skills/<name>`) back into the canonical store. Universal agents use the canonical store directly. See [Supported agents](#supported-agents) for per-agent directories.\n\n# Supported agents\n\nThe `skills` CLI supports 55+ agents. It detects which agents are installed on your machine by probing each agent's configuration directory, and it detects which agent it is running inside by reading environment variables that agent hosts set. When run inside a detected agent, `add` runs non-interactively and targets that agent plus the universal agents.\n\nAgent identifiers are case-sensitive (the identifier is `github-copilot`, not `copilot`). The `--agent` option is repeatable and accepts multiple values per token. `--agent *` targets all agents. \"Universal\" agents share the `.agents/skills` store, so installing a skill for one universal agent makes it visible to all of them.\n\nIn the table below, project directories are relative to the working directory and global directories are absolute (`~` is your home directory, `<config>` is `$XDG_CONFIG_HOME` or `~/.config`). Agents marked \"universal\" use the shared `.agents/skills` store at project scope.\n\n| Identifier       | Display name       | Project directory            | Global directory                             |\n| ---------------- | ------------------ | ---------------------------- | -------------------------------------------- |\n| `adal`           | AdaL               | `.adal/skills`               | `~/.adal/skills`                             |\n| `aider-desk`     | AiderDesk          | `.aider-desk/skills`         | `~/.aider-desk/skills`                       |\n| `amp`            | Amp                | `.agents/skills` (universal) | `<config>/agents/skills`                     |\n| `antigravity`    | Antigravity        | `.agents/skills` (universal) | `~/.gemini/antigravity/skills`               |\n| `augment`        | Augment            | `.augment/skills`            | `~/.augment/skills`                          |\n| `bob`            | IBM Bob            | `.bob/skills`                | `~/.bob/skills`                              |\n| `claude-code`    | Claude Code        | `.claude/skills`             | `~/.claude/skills` (via `CLAUDE_CONFIG_DIR`) |\n| `cline`          | Cline              | `.agents/skills` (universal) | `~/.agents/skills`                           |\n| `codearts-agent` | CodeArts Agent     | `.codeartsdoer/skills`       | `~/.codeartsdoer/skills`                     |\n| `codebuddy`      | CodeBuddy          | `.codebuddy/skills`          | `~/.codebuddy/skills`                        |\n| `codemaker`      | Codemaker          | `.codemaker/skills`          | `~/.codemaker/skills`                        |\n| `codestudio`     | Code Studio        | `.codestudio/skills`         | `~/.codestudio/skills`                       |\n| `codex`          | Codex              | `.agents/skills` (universal) | `~/.codex/skills` (via `CODEX_HOME`)         |\n| `command-code`   | Command Code       | `.commandcode/skills`        | `~/.commandcode/skills`                      |\n| `continue`       | Continue           | `.continue/skills`           | `~/.continue/skills`                         |\n| `cortex`         | Cortex Code        | `.cortex/skills`             | `~/.snowflake/cortex/skills`                 |\n| `crush`          | Crush              | `.crush/skills`              | `~/.config/crush/skills`                     |\n| `cursor`         | Cursor             | `.agents/skills` (universal) | `~/.cursor/skills`                           |\n| `deepagents`     | Deep Agents        | `.agents/skills` (universal) | `~/.deepagents/agent/skills`                 |\n| `devin`          | Devin for Terminal | `.devin/skills`              | `<config>/devin/skills`                      |\n| `dexto`          | Dexto              | `.agents/skills` (universal) | `~/.agents/skills`                           |\n| `droid`          | Droid              | `.factory/skills`            | `~/.factory/skills`                          |\n| `firebender`     | Firebender         | `.agents/skills` (universal) | `~/.firebender/skills`                       |\n| `forgecode`      | ForgeCode          | `.forge/skills`              | `~/.forge/skills`                            |\n| `gemini-cli`     | Gemini CLI         | `.agents/skills` (universal) | `~/.gemini/skills`                           |\n| `github-copilot` | GitHub Copilot     | `.agents/skills` (universal) | `~/.copilot/skills`                          |\n| `goose`          | Goose              | `.goose/skills`              | `<config>/goose/skills`                      |\n| `hermes-agent`   | Hermes Agent       | `.hermes/skills`             | `~/.hermes/skills`                           |\n| `iflow-cli`      | iFlow CLI          | `.iflow/skills`              | `~/.iflow/skills`                            |\n| `junie`          | Junie              | `.junie/skills`              | `~/.junie/skills`                            |\n| `kilo`           | Kilo Code          | `.kilocode/skills`           | `~/.kilocode/skills`                         |\n| `kimi-cli`       | Kimi Code CLI      | `.agents/skills` (universal) | `~/.config/agents/skills`                    |\n| `kiro-cli`       | Kiro CLI           | `.kiro/skills`               | `~/.kiro/skills`                             |\n| `kode`           | Kode               | `.kode/skills`               | `~/.kode/skills`                             |\n| `mcpjam`         | MCPJam             | `.mcpjam/skills`             | `~/.mcpjam/skills`                           |\n| `mistral-vibe`   | Mistral Vibe       | `.vibe/skills`               | `~/.vibe/skills` (via `VIBE_HOME`)           |\n| `mux`            | Mux                | `.mux/skills`                | `~/.mux/skills`                              |\n| `neovate`        | Neovate            | `.neovate/skills`            | `~/.neovate/skills`                          |\n| `openclaw`       | OpenClaw           | `skills`                     | `~/.openclaw/skills`                         |\n| `opencode`       | OpenCode           | `.agents/skills` (universal) | `<config>/opencode/skills`                   |\n| `openhands`      | OpenHands          | `.openhands/skills`          | `~/.openhands/skills`                        |\n| `pi`             | Pi                 | `.pi/skills`                 | `~/.pi/agent/skills`                         |\n| `pochi`          | Pochi              | `.pochi/skills`              | `~/.pochi/skills`                            |\n| `qoder`          | Qoder              | `.qoder/skills`              | `~/.qoder/skills`                            |\n| `qwen-code`      | Qwen Code          | `.qwen/skills`               | `~/.qwen/skills`                             |\n| `replit`         | Replit             | `.agents/skills` (universal) | `<config>/agents/skills`                     |\n| `roo`            | Roo Code           | `.roo/skills`                | `~/.roo/skills`                              |\n| `rovodev`        | Rovo Dev           | `.rovodev/skills`            | `~/.rovodev/skills`                          |\n| `tabnine-cli`    | Tabnine CLI        | `.tabnine/agent/skills`      | `~/.tabnine/agent/skills`                    |\n| `trae`           | Trae               | `.trae/skills`               | `~/.trae/skills`                             |\n| `trae-cn`        | Trae CN            | `.trae/skills`               | `~/.trae-cn/skills`                          |\n| `universal`      | Universal          | `.agents/skills` (universal) | `<config>/agents/skills`                     |\n| `warp`           | Warp               | `.agents/skills` (universal) | `~/.agents/skills`                           |\n| `windsurf`       | Windsurf           | `.windsurf/skills`           | `~/.codeium/windsurf/skills`                 |\n| `zencoder`       | Zencoder           | `.zencoder/skills`           | `~/.zencoder/skills`                         |\n\nPassing an unknown identifier exits 1 and prints the full list of valid identifiers:\n\n```text\n$ dnx skills add ./local-path --yes --agent bogus\n# exit 1\n\nInvalid agents: bogus\n```\n\n# See also\n\n- [Installing Skills](./installing-skills.md): sources, scopes, and the install workflow in depth.\n- [Authoring Skills](./authoring-skills.md): the `SKILL.md` format, `dnx skills init`, and publishing.\n- [Troubleshooting](./troubleshooting.md): authentication, rate limits, timeouts, and common errors.\n","website/content/docs/skills/structure.yaml":"title: Skills\nitems:\n  - path: index\n    title: Introduction\n  - path: getting-started\n    title: Getting Started\n  - path: installing-skills\n    title: Installing Skills\n  - path: authoring-skills\n    title: Authoring Skills\n  - path: reference\n    title: Reference\n  - path: troubleshooting\n    title: Troubleshooting\n","src/HotChocolate/CostAnalysis/tools/oracle/LICENSE-graphql-static-analysis-rs.md":"# License notice: graphql-static-analysis-rs\n\n`dump_corpus.rs` in this directory is built against, and the vendored\n`exact-case.json` corpus is generated from,\n[`graphql-static-analysis-rs`](https://github.com/duckki/graphql-static-analysis-rs)\nat commit `fec57fd7a980b5399637fa464a9bdce0781d91dd` (v0.2.0):\n\n```\nMIT License\n\nCopyright 2026 graphql-static-analysis contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n\n`oracle.patch` and `dump_corpus.rs` are original files written for this\nrepository; they are not derived from the crate's own source and are covered\nby this repository's own license.\n","src/HotChocolate/CostAnalysis/tools/oracle/README.md":"# Cost differential oracle\n\nRegenerates the vendored ExactCase cost corpus\n(`../../test/CostAnalysis.Core.Conformance.Tests/__resources__/rust-corpus/`)\nfrom the MIT-licensed\n[`graphql-static-analysis-rs`](https://github.com/duckki/graphql-static-analysis-rs)\ncrate, the differential oracle for this cost analysis implementation.\n\n## Prerequisites\n\nCorpus regeneration and live differential runs require rustup with stable\nRust >= 1.90 (the pinned commit's `rust-version`) and a C++ compiler. The\ncrate's `fuzz` package links `libfuzzer-sys` 0.4 unconditionally, including\nfor a plain `cargo build` or `cargo run`. Install Rust with:\n\n```bash\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal\n. \"$HOME/.cargo/env\" && rustup toolchain install stable\n```\n\nThe scripts install nothing. `clone-oracle.sh` and `run-nightly.sh` print the\ninstall line when `cargo` is missing, and `run-nightly.sh` also rejects Rust\nversions below 1.90 and missing C++ compilers. Pull-request CI does not run\nRust. The scheduled workflow provisions stable Rust and uses the compiler on\n`ubuntu-26.04`.\n\n## Files\n\n- `clone-oracle.sh`: clones `graphql-static-analysis-rs` at the pinned commit\n  into the gitignored `.oracle/` next to this file, applies `oracle.patch`,\n  and copies `dump_corpus.rs` into the checkout's `fuzz/examples/`.\n- `oracle.patch`: a small patch against the pinned commit. `SCHEMA` and\n  `variable_values` in the crate's `fuzz/src/tree_summary/operation.rs` are\n  `pub(super)` (private to the fuzz package's own targets); the patch adds\n  `pub fn schema()` and `pub fn variables_json(variable_case: u8)` accessors\n  and registers `dump_corpus` as a `[[example]]` in `fuzz/Cargo.toml`.\n- `dump_corpus.rs`: the dump program itself (see below).\n- `oracle.rs`: a Rust example that coerces generated variables, builds a\n  `CostModel`, and evaluates each case with `ExactCase` and its declared\n  default list size.\n- `Fuzz/`: the deterministic .NET generator and comparison command. It emits\n  real `AddCostAnalyzer` interceptor schemas and synthetic annotated schemas.\n- `run-nightly.sh`: generates cases, runs the live oracle, compares raw f64\n  bits, and writes a standalone fixture for the first disagreement.\n- `LICENSE-graphql-static-analysis-rs.md`: the crate's MIT license text and\n  attribution for the vendored commit.\n\n## Running the live oracle\n\n```bash\nbash src/HotChocolate/CostAnalysis/tools/oracle/run-nightly.sh \\\n    --seed 1 --cases 200\n```\n\nEvery case stores its seed and uses the same finite `DefaultListSize` on both\nimplementations. Generated operations are query-only and reject introspection\nmeta-fields, `@defer`, and `@stream` before emission. Variables are valid for\nthe generated operation and are coerced by `apollo_compiler` before the Rust\nestimator runs.\n\nReal schemas are printed from servers configured with `AddCostAnalyzer`,\ncursor and offset paging, filtering, sorting, and list-of-scalar fields. The\nprinted SDL therefore carries explicit resolver, filter, sort, paging, and\nlist-of-scalar annotations. Synthetic schemas cover signed weights,\n`@listSize`, input defaults, interfaces, unions, and directive argument\nweights. Operations cover named fragments, Boolean directives, aliases, and\nduplicate response names.\n\n`slicingArgumentDefaultValue` is a ChilliCream extension. When a generated\noperation supplies none of a field's slicing arguments, the generator adds\nthe declared default literal to the oracle copy of that operation only. It\ndoes not rewrite the schema, and it adds nothing when any slicing argument is\nalready supplied.\n\nComparison uses the hexadecimal IEEE-754 bit patterns for `typeCost` and\n`fieldCost`. A mismatch exits nonzero and writes one isolated\n`source: \"fuzz-found\"` fixture under the conformance resources. Add this\nfixture to the conformance suite to run it without Rust.\n\n## Regenerating the corpus\n\n```bash\ncd src/HotChocolate/CostAnalysis/tools/oracle\n./clone-oracle.sh\ncargo run --manifest-path .oracle/fuzz/Cargo.toml --example dump_corpus -- \\\n    ../../test/CostAnalysis.Core.Conformance.Tests/__resources__/rust-corpus\n```\n\nThis overwrites `exact-case.json` and `manifest.json` in that directory.\nThe same pinned commit produces byte-identical output.\n\n## What the dump does\n\nThe corpus contains the ExactCase IBM-cost cases from the crate's 15,840-case\nmatrix. There are 1,980 candidates before invalid-variable exclusions and\ndeduplication.\n\nFor each row:\n\n- Rows with variables that fail GraphQL coercion are excluded and counted\n  in the manifest's `excludedInvalidVariables`.\n- Duplicate `(operation, variables, defaultListSize)` rows are excluded and\n  counted in `deduplicated`. Missing variables and an empty variables object\n  are equivalent.\n- The remaining rows are costed with the crate's own `CostEstimator` in\n  `ExactCase` mode, with `default_list_size` set to the row's `list_size`\n  (0..4 for the legacy-family rows; the structural rows fix it at 2). The\n  emitted `typeCost`/`fieldCost` are the raw `f64` values `CostEstimator`\n  returns, never the crate's `cost:T,F` display format.\n- `emitted + excludedInvalidVariables + deduplicated == exactCostRows` always\n  holds (asserted by the dump itself); the manifest records all four numbers\n  plus the pinned commit.\n\nThe emitted schema excludes the crate's `@tag` definition. None of the\nemitted operations uses that directive.\n\n## Rust-free validation\n\nThe generator can build and emit cases without cloning or running the oracle:\n\n```bash\ndotnet run --project src/HotChocolate/CostAnalysis/tools/oracle/Fuzz \\\n    --framework net11.0 -- --seed 1 --cases 20 \\\n    --emit-only /tmp/fuzz-cases.json\n```\n\nReviewers without Rust installed can still validate the committed artifact\nshape:\n\n```bash\npython3 -c \"\nimport json\nd = json.load(open('../../test/CostAnalysis.Core.Conformance.Tests/__resources__/rust-corpus/exact-case.json'))\nm = json.load(open('../../test/CostAnalysis.Core.Conformance.Tests/__resources__/rust-corpus/manifest.json'))\nassert m['matrixSize'] == 15840 and m['exactCostRows'] == 1980\nassert len(d) == m['emitted'] == 1980 - m['excludedInvalidVariables'] - m['deduplicated'], m\nassert all(r['backend'] == 'exact-case' and 'directive @tag' not in r['sdl'] for r in d)\nprint('ok', len(d))\n\"\n```\n\nThis does not re-run the estimator, so it cannot catch a wrong `typeCost` or\n`fieldCost`; it only checks the corpus's shape and bookkeeping.\n","src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/ReplyMailCommandTests.Reply_Should_ThreadUnderOriginalMessage_AndInheritRootSubject_When_JsonOutputIsRequested.md":"# Command: /replymailcommandtests.reply_should_threadunderoriginalmessage_andinheritrootsubject_when_jsonoutputisrequested\n\nPath: `src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/ReplyMailCommandTests.Reply_Should_ThreadUnderOriginalMessage_AndInheritRootSubject_When_JsonOutputIsRequested.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/ReplyMailCommandTests.Reply_Should_ThreadUnderOriginalMessage_AndInheritRootSubject_When_JsonOutputIsRequested.md)","src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/SendMailCommandTests.Send_Should_ReturnSendResult_When_JsonOutputIsRequested.md":"# Command: /sendmailcommandtests.send_should_returnsendresult_when_jsonoutputisrequested\n\nPath: `src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/SendMailCommandTests.Send_Should_ReturnSendResult_When_JsonOutputIsRequested.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/SendMailCommandTests.Send_Should_ReturnSendResult_When_JsonOutputIsRequested.md)","src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Tasks/__snapshots__/TaskStoreTests.ReleaseAssigneeAsync_Should_ReleaseInProgressTasksAndAppearInReady.md":"# Command: /taskstoretests.releaseassigneeasync_should_releaseinprogresstasksandappearinready\n\nPath: `src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Tasks/__snapshots__/TaskStoreTests.ReleaseAssigneeAsync_Should_ReleaseInProgressTasksAndAppearInReady.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Tasks/__snapshots__/TaskStoreTests.ReleaseAssigneeAsync_Should_ReleaseInProgressTasksAndAppearInReady.md)"},"files":{"website/AGENTS.md":"<!-- BEGIN:nextjs-agent-rules -->\n\n# This is NOT the Next.js you know\n\nThis version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.\n\n<!-- END:nextjs-agent-rules -->\n\n# Authoring markdown content\n\nWhen creating or editing content under `content/docs/` or `content/blog/`, follow\nthe conventions in [README.md → Authoring Markdown Content](./README.md#authoring-markdown-content).\nIt covers frontmatter, `structure.yaml` sidebars, links, images, YouTube videos,\nadmonitions, Mermaid diagrams, and MDX gotchas.\n\nWhen creating or editing a video under `content/videos/`, also follow\n[README.md → Videos](./README.md#videos) for the file name and frontmatter.\n\n# Components\n\nThis site is built to be extended agent-first: adding a page or component should\nbe mechanical and consistent. Keep the quality bar high; do not cut corners\nbecause an agent is doing the work.\n\n## Where code lives\n\n- **Pages**: `app/` route segments. Content/marketing routes live under\n  `app/(content)/`. Keep page files thin: compose section components, do not\n  inline large markup.\n- **Reusable components**: `src/components/`, one component per file\n  (PascalCase filename).\n- **Design-system primitives** (Button, Input, Image, Typography, ...):\n  `src/design-system/`.\n- **Icons and inline SVG art**: `src/icons/`, one per file.\n- A component that is only a child of one parent and is not reused elsewhere may\n  live in the parent's file. As soon as it is reused or is independently\n  meaningful, move it to its own file under `src/components/`.\n\n## Props\n\n- Declare props as an `interface` named `<Component>Props`.\n- Every property is `readonly`.\n- Do **not** export the props interface; it is the component's own\n  implementation detail.\n\n```tsx\ninterface ButtonProps {\n  readonly label: string;\n  readonly onClick?: () => void;\n}\n\nexport function Button({ label, onClick }: ButtonProps) {\n  // ...\n}\n```\n\n## SVG and icons\n\n- Add SVGs as inline React components in `src/icons/` that return `<svg>…</svg>`\n  directly, so the markup is inlined into the HTML.\n- Do **not** add raw `.svg` files to `public/` to load via `<img>` / `Image`:\n  the image pipeline does not process SVG, and inlining lets icons inherit\n  `currentColor` and be sized/positioned with CSS.\n- Accept `className` (and `style` when the caller positions the icon). Default\n  decorative icons to `aria-hidden=\"true\"`.\n- If the SVG uses element ids (e.g. gradient ids), prefix them per icon so\n  several inlined icons on the same page do not collide.\n\n## Typography\n\nUse the type scale from `app/globals.css` (`@theme`): the `text-hero` /\n`text-h1`…`text-h6` / `text-lead` / `text-body` / `text-caption` utilities (each\nships its line-height), the `font-heading` / `font-body` families (Tailwind\n`font-sans` maps to the body voice), and the `.hero` / `.lead` / `.caption`\nhelper classes. Avoid ad-hoc `text-4xl`-style sizes for display headings.\n\n## Before you finish\n\n- Verify visually against the running dev server (`npm run dev`).\n- `npx eslint <changed files>` must pass.\n- `npm run format` must be run and `npm run format:check` must pass (Prettier\n  formatting, including Tailwind class sorting, is enforced in CI).\n","website/content/docs/skills/getting-started.md":"---\ntitle: \"Getting Started\"\ndescription: \"Run the `skills` CLI with `dnx` and add your first Agent Skill to Claude Code or another AI coding agent in five minutes using `dnx skills add`.\"\n---\n\nBy the end of this guide you will have run `skills` and added your first skill to your agent.\n\n`skills` is a .NET CLI that installs, updates, and authors [Agent Skills](https://agentskills.io/home), the portable `SKILL.md` files that extend AI coding agents like Claude Code, Cursor, and GitHub Copilot. You point it at a source (a GitHub repo, a git URL, or a local folder), and it places the skill where your agent looks for it. Your agent then loads the skill on demand when a task matches it.\n\nThis page takes you from zero to one working skill. It takes about five minutes.\n\n# Prerequisites\n\nBefore you start, make sure you have the following:\n\n| Requirement                                                   | Why you need it                                                                                                                                                             |\n| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [.NET 10 SDK or newer](https://dotnet.microsoft.com/download) | To run `skills` with `dnx`, the way these docs show it. The `dnx` command ships with the .NET 10 SDK.                                                                       |\n| An AI coding agent                                            | The target for your skill. This guide uses [Claude Code](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview). The `skills` CLI supports 55+ agents. |\n\nThese docs run `skills` with `dnx`, so there is nothing to install first. If you would rather have `skills` on your `PATH`, install the global tool instead (it needs only the .NET SDK 8.0 or newer). See [Install as a global tool](#install-as-a-global-tool).\n\n# Run `skills`\n\nThese docs run `skills` with `dnx`, which needs no install. You can also install it as a global tool if you prefer `skills` on your `PATH`.\n\n## Run with dnx\n\n`dnx` ships with the .NET 10 SDK and runs a tool straight from NuGet, the way `npx` runs a package from npm. Nothing is installed up front.\n\n```shell\ndnx skills add anthropics/skills --agent claude-code\n```\n\nOn the first run, `dnx` prompts you to confirm the package download before it proceeds:\n\n```text\nTool package skills@<version> will be downloaded from source https://api.nuget.org/v3/index.json.\nProceed? [y/n] (y):\n```\n\nAfter you confirm, the install proceeds and prints the summary shown in [Add your first skill](#add-your-first-skill). The first run downloads the package into your NuGet cache; later runs reuse it and start immediately. `dnx skills` is shorthand for `dotnet tool exec skills`.\n\nTo skip the download prompt (for example in CI), pass `--yes`:\n\n```shell\ndnx --yes skills add anthropics/skills --agent claude-code\n```\n\nYou can control the `skills` version that `dnx` runs and where it fetches it from:\n\n| Command                                      | What it does                        |\n| -------------------------------------------- | ----------------------------------- |\n| `#!shell dnx skills@0.3.0 add ...`           | Runs an exact version.              |\n| `#!shell dnx skills@0.3.* add ...`           | Runs the latest 0.3.x version.      |\n| `#!shell dnx --prerelease skills add ...`    | Allows prerelease versions.         |\n| `#!shell dnx --source <feed> skills add ...` | Fetches from a specific NuGet feed. |\n\nIf your repository has a `.config/dotnet-tools.json` manifest that lists `skills`, `dnx` honors the pinned version from the manifest, which keeps one-shot runs consistent with the version your team committed.\n\n## Install as a global tool\n\nIf you would rather have `skills` on your `PATH`, install it as a global [.NET tool](https://learn.microsoft.com/dotnet/core/tools/global-tools). This needs the .NET SDK 8.0 or newer.\n\n```shell\ndotnet tool install -g skills\n```\n\n```text\nYou can invoke the tool using the following command: skills\nTool 'skills' (version '0.3.0') was successfully installed.\n```\n\nWith the global tool you run `skills` directly: drop the `dnx` prefix from every example in these docs (`dnx skills add ...` becomes `skills add ...`). Confirm the install with `skills --version`, which prints a value like `0.3.0+<git-sha>` (the trailing suffix records the exact commit the build came from).\n\nTo pin `skills` to a version your whole team shares, install it as a local tool through a manifest instead. From the repository root:\n\n```shell\ndotnet new tool-manifest\ndotnet tool install skills\n```\n\nLocal tools are restored with `dotnet tool restore` and run through `dotnet skills`. Check the manifest (`./.config/dotnet-tools.json`) into source control so every collaborator uses the same version.\n\n# Add your first skill\n\nYou are ready to install a skill. The example below installs skills from [anthropics/skills](https://github.com/anthropics/skills), Anthropic's reference repository, targeting Claude Code.\n\n```shell\ndnx skills add anthropics/skills --agent claude-code\n```\n\nAgent names are case-sensitive. Use `claude-code`, not `claude` or `Claude`. For GitHub Copilot the name is `github-copilot`.\n\nThe `skills` CLI fetches the source, discovers the skills, installs them, and prints a summary:\n\n```text\nSource: https://github.com/anthropics/skills.git\nFound 2 skill(s)\n\n┌─Installation Summary─────────────────────────────────────────────────────────┐\n│ Canonical: /your-project/.agents/skills                                      │\n│ Symlinked:  Claude Code                                                      │\n└──────────────────────────────────────────────────────────────────────────────┘\n┌─Installed 2 skill(s)─────────────────────────────────────────────────────────┐\n│ ✓ pdf                                                                        │\n│   → /your-project/.claude/skills/pdf                                         │\n│ ✓ docx                                                                       │\n│   → /your-project/.claude/skills/docx                                        │\n└──────────────────────────────────────────────────────────────────────────────┘\n\nDone!  Review skills before use; they run with full agent permissions.\n```\n\n> The trailing line is a deliberate safety nudge. A skill can include scripts that the agent runs with your agent's full permissions. Install skills only from sources you trust, and read a new skill before you use it.\n\nIf you omit `--agent`, the CLI runs interactively and lets you pick which agents to target from the ones it detects on your machine. To install only specific skills from a multi-skill source, add `--skill <name>` (repeatable). For the full set of source forms, scopes, and flags, see [Installing Skills](./installing-skills.md).\n\n**Checkpoint.** If everything worked, you should see the `Installed 2 skill(s)` panel and the `Done!` line, with no error. If you saw an `Invalid agents` panel, you misspelled the agent name (it is case-sensitive). If you saw `No valid skills found`, the source had no `SKILL.md` with both a `name` and a `description`. See [Troubleshooting](./troubleshooting.md) for more.\n\n# See what is installed\n\nTo confirm what landed in your project, list the installed skills:\n\n```shell\ndnx skills list\n```\n\n```text\nProject Skills\n\nSkill  Path                   Agents\npdf    ./.claude/skills/pdf   Claude Code\ndocx   ./.claude/skills/docx  Claude Code\n```\n\nThe table shows each skill's name, where it lives on disk, and the agents linked to it (shown by their display name, `Claude Code`). To list global skills instead, add `-g`. For machine-readable output, add `--json`.\n\n# Use the skill\n\nThe skill now lives where your agent looks for it. You do not need to do anything else.\n\nYour agent loads each installed skill's `name` and `description` at startup, then reads the full skill only when a task matches the description. This is [progressive disclosure](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview): the description is the trigger, and the body loads on demand. Start a task that matches the skill, and your agent picks it up automatically.\n\n# Update or remove the global tool\n\nIf you run `skills` with `dnx`, you never update it yourself: each run fetches the version you ask for. The commands below apply when you installed the global tool.\n\nTo update the global `skills` tool to the latest version:\n\n```shell\ndotnet tool update -g skills\n```\n\n```text\nTool 'skills' was successfully updated from version '0.3.0' to version '<new>'.\n```\n\nTo uninstall it:\n\n```shell\ndotnet tool uninstall -g skills\n```\n\n```text\nTool 'skills' (version '0.3.0') was successfully uninstalled.\n```\n\nNote that `dotnet tool update` updates the `skills` CLI, not your installed skills. To check your skills for updates, use the `dnx skills update` command, covered in [Installing Skills](./installing-skills.md).\n\n# Next steps\n\n- [Installing Skills](./installing-skills.md): every source form, project versus global scope, picking agents and skills, symlink versus copy, and checking for skill updates.\n- [Authoring Skills](./authoring-skills.md): scaffold a `SKILL.md` with `dnx skills init`, write a good description, and publish your skill.\n- [Reference](./reference.md): the complete command and flag surface.\n","AGENTS.md":"# AGENTS.md\n\nThis file provides guidance to coding agents when working with this repository.\n\n## Attribution\n\n- Do not add `Co-authored-by` trailers or other co-author attribution for agents.\n\n## Pull Requests\n\n- Start a bug fix PR title with `Fix`: `Fix the gateway ignoring subgraph timeouts`. The title becomes the squash commit subject and the release note entry.\n- Area prefixes are optional. Write them in title case (`[Fusion]`, not `[fusion]`), and put `Fix` after one: `[Fusion] Fix the gateway ignoring subgraph timeouts`.\n\n## Build\n\n### Website\n\nUse `npm`.\n\n```bash\ncd website\nnpm ci\n```\n\nnpm 11 before 11.21.1 and npm 12 before 12.2.1 write `allowScripts` entries from `npm install-scripts approve` that npm cannot match under the linked install strategy ([npm/cli#9939](https://github.com/npm/cli/issues/9939)), so on those versions add approvals by hand as `\"<package>@<version>\": true`.\n\n### C# Source Code\n\nBuilds report IDE code-style violations (`IDE*`) as build errors, the same as CI does. Fix every reported style error.\n\nBuild the full solution:\n\n```bash\ndotnet build src/All.slnx\n```\n\nEach area has its own solution file, so you can build or test a subset directly:\n\n```bash\ndotnet test src/HotChocolate/Fusion\n```\n\n## Updating .NET\n\nWhen a change edits `TargetFrameworks` in `src/Directory.Build.props` or the SDK version in `global.json`, work through [docs/updating-dotnet.md](docs/updating-dotnet.md) before handoff.\n\n## Code Quality\n\n### C# / .NET\n\n- Always use curly braces for loops and conditionals, no exceptions.\n- Use file-scoped namespaces and 4-space indentation.\n- Test naming: `Method_Should_Outcome_When_Condition`.\n- No vacuous assertions (`Assert.NotNull` alone is not a test).\n- If a test requires excessive stubs and reflection, you're at the wrong test tier.\n- Do not use em dash style sentences in docs, comments, or XML documentation. Use commas, periods, parentheses, or colons instead.\n- XML docs should describe the contract and concepts, not internals like pooling or iteration mechanics, and should not leak other implementation details.\n- XML docs and comments are 1-2 sentences stating the contract: what it is, what null or edge values mean. No rationale, no use-case examples, no design justification. If a sentence explains why the design is right instead of what the member promises, delete it. The same applies to docs pages: every sentence must inform the reader, none may justify the design.\n- Do not make new parameters optional just to avoid updating call sites. A parameter should only be optional when it has a sensible semantic default and the API is frequently used (where call-site brevity outweighs explicitness). If a parameter is logically required, make it required and update all call sites.\n\n### Testing\n\n- Prefer snapshot tests over manual `Assert` calls, use **CookieCrumble** for snapshots.\n- CookieCrumble has native snapshot support for `IExecutionResult`, `GraphQLHttpResponse`, and other core types.\n- For smaller snapshots, prefer **inline snapshots** (`MatchInlineSnapshot`) over snapshot files.\n- For a collection of results (for example a stream of subscription events), snapshot the list with `MatchInlineSnapshots` (a parallel list of per-element inline snapshots). Do NOT concatenate with `string.Join(\"---\", values).MatchInlineSnapshot(...)`: a manual separator hides element boundaries and reinvents what the collection overload does natively.\n- For tests with multiple assertions, use **Markdown snapshots** (`MatchMarkdownSnapshot`).\n- Hard limit: a single test method must contain at most 5 `Assert.*` calls. Anything beyond that is too hard to reason about in review, switch to a snapshot (Markdown for multi-shape state, inline or file for a single output).\n- Use the AAA section marker style. Each section starts with a single-line comment, the test name documents intent, no paragraph-style block comments above sections:\n\n  ```csharp\n  // arrange\n  // optional one-line description, only when the next code is non-obvious\n  ... arrange code ...\n\n  // act\n  ... act code ...\n\n  // assert\n  ... assert code ...\n  ```\n\n- Avoid `Assert.DoesNotContain` as it is a weak assertion that easily goes out of date, it only proves something is absent without verifying what *is* present. Prefer `Assert.Equal` to check the entire string value, or `Assert.Collection` to verify the complete contents of a collection.\n- Snapshot tests: update from `__mismatch__/` directory, understand ordering issues before updating.\n- Filter tests during iteration, never run the full suite unnecessarily.\n- Use real databases in integration tests, not mocks (unless explicitly instructed otherwise).\n\n## Performance\n\n### C# / .NET\n\nThis is framework code, performance matters. Aim for zero allocations on hot paths.\n\n- Use `ChunkedArrayWriter` or `PooledArrayWriter` when you need an `IBufferWriter<byte>` for in-memory byte writing.\n\n## Tools\n\n### C# / .NET\n\nIf you need to search for packages on nuget.org, use the `dotnet` CLI, e.g. `dotnet package search HotChocolate`.\n\n### Profiling\n\nThe dev container has `dotnet-trace`, `dotnet-counters`, `dotnet-gcdump`, `dotnet-dump`, `dotnet-symbol`, `dottrace` and `dotmemory` installed. Versions are pinned in `.devcontainer/dockerfile`, and `docs/profiling.md` has the full commands and caveats. The tools attach to a running process in the same container. Write outputs to `perf/<label>-<git-short-sha>/`, which is gitignored.\n\n```bash\nOUT=perf/<label>-$(git rev-parse --short HEAD); mkdir -p \"$OUT\"\ndotnet-trace ps\ndotnet-trace collect -p <pid> --duration 00:00:00:30 --format speedscope -o \"$OUT/cpu.nettrace\"\ndotnet-trace report \"$OUT/cpu.nettrace\" topN -n 25 --inclusive\ndotnet-trace collect -p <pid> --profile gc-verbose --duration 00:00:00:15 -o \"$OUT/alloc.nettrace\"\ndotnet-gcdump collect -p <pid> -o \"$OUT/heap.gcdump\" && dotnet-gcdump report \"$OUT/heap.gcdump\" > \"$OUT/heap-report.txt\"\ndotnet-counters collect -p <pid> --format json -o \"$OUT/counters.json\" --duration 00:00:00:20 --counters System.Runtime,Microsoft.AspNetCore.Hosting,System.Net.Http\n```\n\n- Profile Release builds. Debug builds distort time and allocations.\n- Sampling gives time, not call counts. Call counts need dotTrace Tracing mode, which only `dottrace start` offers; `dottrace attach` is limited to Sampling and Timeline.\n- On Linux, EventPipe samples measure thread time. Ignore idle thread pool frames such as `LowLevelLifoSemaphore.WaitForSignal` and `WaitHandle.WaitOneNoCheck`.\n- `.dtp` (dotTrace) and `.dmw` (dotMemory) snapshots are for Rider on the host. Use the `dotnet-trace` and `dotnet-gcdump` outputs for analysis inside the container.\n\n### Nitro persisted operations (Fusion Aspire)\n\nAfter adding or editing any `.graphql` document under `src/HotChocolate/Fusion/src/Fusion.Aspire/Nitro/Operations`, regenerate the `.sha256` sidecars and verify them:\n\n```bash\n.github/scripts/nitro-aspire-operations.sh update \\\n    --source src/HotChocolate/Fusion/src/Fusion.Aspire/Nitro/Operations\n.github/scripts/nitro-aspire-operations.sh verify \\\n    --source src/HotChocolate/Fusion/src/Fusion.Aspire/Nitro/Operations \\\n    --output /tmp/nitro-aspire-operations.json\n```\n\nNever hand-write or hand-edit a `.sha256` sidecar. The `update` command is the only source of sidecar content, and `verify` must pass before handoff.\n\n## Components\n\n### All components\n\n#### Exceptions\n\nCreate exceptions through the `ThrowHelper` class of the project you are editing instead of inlining `throw new ...`. Each project keeps its own, which centralizes exception messages.\nExample: `src/HotChocolate/Fusion/src/Fusion.Execution/Execution/ThrowHelper.cs`\n\n#### GraphQL errors\n\nCreate GraphQL errors through the `ErrorHelper` class of the project you are editing instead of inlining `ErrorBuilder` calls. Each project keeps its own, which centralizes error messages.\nExample: `src/HotChocolate/AspNetCore/src/AspNetCore.Pipeline/Utilities/ErrorHelper.cs`\n\n### src/Fusion\n\n#### Execution nodes\n\nWhen you add a value to `ExecutionNodeType`, map it in two places:\n\n- `ExecutePlanNodeSpan.KindValues` in `src/HotChocolate/Fusion/src/Fusion.Diagnostics/Spans/ExecutePlanNodeSpan.cs`\n- `GraphQL.Operation.Step.KindValues` in `src/HotChocolate/Diagnostics/src/Diagnostics.Core/SemanticConventions.cs`, if the kind needs a new constant. Tag values are snake_case.\n\n`KindValues` supplies the `graphql.operation.step.kind` tag on the step span. An unmapped type does not fail execution. `ExecutePlanNodeSpan.Start` falls back to an untagged span, so the node silently loses its kind in traces. The guard test `StepSpan_Should_MapEveryExecutionNodeTypeToAKindValue` in `src/HotChocolate/Fusion/test/Fusion.Diagnostics.Tests/FusionActivityExecutionDiagnosticListenerTests.cs` fails until the mapping exists.\n\n#### Operation planner version\n\n`OperationPlanner.Version` identifies planning behavior and is independent of the package version. Bump the minor version when an existing operation can plan differently, the major version when consumers must react to a new plan structure. Refactors, performance work and fixes that cannot change a plan do not bump it.\n\n#### Operation plan JSON format\n\n`JsonOperationPlanFormatter` in `src/HotChocolate/Fusion/src/Fusion.Execution/Execution/Nodes/Serialization/JsonOperationPlanFormatter.cs` writes the plan document that tooling consumes. Its shape is published as a JSON schema, so any change to the emitted JSON is a two part change:\n\n1. Bump `JsonOperationPlanFormatter.FormatVersion`. It is written as the root `version` property and is the discriminator consumers pin against. Additive optional properties bump the minor version, anything that changes or removes an existing property bumps the major version.\n2. Add the matching variant to `website/public/schemas/fusion/operation-plan.json`, published at `https://chillicream.com/schemas/fusion/operation-plan.json`. Add a `#/$defs/<version>_plan` entry and the `allOf` branch that selects it for that root `version`, and list the new version in the root `version` enum. Every other definition is unprefixed and shared across versions. When a version changes one of them, fork only that definition to `<version>_<name>` and point the new plan at the fork, so a released version keeps validating exactly what it validated before.\n\nThe root `version` enum and the `allOf` branch that selects `v1_0_0_plan` are the pattern to copy: a new version adds one enum entry, one branch and one plan definition.\n\nThe internal `Format(IBufferWriter<byte>, Operation, ImmutableArray<ExecutionNode>)` overload feeds the SHA-256 that becomes `OperationPlan.Id`. It deliberately omits the `version` property, so leave it alone unless you intend to change every plan id.\n","website/content/docs/skills/authoring-skills.md":"---\ntitle: \"Authoring Skills\"\ndescription: \"Author Agent Skills with the `skills` CLI: scaffold a folder with `dnx skills init`, write the SKILL.md frontmatter and instructions, and publish through git.\"\n---\n\nPackage your team's conventions once, and any agent can pick them up. A skill is a folder with a `SKILL.md` file that tells an agent how to do something the way your team does it: your release checklist, your code review rules, your API client patterns. You write it once, push it to a git repo, and your teammates install it with one command. From then on, every agent they run loads that knowledge on demand, no copy-pasting prompts into each session.\n\nThis page teaches you to scaffold a skill, write a correct `SKILL.md`, add supporting files, and publish it so others can install it with [`dnx skills add`](./installing-skills.md). The skill format is the open [Agent Skills](https://agentskills.io/home) standard, so what you write here works across [55+ agents](./index.md), not only the one you author it in.\n\n# Scaffold a skill\n\n> Prerequisite: the .NET 10 SDK. See [Getting Started](./getting-started.md) before running the commands below.\n\nTo create a new skill in its own folder, run `dnx skills init` with a name.\n\n```shell\ndnx skills init my-skill\n```\n\n```text\nInitialized skill: my-skill\n\nCreated:\n  my-skill/SKILL.md\n\nNext steps:\n  1. Edit my-skill/SKILL.md to define your skill instructions\n  2. Update the name and description in the frontmatter\n\nPublishing:\n  GitHub: Push to a repo, then skills add <owner>/<repo>\n  URL:    Host the file, then skills add https://example.com/my-skill/SKILL.md\n```\n\nThis creates `my-skill/SKILL.md`. If everything worked, you have a folder named `my-skill` with one file inside it.\n\nTo scaffold a skill in the current directory instead, run `dnx skills init` with no name. The CLI derives the skill name from the folder you are in and writes `SKILL.md` next to your other files.\n\n```shell\ndnx skills init\n```\n\n```text\nInitialized skill: my-skill\n\nCreated:\n  SKILL.md\n\nNext steps:\n  1. Edit SKILL.md to define your skill instructions\n  2. Update the name and description in the frontmatter\n\nPublishing:\n  GitHub: Push to a repo, then skills add <owner>/<repo>\n  URL:    Host the file, then skills add https://example.com/my-skill/SKILL.md\n```\n\n`dnx skills init` never overwrites an existing skill. If `SKILL.md` is already present, it leaves your file untouched and tells you so.\n\n```text\nSkill already exists at my-skill/SKILL.md\n```\n\n## The generated template\n\n`dnx skills init` writes a spec-compliant starting point: the two required frontmatter fields, then a body with a heading and the sections most skills need.\n\n```markdown\n---\nname: my-skill\ndescription: A brief description of what this skill does\n---\n\n# my-skill\n\nInstructions for the agent to follow when this skill is activated.\n\n## When to use\n\nDescribe when this skill should be used.\n\n## Instructions\n\n1. First step\n2. Second step\n3. Additional steps as needed\n```\n\nReplace the placeholder `description`, then fill in the body. The next sections explain each part.\n\n# Structure a SKILL.md\n\nA `SKILL.md` has two parts: YAML frontmatter between `---` fences, and a Markdown body below it. The frontmatter is metadata the agent reads to decide whether your skill is relevant. The body is the instructions the agent follows once it decides to use the skill.\n\nThe \"Required frontmatter\" and \"Optional frontmatter\" subsections below are reference material: field-by-field constraint tables you can scan when you fill in the frontmatter. For the complete, authoritative field list see the [Reference](./reference.md).\n\n## Required frontmatter\n\nEvery skill needs `name` and `description`. The CLI skips any skill that is missing either field, so getting these right is the difference between a skill that installs and one that silently disappears.\n\n| Field         | Constraints                                                                                                                                                                                                                                               |\n| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `name`        | 1 to 64 characters. Lowercase letters, digits, and hyphens only. No leading or trailing hyphen. No consecutive hyphens. Should match the skill's folder name. Must not contain XML tags, and must not contain the reserved words `anthropic` or `claude`. |\n| `description` | 1 to 1024 characters. Must say BOTH what the skill does AND when to use it. Include specific trigger keywords that match the tasks where the skill applies. Must not contain XML tags.                                                                    |\n\nThe `description` is the single most important field you write. At startup the agent loads only your `name` and `description` (not the body), then matches the user's request against that description to decide whether to read the rest. A vague description means the agent never triggers your skill. Front-load what the skill does, then state the conditions that should activate it, and name the tools, file types, or commands involved.\n\n```markdown\n---\nname: release-checklist\ndescription: Runs our release checklist before publishing a NuGet package. Use when cutting a release, bumping a version, or preparing a package for nuget.org.\n---\n```\n\nThese constraints are the union of two authorities: the open spec at [agentskills.io/specification](https://agentskills.io/specification) (which adds the \"match the folder name\" and \"no consecutive hyphens\" rules) and the [Anthropic platform rules](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) (which add the reserved-word and XML-tag prohibitions). Honoring both keeps your skill portable across every agent.\n\n## Optional frontmatter\n\nAdd these fields only when you need them. The open spec at [agentskills.io/specification](https://agentskills.io/specification) is the authoritative field list; the most useful fields are below.\n\n| Field           | Purpose                                                                                                                                                                     |\n| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `license`       | A license name or a reference to a bundled license file. Keep it short.                                                                                                     |\n| `compatibility` | Up to 500 characters describing environment needs (intended product, system packages, network access). Most skills do not need it. Example: `Requires git, docker, and jq`. |\n| `metadata`      | A string-to-string map for client-defined properties the spec does not cover, such as `author` or `version`. Use distinctive key names to avoid collisions.                 |\n| `allowed-tools` | A space-separated list of pre-approved tools, for example `Bash(git:*) Read`.                                                                                               |\n\nFor the exhaustive list of frontmatter fields and their constraints, see the [Reference](./reference.md).\n\n> [!WARNING]\n> **`allowed-tools` is experimental.** Support varies between agents, and `dnx skills init` does not emit it. Treat it as a hint that some agents honor and others ignore, not a security boundary.\n\n## The instructions body\n\nThe body is plain Markdown the agent follows when your skill activates. There are no format restrictions, so write it the way you would brief a new teammate: step-by-step instructions, input and output examples, and the edge cases people get wrong.\n\nKeep `SKILL.md` focused. The recommendation from both [Anthropic](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) and the open spec is to keep the body under roughly 500 lines and move long detail into supporting files (see the next section). A tight body loads fast and keeps the agent on the steps that matter.\n\n# Add supporting files\n\nA skill folder can hold more than `SKILL.md`. Three conventional subdirectories cover most needs.\n\n```text\nmy-skill/\n├── SKILL.md          # Required: frontmatter + instructions\n├── references/       # Docs loaded on demand (REFERENCE.md, API.md, ...)\n├── scripts/          # Code the agent runs\n└── assets/           # Templates, data files, schemas\n```\n\nThe CLI copies or symlinks the whole folder as a unit, so every supporting file ships with the skill. (A few build artifacts are excluded automatically, including `.git`, `node_modules`, and `__pycache__`.)\n\nThese directories exist because of [progressive disclosure](./index.md#how-skills-load-progressive-disclosure): the agent loads your skill in stages so a large skill costs almost nothing until it is needed.\n\n- At startup the agent loads only `name` and `description`.\n- When the skill triggers, the agent reads the `SKILL.md` body.\n- A file under `references/`, `scripts/`, or `assets/` loads only when the body points the agent at it.\n\nThis is why moving detail out of `SKILL.md` and into `references/` is free: that material never enters the context window until the agent actually follows a link to it. Reference your supporting files with relative paths one level deep (for example `references/api.md`), and avoid deep nesting chains. For more on the three-stage model, see the [Introduction](./index.md#how-skills-load-progressive-disclosure) and [Anthropic's overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).\n\n# How installed skills are named\n\nWhen someone installs your skill, the CLI derives the on-disk directory name by sanitizing the `name` field. It lowercases the name, replaces every run of characters outside `a-z`, `0-9`, `.`, and `_` with a single hyphen, and trims leading and trailing dots and hyphens.\n\nFor a clean lowercase-hyphen name like `release-checklist`, the on-disk name is identical, with no surprises. A name with spaces or uppercase letters gets rewritten (`My Skill` becomes `my-skill`), which can mismatch what you and your teammates expect on disk and during removal. Pick a clean lowercase-hyphen name that already satisfies the [required frontmatter rules](#required-frontmatter), and the install name matches your folder name exactly.\n\n# Publish and install\n\nA skill is a folder in a git repo, so publishing is committing and pushing. Any repository the CLI can reach with git works.\n\nTo publish, commit your skill folder and push it to GitHub, GitLab, or any git remote. Then anyone installs it with `dnx skills add` pointed at the repo. The forms below show what an installer runs against your published skill; for the full add workflow, including expected output, scoping, and agent targeting, see [Installing Skills](./installing-skills.md).\n\n```shell\n# install every skill in the repo\ndnx skills add my-org/my-skills\n\n# install only one skill from a multi-skill repo\ndnx skills add my-org/my-skills@release-checklist\n\n# install a single SKILL.md hosted at a URL\ndnx skills add https://example.com/my-skill/SKILL.md\n```\n\nPrivate repositories work with no extra configuration. The CLI shells out to your own `git`, so it uses your existing credentials (SSH agent keys, a git credential helper, or `gh auth`). If you can `git clone` the repo, `skills` can install from it. When authentication fails, see [Troubleshooting](./troubleshooting.md).\n\nTo keep a work-in-progress skill out of default discovery, set `metadata.internal` to `true` in the frontmatter. The CLI hides internal skills unless the installer explicitly opts in (by filtering for the skill by name, or by setting the `INSTALL_INTERNAL_SKILLS` environment variable).\n\n```markdown\n---\nname: experimental-skill\ndescription: An in-progress skill. Use when testing new conventions before rollout.\nmetadata:\n  internal: \"true\"\n---\n```\n\n# Validate a skill\n\nTo check a skill against the open spec before you publish, use the reference validator `skills-ref` from the [agentskills/agentskills](https://github.com/agentskills/agentskills) repository. It validates your frontmatter and naming conventions.\n\n```shell\nskills-ref validate ./my-skill\n```\n\nIt reports a clean pass when the skill is valid, or names the offending field and rule when it is not (for example, an empty `description` or a `name` that breaks the naming rules).\n\nRunning it after `dnx skills init` and again before you push catches a malformed `name` or an empty `description` while it is still fast to fix, rather than discovering that the CLI skipped your skill on install.\n\n# Next steps\n\n- [Installing Skills](./installing-skills.md): install your published skill, target specific agents, and choose project or global scope.\n- [Reference](./reference.md): the complete command and flag surface, including `dnx skills init`.\n",".vscode/mcp.json":"{\n  \"servers\": {\n    \"microsoft.docs.mcp\": {\n      \"type\": \"http\",\n      \"url\": \"https://learn.microsoft.com/api/mcp\"\n    },\n    \"nuget\": {\n      \"type\": \"stdio\",\n      \"command\": \"dotnet\",\n      \"args\": [\n        \"dnx\",\n        \"NuGet.Mcp.Server\",\n        \"--source\",\n        \"https://api.nuget.org/v3/index.json\",\n        \"--yes\"\n      ]\n    },\n    \"lighthouse\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@danielsogl/lighthouse-mcp@latest\"]\n    },\n    \"playwright\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@playwright/mcp@latest\"]\n    },\n  }\n}\n","website/content/docs/skills/index.md":"---\ntitle: Skills\nmetaTitle: \"Skills: Agent Skills CLI for .NET\"\ndescription: \"The `skills` .NET CLI installs, updates, and authors Agent Skills: portable SKILL.md files you can share across Claude Code, Cursor, and 55+ agents.\"\n---\n\n`skills` is the .NET CLI that installs, updates, and authors [Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills): portable `SKILL.md` files that teach an AI coding agent how you work. Stop re-explaining your conventions every session. Package the knowledge once, then hand the same skill to Claude Code, Cursor, GitHub Copilot, or another of the 55+ supported agents with a single command.\n\nRun it with `dnx`, which ships with the .NET 10 SDK, so there is nothing to install first:\n\n```shell\ndnx skills add anthropics/skills --agent claude-code\n```\n\n```text\nSource: https://github.com/anthropics/skills.git\nFound 2 skill(s)\n\n┌─Installation Summary─────────────────────────────────────────────────────────┐\n│ Canonical: /your-project/.agents/skills                                      │\n│ Symlinked:  Claude Code                                                      │\n└──────────────────────────────────────────────────────────────────────────────┘\n┌─Installed 2 skill(s)─────────────────────────────────────────────────────────┐\n│ ✓ pdf                                                                        │\n│   → /your-project/.claude/skills/pdf                                         │\n│ ✓ docx                                                                       │\n│   → /your-project/.claude/skills/docx                                        │\n└──────────────────────────────────────────────────────────────────────────────┘\n\nDone!  Review skills before use; they run with full agent permissions.\n```\n\nThe CLI detects the agents you have installed, then symlinks the skill into each one from a single canonical store. The agent loads the skill on its own when a task matches.\n\nThese docs show every command as `dnx skills`. Prefer `skills` on your `PATH`? Install the global tool with `#!shell dotnet tool install -g skills`, then drop the `dnx` prefix and run `skills` directly.\n\nNeed the prerequisites or a step-by-step walkthrough? See [Get started](./getting-started.md). The [source repository](https://github.com/ChilliCream/skills) and [`skills` package on NuGet](https://www.nuget.org/packages/skills) are public.\n\n# What are Agent Skills\n\nA skill is a folder with a single `SKILL.md` file. That file has YAML frontmatter (a `name` and a `description`) followed by a Markdown body of instructions. Optional subfolders carry supporting material the agent reads only when it needs it.\n\nThink of a skill as an onboarding guide for a new team member. You write down a procedure once (how to run your test suite, how your commit messages are formatted, which API your team prefers), and the agent references the relevant section when a task calls for it. A general-purpose agent becomes a specialist in your codebase without bespoke prompt engineering on every request.\n\nSkills differ from prompts. A prompt is conversation-level guidance you paste in for one task. A skill loads on demand across every conversation, so you never repaste the same instructions again.\n\nThe `SKILL.md` format is an open standard created by Anthropic and adopted across the ecosystem. The same file works in 55+ supported agents, including Claude Code, Cursor, and GitHub Copilot. To go deeper, read Anthropic's [Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) and the [open specification](https://agentskills.io/specification) at agentskills.io.\n\n# How skills load: progressive disclosure\n\nSkills stay out of the agent's context window until they are needed. The format loads in three levels, each at a different time. This is the single most important idea to understand, because it is why you can install many skills without paying a context penalty.\n\n| Level                 | What loads                                            | When                                    | Token cost            |\n| --------------------- | ----------------------------------------------------- | --------------------------------------- | --------------------- |\n| Level 1: Metadata     | The `name` and `description` from the frontmatter     | Always, at startup                      | ~100 tokens per skill |\n| Level 2: Instructions | The `SKILL.md` Markdown body                          | When the skill is triggered             | Keep under ~5k tokens |\n| Level 3: Resources    | Bundled files in `references/`, `scripts/`, `assets/` | On demand, when the body points to them | Effectively unlimited |\n\nAt startup the agent loads only each skill's `name` and `description`. The `description` is what the agent matches against your request to decide whether to activate the skill, so write it to describe both what the skill does and when to use it. When a request matches, the agent reads the full body. Bundled resources never enter context until the body references them, which is why supporting material can be effectively unbounded.\n\nThe open standard frames the same flow as Discovery, Activation, and Execution. For the full model, see Anthropic's [overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) and the [agentskills.io home page](https://agentskills.io/home).\n\n# What a skill looks like\n\nA skill is, at minimum, a folder containing one `SKILL.md` file. Everything else is optional and loaded only when referenced:\n\n```text\nmy-skill/\n├── SKILL.md       # Required: frontmatter (name + description) + Markdown instructions\n├── references/    # Optional: extra docs the agent reads on demand\n├── scripts/       # Optional: code the agent runs via the shell\n└── assets/        # Optional: templates, schemas, images, data files\n```\n\nThe folder name should match the `name` in the frontmatter. Here is a minimal, valid `SKILL.md` with the two required fields:\n\n```markdown\n---\nname: roll-dice\ndescription: Rolls one or more dice and returns the results. Use when the user asks to roll dice, flip for a decision, or pick a random number in a range.\n---\n\n# Roll dice\n\nWhen the user asks to roll dice, parse the count and number of sides (default to one six-sided die),\nthen return each roll and the total.\n```\n\nThe `dnx skills init` command scaffolds this layout for you; [Authoring Skills](./authoring-skills.md) walks through it with the generated `SKILL.md` and folder tree. The full field reference, including optional frontmatter, lives in the [open specification](https://agentskills.io/specification) and in [Authoring Skills](./authoring-skills.md).\n\n# Why Skills\n\nThe `skills` CLI brings the install-once, run-anywhere skill workflow to the .NET SDK. Three things make it worth adding to your toolbox.\n\nProject-scoped installs are recorded in a `skills-lock.json` file in your working directory. Commit it, and your whole team shares one reproducible skill set, the same way a lock file pins your package dependencies.\n\nOne install reaches every detected agent. The CLI materializes each skill once in a canonical store, then links it into the directory each installed agent expects. You do not manage per-agent copies by hand.\n\nPersonal skills install globally with `--global`. Those live outside any single project and follow you across every repository you work in.\n\n# The ecosystem\n\nThe Agent Skills world has three distinct layers. Knowing which is which helps you find what you need.\n\n| Layer         | What it is                                | Where                                                                                                             |\n| ------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| Format / spec | The open `SKILL.md` standard              | [agentskills.io](https://agentskills.io/specification), [anthropics/skills](https://github.com/anthropics/skills) |\n| Discovery     | A directory of published skills to browse | [skills.sh](https://www.skills.sh/)                                                                               |\n| Installers    | CLIs that fetch and install skills        | `skills` (.NET), [npx skills](https://github.com/vercel-labs/skills) (Node)                                       |\n\nThe `skills` CLI brings the [npx skills](https://github.com/vercel-labs/skills) workflow to the .NET SDK via `dnx`, so you can run it without a global install. The command surface deliberately mirrors what Node developers already know. The CLI has no registry of its own: you point `dnx skills add` at any git repository or local folder, and you discover skills to install from directories like [skills.sh](https://www.skills.sh/).\n\n# Next steps\n\n- [Get started](./getting-started.md): run `skills` and add your first skill end to end.\n- [Author a skill](./authoring-skills.md): scaffold a `SKILL.md`, write a strong description, and publish it.\n","website/content/docs/skills/installing-skills.md":"---\ntitle: \"Installing Skills\"\ndescription: \"Install Agent Skills from GitHub repos, git URLs, or local folders with `dnx skills add`: the CLI finds every SKILL.md and wires it into your agents.\"\n---\n\n`dnx skills add` installs skills from a source into the AI coding agents you already have. Point it at a GitHub repository and the CLI discovers every `SKILL.md`, detects your agents, and wires the skill into each one.\n\n```shell\ndnx skills add anthropics/skills\n```\n\nThat single command fetches [Anthropic's reference skills](https://github.com/anthropics/skills), then either prompts you to choose which skills and agents you want or, when it is running inside an agent, installs non-interactively. This page walks the full lifecycle: choosing a source, narrowing to specific skills and agents, picking a scope, keeping skills current, and removing them.\n\nIf you have not installed the CLI yet, start with [Getting Started](./getting-started.md).\n\n> [!WARNING]\n> **Skills run with your agent's full permissions.** A skill is executable instructions plus optional scripts that your agent runs on your machine. Install only from sources you trust, and review a skill before you use it. After every successful install, `skills` reminds you: `Review skills before use; they run with full agent permissions.`\n\n# Choose a source\n\nThe `source` argument tells the CLI where to fetch skills from. It infers the kind of source from the string, so you pass one positional value and nothing else.\n\nThe most common form is a GitHub `owner/repo` shorthand:\n\n```shell\ndnx skills add anthropics/skills\n```\n\nEvery source form below is accepted. The first matching rule wins, and clones are always shallow (the CLI fetches only the latest commit, not the full history).\n\n| Source form            | Example                                                                      | What it does                                                              |\n| ---------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------- |\n| GitHub `owner/repo`    | `#!shell dnx skills add anthropics/skills`                                   | Installs from the repository root. The default shorthand.                 |\n| GitHub subpath         | `#!shell dnx skills add anthropics/skills/document-skills/pdf`               | Installs only the skill at that path in the repo.                         |\n| GitHub branch or tag   | `#!shell dnx skills add owner/repo#main`                                     | Installs from a specific ref (`#branch` or `#tag`).                       |\n| GitHub skill filter    | `#!shell dnx skills add owner/repo@my-skill`                                 | Installs only the skill named `my-skill` from the repo.                   |\n| GitHub URL             | `#!shell dnx skills add https://github.com/owner/repo`                       | Full URL, with or without a trailing `.git`.                              |\n| GitHub `tree` URL      | `#!shell dnx skills add https://github.com/owner/repo/tree/main/skills/foo`  | A `/tree/<ref>/<path>` URL pins the ref and subpath.                      |\n| GitLab shorthand       | `#!shell dnx skills add gitlab:group/project`                                | Installs from GitLab. Subgroups are supported (`group/subgroup/project`). |\n| GitLab URL             | `#!shell dnx skills add https://gitlab.com/group/project/-/tree/main/skills` | GitLab uses `/-/tree/` (note the `-` segment).                            |\n| Generic git or SSH     | `#!shell dnx skills add git@github.com:owner/repo.git`                       | Any `https`, `ssh://`, `git://`, or scp-style git transport.              |\n| Local directory        | `#!shell dnx skills add ./my-skills`                                         | A local path: `./`, `../`, an absolute path, or a Windows drive path.     |\n| Well-known HTTP(S) URL | `#!shell dnx skills add https://example.com/skills`                          | A non-git site that serves skills via `.well-known` discovery.            |\n\nA few notes that save time:\n\n- A bare name like `my-skills` (no `./` prefix) is treated as `owner/repo` shorthand, not a local path. Use `./my-skills` when you mean a local directory.\n- You can combine a ref and a skill filter: `owner/repo#main@my-skill`.\n- Any credentials embedded in a URL are stripped before they appear in output or in the lock file. The `Source:` line that the CLI prints shows `https://<redacted>@host/...`.\n\n> A well-known HTTP source fetches a `.well-known/agent-skills/index.json` (or `.well-known/skills/index.json`) discovery document from the site and downloads the listed skills. Every fetch is pinned to the same origin as the index, and indexes verify a SHA-256 digest per skill.\n\n# Choose which skills to install\n\nA source can contain many skills. By default, when you do not pass any filter, the CLI lists what it found and lets you select interactively. To narrow the set up front, use the options below.\n\nTo preview the available skills without installing anything, pass `--list` (or `-l`):\n\n```shell\ndnx skills add anthropics/skills --list\n```\n\n```text\nSource: https://github.com/anthropics/skills.git\nFound 2 skill(s)\n\nAvailable Skills\n  pdf\n    the pdf skill\n  docx\n    the docx skill\n\nUse --skill <name> to install specific skills\n```\n\nTo install one or more specific skills by name, pass `--skill` (or `-s`). The option is repeatable:\n\n```shell\ndnx skills add anthropics/skills --skill pdf --skill docx\n```\n\nYou can also embed a single skill filter in the source string with `@name`:\n\n```shell\ndnx skills add anthropics/skills@pdf\n```\n\nTo install every skill from the source into every detected agent, non-interactively, pass `--all`:\n\n```shell\ndnx skills add anthropics/skills --all\n```\n\nA successful run prints the `Installation Summary` and `Installed N skill(s)` panels followed by the safety reminder, the same shape shown under [How skills reach each agent](#how-skills-reach-each-agent).\n\n`--all` is a shortcut: it selects all skills, targets all agents, and skips every prompt.\n\nIf a `--skill` filter matches nothing, the CLI lists what was available so you can correct the name, and exits with a non-zero code:\n\n```text\nSource: /home/you/my-skills\nFound 2 skill(s)\nNo matching skills found for: nope\nAvailable skills:\n  alpha\n  beta\n```\n\nA skill is any folder that contains a `SKILL.md` with both a `name` and a `description`. If the source contains no valid skills, the CLI reports `No valid skills found. Skills require a SKILL.md with name and description.` and exits non-zero. See [Authoring Skills](./authoring-skills.md) for the format.\n\n# Choose which agents\n\nBy default, the CLI detects which agents are installed on your machine and targets them. To choose explicitly, pass `--agent` (or `-a`). The option is repeatable and accepts multiple values per token, and `*` means every supported agent:\n\n```shell\n# repeated flags\ndnx skills add anthropics/skills --agent claude-code --agent cursor\n\n# space-separated values in one token\ndnx skills add anthropics/skills --agent claude-code cursor\n\n# every supported agent\ndnx skills add anthropics/skills --agent \"*\"\n```\n\nA valid `--agent` run prints the `Installation Summary` and `Installed N skill(s)` panels shown under [How skills reach each agent](#how-skills-reach-each-agent), naming each agent that was linked or copied.\n\nThe CLI resolves the target agents like this:\n\n- **Running inside an agent.** When the CLI runs inside an agent (for example, when your agent invokes it for you), it goes non-interactive and targets that agent plus the shared store.\n- **Run from your shell, one agent installed.** The CLI auto-selects that agent plus the shared store.\n- **Run from your shell, several agents installed.** The CLI prompts you to choose, pre-selecting your last-used agents (or the common defaults `claude-code`, `codex`, `opencode` on a first run).\n- **`--agent` passed.** The CLI uses exactly what you specify, after validation.\n\nThese are the headline agent identifiers. Names are case-sensitive.\n\n| Agent          | `--agent` identifier |\n| -------------- | -------------------- |\n| Claude Code    | `claude-code`        |\n| Cursor         | `cursor`             |\n| GitHub Copilot | `github-copilot`     |\n| Codex          | `codex`              |\n| Continue       | `continue`           |\n| Gemini CLI     | `gemini-cli`         |\n| Windsurf       | `windsurf`           |\n\nThe `skills` CLI supports 55+ agents. For the complete list, plus the exact directory each agent installs into, see the [Reference](./reference.md).\n\nBecause identifiers are case-sensitive, `copilot` and `Claude-Code` are not valid. An invalid value fails fast and lists every valid name so you can copy the right one:\n\n```text\n┌─Invalid agents───────────────────────────────────────────────────────────────┐\n│ Invalid agents: bogus                                                        │\n│                                                                              │\n│ Valid agents: adal, aider-desk, amp, antigravity, augment, bob, claude-code, │\n│ cline, codearts-agent, codebuddy, codemaker, codestudio, codex,              │\n│ command-code, continue, cortex, crush, cursor, deepagents, devin, dexto,     │\n│ droid, firebender, forgecode, gemini-cli, github-copilot, goose,             │\n│ hermes-agent, iflow-cli, junie, kilo, kimi-cli, kiro-cli, kode, mcpjam,      │\n│ mistral-vibe, mux, neovate, openclaw, opencode, openhands, pi, pochi, qoder, │\n│ qwen-code, replit, roo, rovodev, tabnine-cli, trae, trae-cn, universal,      │\n│ warp, windsurf, zencoder                                                     │\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\n# Project and global scope\n\nThe CLI installs into one of two scopes. Understanding the difference tells you where skills live and who shares them.\n\n**Project scope is the default.** The CLI records the installed skills in a `skills-lock.json` file in your working directory and materializes the skill folders under `./.agents/skills`. Commit `skills-lock.json` so everyone who clones the repository shares the same skill set. This is the right scope for skills your whole team should use on a given project.\n\n**Global scope (`--global` or `-g`) installs skills for your user account**, across every project.\n\n```shell\ndnx skills add anthropics/skills --global\n```\n\nIn global scope the lock file lives at `~/.local/share/skills/.skill-lock.json` (honoring `XDG_DATA_HOME` if you set it), and the skill folders are materialized under `~/.agents/skills`.\n\nIn both scopes, the CLI materializes each skill once in a canonical store, then makes each targeted agent point at it.\n\n# How skills reach each agent\n\nBy default, the CLI writes each skill once into the canonical store and creates a symlink from every targeted agent's directory back to it. Editing the one canonical copy updates the skill for every agent at once, so you maintain a single source of truth.\n\n```mermaid\nflowchart LR\n  S[\"Source (repo, URL, or local path)\"] --> C[\"Canonical store (.agents/skills)\"]\n  C -. \"symlink\" .-> A1[\".claude/skills\"]\n  C -. \"symlink\" .-> A2[\".windsurf/skills\"]\n  C --> A3[\"Universal agents (.agents/skills is the store)\"]\n```\n\nSome agents read directly from the shared `.agents/skills` store, so their skills directory _is_ that store and no symlink is needed. The [Reference](./reference.md) lists which agents read from the shared store and the directory each agent installs into.\n\nTo copy files instead of symlinking, pass `--copy`. Use it for sandboxed agents that cannot follow symlinks (for example, agents running in containers where symlinks across mounts break):\n\n```shell\ndnx skills add anthropics/skills --copy --agent claude-code --agent windsurf\n```\n\nThe CLI also copies automatically in two cases, so you rarely need `--copy` by hand:\n\n- When a symlink cannot be created (for example, on Windows without the symlink privilege), the CLI falls back to copying for that agent.\n- When every targeted agent shares one skills directory, the CLI copies, because symlinking only makes sense across distinct directories.\n\nA successful install reports which agents were linked or copied and where each skill landed:\n\n```text\nSource: https://github.com/owner/skills.git\nFound 1 skill(s)\n\n┌─Installation Summary─────────────────────────────────────────────────────────┐\n│ Canonical: /your-project/.agents/skills/alpha                                │\n│ Symlinked:  Claude Code, Windsurf                                            │\n└──────────────────────────────────────────────────────────────────────────────┘\n┌─Installed 1 skill(s)─────────────────────────────────────────────────────────┐\n│ ✓ alpha                                                                      │\n│   → /your-project/.claude/skills/alpha                                       │\n└──────────────────────────────────────────────────────────────────────────────┘\n\nDone!  Review skills before use; they run with full agent permissions.\n```\n\nIf everything worked, you should see the `Installation Summary` panel followed by an `Installed N skill(s)` panel and the safety reminder. To confirm later, run `dnx skills list` (see the [Reference](./reference.md)).\n\n# Scan nested skills with --full-depth\n\nBy default, the CLI installs the skill at the source root if one exists there. If the root is not itself a skill, it discovers every nested skill instead. That fast path covers most repositories.\n\nTo find skills in nested and curated directories that the default scan does not reach, pass `--full-depth`:\n\n```shell\ndnx skills add owner/curated-skills --full-depth\n```\n\nThe install reports the same `Installation Summary` and `Installed N skill(s)` panels shown under [How skills reach each agent](#how-skills-reach-each-agent); only the set of discovered skills differs.\n\n`--full-depth` widens _discovery_: it scans nested directories and curated locations (such as `skills/.curated`) so the CLI finds skills the default scan would skip. It does not change clone depth. Clones are always shallow regardless of this flag.\n\n# Install from a private repository\n\nThe CLI never manages or prompts for credentials. It shells out to `git`, which uses your own setup: SSH agent keys, a git credential helper, `gh` authentication, or `~/.netrc`. To avoid hanging on a missing credential, it sets `GIT_TERMINAL_PROMPT=0`, so an unauthenticated clone fails fast with a clear error instead of waiting at a prompt.\n\nTo install from a private repository, make sure your normal git auth already works, then run `add` as usual:\n\n```shell\ndnx skills add owner/private-skills --agent claude-code\n```\n\nThis prints the same `Installation Summary` and `Installed N skill(s)` panels shown under [How skills reach each agent](#how-skills-reach-each-agent), once the clone authenticates.\n\nBefore you install, verify your access with one of:\n\n```shell\nssh -T git@github.com   # confirm your SSH key reaches GitHub\ngh auth login           # or authenticate the GitHub CLI\n```\n\nA working SSH key prints the well-known success line (GitHub closes the connection because it does not provide shell access):\n\n```text\nHi <user>! You've successfully authenticated, but GitHub does not provide shell access.\n```\n\nIf a clone fails with an authentication error, the CLI prints guidance pointing you back to your git credentials. See [Troubleshooting](./troubleshooting.md) for the full list of clone and auth failures.\n\n# Keep skills up to date\n\n`dnx skills update` checks your installed skills for newer versions. It has the aliases `upgrade` and `check`.\n\n```shell\ndnx skills update -g\n```\n\n```text\nChecking for skill updates...\n\nChecking global skill 1/1: my-skill\nFound 1 global update(s)\n\nUpdate available: my-skill\n  Run: skills add owner/repo/skills/my-skill -g -y\n\nUpdates available for 1 skill(s); no updates were applied.\n```\n\n**`update` only reports; it never applies changes.** It prints the exact `skills add ... -y` command to run for each skill that has an update (prefix it with `dnx` when you run through `dnx`). Copy that command and run it yourself to apply the update. The output is explicit: `no updates were applied.`\n\nScope the check the same way you scope an install:\n\n- `-g` (or `--global`) checks global skills only.\n- `-p` (or `--project`) checks project skills only.\n- Pass both, or name specific skills, to check both scopes.\n- With no scope flag in an interactive shell, the CLI prompts you to choose. Non-interactively (for example with `-y`), it checks both scopes.\n\nWhen there is nothing to update, you get a clean report:\n\n```text\nChecking for skill updates...\n\nChecking global skill 1/1: my-skill\nAll global skills are up to date\n```\n\nThe update check calls the GitHub API. If you hit a rate limit, set a `GITHUB_TOKEN` or `GH_TOKEN` environment variable (or sign in with `gh auth login`) and the CLI uses it for the check. See [Troubleshooting](./troubleshooting.md) for rate-limit and timeout details.\n\n# Remove skills\n\n`dnx skills remove` uninstalls skills. It unlinks each agent's copy and removes the canonical store entry once no remaining agent references it, then updates the lock file.\n\nTo remove specific skills by name, list them:\n\n```shell\ndnx skills remove alpha --yes\n```\n\n```text\nSuccessfully removed 1 skill(s)\n```\n\nTo remove everything, pass `--all`:\n\n```shell\ndnx skills remove --all\n```\n\n```text\nSuccessfully removed 1 skill(s)\n```\n\nTo limit removal to specific agents, add `--agent`. To target your user-level skills, add `--global`.\n\nRun `dnx skills remove` with no names to remove interactively: the CLI shows a multi-select prompt, then a confirmation that defaults to **no**. Declining cancels and removes nothing:\n\n```text\n$ dnx skills remove\n\nRemoval cancelled\n```\n\nIf a named skill is not installed, the CLI tells you and exits cleanly without changing anything:\n\n```text\nNo matching skills found for: nope\n```\n\n# Next steps\n\n- [Authoring Skills](./authoring-skills.md): write and publish your own `SKILL.md` with `dnx skills init`.\n- [Reference](./reference.md): every command, flag, the full list of 55+ agents, and per-agent install directories.\n- [Troubleshooting](./troubleshooting.md): clone failures, authentication errors, rate limits, and symlink fallbacks.\n","website/content/docs/skills/troubleshooting.md":"---\ntitle: \"Troubleshooting\"\ndescription: \"Troubleshoot `skills` CLI errors: each section maps the exact message the CLI prints to its cause and a copy-pasteable fix for installing and updating skills.\"\n---\n\nThis page maps the errors and surprises you hit when running `skills` to their cause and fix. Each section starts with the exact message the CLI prints (where one exists), explains why it happens, and gives you a copy-pasteable way out.\n\nIf you are new to `skills`, start with [Getting Started](./getting-started.md). For the full command and flag surface, see the [Reference](./reference.md). For what each agent identifier means and where skills land, see [Installing Skills](./installing-skills.md).\n\n# \"No valid skills found. Skills require a SKILL.md with name and description.\"\n\nYou ran `dnx skills add <source>` and the CLI reached the source but found nothing to install:\n\n```text\n$ dnx skills add ./my-skills --yes --agent claude-code\n# exit 1\n\nSource: /home/you/my-skills\nNo valid skills found. Skills require a SKILL.md with name and description.\n```\n\nCause: a skill is a directory that contains a `SKILL.md` file with both `name` and `description` in its YAML frontmatter. The CLI silently skips any folder that is missing the file, missing either field, or whose `name`/`description` collapses to empty. By default, it only looks at the source root (or the subpath you pointed it at), so a `SKILL.md` buried in a nested directory is not discovered.\n\nTo see exactly what the CLI finds without installing anything, run `--list`:\n\n```shell\ndnx skills add owner/repo --list\n```\n\n```text\nSource: https://github.com/owner/repo.git\nFound 2 skill(s)\n\nAvailable Skills\n  alpha\n    the alpha skill\n  beta\n    the beta skill\n\nUse --skill <name> to install specific skills\n```\n\nIf `--list` reports `Found 0 skill(s)`, work through these in order:\n\n| Check                                                     | Fix                                                                                                                            |\n| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| Is your path or subpath pointing at the right folder?     | Point at the directory that contains `SKILL.md`, or add the repo subpath: `#!shell dnx skills add owner/repo/skills/my-skill`. |\n| Does the `SKILL.md` have both `name:` and `description:`? | Add the missing field. Both must be non-empty. See [Authoring Skills](./authoring-skills.md).                                  |\n| Are the skills in nested directories?                     | Add `--full-depth` to scan nested directories: `#!shell dnx skills add owner/repo --full-depth --list`.                        |\n\n> `--full-depth` widens discovery so the CLI scans nested directories for skills. It does not change how much of the repository is cloned. Clones are always shallow regardless of this flag.\n\n# \"Invalid agents: &lt;name&gt;\"\n\nYou passed an `--agent` value that the CLI does not recognize:\n\n```text\n$ dnx skills add ./my-skills --yes --agent bogus\n# exit 1\n\nSource: /home/you/my-skills\nFound 1 skill(s)\n\n┌─Invalid agents───────────────────────────────────────────────────────────────┐\n│ Invalid agents: bogus                                                        │\n│                                                                              │\n│ Valid agents: adal, aider-desk, amp, antigravity, augment, bob, claude-code, │\n│ cline, codearts-agent, codebuddy, codemaker, codestudio, codex,              │\n│ command-code, continue, cortex, crush, cursor, deepagents, devin, dexto,     │\n│ droid, firebender, forgecode, gemini-cli, github-copilot, goose,             │\n│ hermes-agent, iflow-cli, junie, kilo, kimi-cli, kiro-cli, kode, mcpjam,      │\n│ mistral-vibe, mux, neovate, openclaw, opencode, openhands, pi, pochi, qoder, │\n│ qwen-code, replit, roo, rovodev, tabnine-cli, trae, trae-cn, universal,      │\n│ warp, windsurf, zencoder                                                     │\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\nCause: the value is misspelled or uses the wrong case. Agent identifiers are case-sensitive, and several differ from the product's marketing name. The most common mistakes:\n\n| You typed                   | Use instead      |\n| --------------------------- | ---------------- |\n| `copilot`, `github_copilot` | `github-copilot` |\n| `Claude-Code`, `claude`     | `claude-code`    |\n| `gemini`                    | `gemini-cli`     |\n| `roo-code`                  | `roo`            |\n\nThe error panel always prints every valid identifier, so copy the correct one from the list. The same `Invalid agents: <name>` message appears (without the panel) from `dnx skills list` and `dnx skills remove`. For the full table of identifiers and where each one installs skills, see [Installing Skills](./installing-skills.md) and the [Reference](./reference.md).\n\n# Cloning a private repository fails with \"Authentication failed\"\n\n`dnx skills add` reports an authentication error and stops before installing.\n\nCause: the CLI never prompts for credentials. It shells out to your own `git`, which uses your existing setup (SSH agent keys, a git credential helper, `gh` auth, or `~/.netrc`). When git cannot authenticate, the CLI surfaces the failure instead of hanging. Any credentials embedded in a URL are redacted from the output, so secrets never appear in errors or in the lock file.\n\nTo fix it, confirm your machine can reach the repository, then retry the same `dnx skills add` command.\n\nFor SSH sources (`git@github.com:owner/repo.git`):\n\n```shell\nssh -T git@github.com\n# Hi <you>! You've successfully authenticated, but GitHub does not provide shell access.\n```\n\nFor HTTPS sources, authenticate with the GitHub CLI or configure a git credential helper. These are one-time setup commands whose output varies by environment:\n\n```shell\ngh auth login                         # uses the gh credential helper\n# or\ngit config --global credential.helper store\n```\n\nAfter `gh auth login` completes, it confirms the authenticated account.\n\nOnce `git clone <repo>` succeeds on its own, `dnx skills add <repo>` will succeed too.\n\n# The clone times out\n\nA large repository can exceed the default clone budget and cause the CLI to abort the fetch.\n\nCause: the CLI caps each clone at 5 minutes (300000 ms). The clone is always shallow (latest commit only), but a very large repository or a slow connection can still run past the limit.\n\nTo raise the timeout, set `SKILLS_CLONE_TIMEOUT_MS` in milliseconds before running the command:\n\n```shell\nSKILLS_CLONE_TIMEOUT_MS=600000 dnx skills add owner/big-repo --agent claude-code   # 10 minutes\n```\n\nWith the longer budget the clone finishes and the install completes with the usual `Installed 1 skill(s)` panel.\n\nAlternatively, clone the repository yourself and point `skills` at the local copy. This skips the network step entirely:\n\n```shell\ngit clone --depth 1 https://github.com/owner/big-repo.git\ndnx skills add ./big-repo --agent claude-code\n```\n\nPointing `skills` at the local clone installs the skill without touching the network and prints the same `Installed 1 skill(s)` panel.\n\n# A skill does not appear for one agent\n\n`dnx skills add` reports success, the skill shows up in `dnx skills list`, but one of your agents does not see it.\n\nCause: agents that keep skills in their own directory (for example `.claude/skills` for Claude Code or `.windsurf/skills` for Windsurf) only get a link when that agent's directory already exists in your project. The CLI will not create a config directory for an agent you do not use. When the directory is missing, it skips the link for that agent but still materializes the skill in the shared `.agents/skills` store, so the skill is installed; it is only the per-agent link that is missing.\n\nPick whichever fix matches your intent:\n\n| Goal                                                           | Fix                                                                                                                                   |\n| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |\n| You do use that agent in this project                          | Create its directory, then re-run the install: `#!shell mkdir -p .claude && dnx skills add owner/repo --agent claude-code`.           |\n| You want a self-contained copy regardless of agent directories | Add `--copy` to write the skill straight into each agent's directory: `#!shell dnx skills add owner/repo --agent claude-code --copy`. |\n| You meant a different agent                                    | Re-run with the correct `--agent` value. See [Installing Skills](./installing-skills.md).                                             |\n\nAfter the directory exists, re-running the install links the skill into `.claude/skills`. The Installation Summary then lists `Symlinked:  Claude Code` instead of skipping that agent.\n\nAgents that share the universal `.agents/skills` store (Cursor, Codex, GitHub Copilot, Gemini CLI, and others) always see the skill because their directory is the canonical store.\n\n# Symlinks are not created (Windows)\n\nOn Windows, `skills` copies skills into agent directories instead of linking them.\n\nCause: creating a symlink on Windows requires either an elevated process or Developer Mode. When the CLI cannot create the link, it automatically falls back to copying the skill so the install still succeeds. The skill works either way; the only difference is that copies do not share a single editable source of truth the way symlinks do.\n\nTo get symlinks instead of copies, choose one:\n\n- Enable Developer Mode (Settings, \"For developers\", \"Developer Mode\"), then re-run the command.\n- Run your terminal elevated (\"Run as administrator\") and re-run the command.\n\nIf you prefer copies and want the CLI to copy without attempting a symlink first, pass `--copy` explicitly:\n\n```shell\ndnx skills add owner/repo --agent claude-code --copy\n```\n\nThe output shows the skill was copied rather than linked: the Installation Summary lists `Copied:  Claude Code`, and the skill is written directly into `.claude/skills`.\n\n# \"skills update\" cannot check a skill or hits a rate limit\n\n`dnx skills update` reports that one or more skills could not be checked:\n\n```text\n$ dnx skills update -g\n\nChecking for skill updates...\n\n\n1 skill(s) cannot be checked automatically:\n  * legacy (Private or deleted repo)\n    To update: skills add https://github.com/owner/repo -g -y\n```\n\nCause: `update` checks for newer versions by calling the GitHub API, and unauthenticated calls are rate-limited. It also cannot diff every kind of source. Skills installed from a local path, a generic git URL, a well-known HTTP source, or a private or deleted repository have no checkable remote tree, so they are reported as \"cannot be checked automatically\" with a manual refresh hint.\n\nTo raise the rate limit, give `skills` a GitHub token and re-run. The CLI reads `GITHUB_TOKEN`, then `GH_TOKEN`, then falls back to `gh auth token`:\n\n```shell\nexport GITHUB_TOKEN=ghp_...   # or: gh auth login\ndnx skills update\n```\n\nWith the token in place the rate limit clears and the check completes:\n\n```text\nChecking for skill updates...\n\nAll skills are up to date.\n```\n\nFor sources that can never be checked automatically, re-install with `dnx skills add` to refresh them. The `update` output prints the exact command to run for each one:\n\n```shell\ndnx skills add owner/repo/skills/my-skill -y\n```\n\nThe refresh re-installs the skill from its source and prints the usual `Installed 1 skill(s)` panel.\n\n> `dnx skills update` only checks for and reports available updates. It never applies them. Whatever it finds, it prints the precise `skills add ...` command for you to run (prefix it with `dnx` when you use `dnx`). The aliases `dnx skills upgrade` and `dnx skills check` behave identically. See the [Reference](./reference.md).\n\n# \"... is newer than this skills supports\"\n\nA command refuses to write to a lock file and reports that the on-disk version is newer than this version of `skills` supports.\n\nCause: the lock file (`skills-lock.json` in your project, or the global `.skill-lock.json`) was written by a newer version of `skills` than the one you are running. The CLI reads newer lock files but refuses to modify them, so it does not corrupt state written by a version it does not understand.\n\nTo fix it, update `skills` to the latest release:\n\n```shell\ndotnet tool update -g skills\n```\n\nA successful upgrade reports the version change:\n\n```text\nTool 'skills' was successfully updated from version 0.1.0 to version 0.3.0.\n```\n\nIf you no longer need the existing lock state and want to start fresh, delete the lock file and re-install your skills. The project lock lives at `skills-lock.json` in your working directory; the global lock lives at `~/.local/share/skills/.skill-lock.json` (or under `$XDG_DATA_HOME/skills` if that variable is set).\n\n> [!WARNING]\n> **Deleting a lock file discards update tracking.** The CLI uses the lock file to know what is installed and to check for updates. After deleting it, run `dnx skills add` again for each skill so the CLI can rebuild the lock. The installed skill folders themselves are not removed by deleting the lock.\n\n# Bundled binary assets are missing from a skill\n\nA skill installs, but a binary file it ships (an image, a model, a compiled tool) is a tiny placeholder or absent.\n\nCause: the CLI disables Git LFS while cloning, so only LFS pointer files are fetched, not the large binaries they track. This keeps clones fast and shallow, but it means LFS-tracked assets do not arrive with the skill.\n\nTo fix it, change how the skill stores its assets:\n\n- Store skill assets without Git LFS so they travel as ordinary files in the repository.\n- Vendor the assets directly into the skill folder (commit the real files alongside `SKILL.md`).\n\nIf you author the skill yourself, see [Authoring Skills](./authoring-skills.md) for how to lay out bundled resources.\n\n# \"Failed to remove\" a skill\n\n`dnx skills remove` reports that it could not remove a skill:\n\n```text\n$ dnx skills remove \"My Skill\" --yes\n# exit 1\n\nFailed to remove 1 skill(s)\n  My Skill: ...\n```\n\nCause: the CLI removes a skill by the sanitized, lowercase, hyphenated name it uses on disk (for example `my-skill`). A folder created outside `skills` whose name does not match that sanitized form is not something the CLI will delete automatically, so it reports the failure rather than falsely claiming success. The CLI also refuses to delete a real non-empty directory or file it did not create, which protects your own data.\n\nTo fix it, delete the folder yourself from the skills directory. For a project install that is `./.agents/skills/<folder>`; for the corresponding agent directory it is, for example, `./.claude/skills/<folder>`. For a global install the canonical store is `~/.agents/skills/<folder>`.\n\n```shell\nrm -rf \"./.agents/skills/My Skill\"\n```\n\nRun `dnx skills list` afterward to confirm the skill is gone. The listing no longer shows the removed skill:\n\n```text\n$ dnx skills list\n\nNo project skills found.\nTry listing global skills with -g\n```\n\n# Next steps\n\n- [Reference](./reference.md): every command, flag, exit code, and environment variable in one place.\n- [Installing Skills](./installing-skills.md): sources, scopes, agent targeting, and the symlink versus copy model.\n- Still stuck? Ask in the [ChilliCream Slack](https://slack.chillicream.com/).\n","website/content/docs/skills/reference.md":"---\ntitle: \"Reference\"\ndescription: \"Complete `skills` CLI reference covering every command and flag, JSON output, exit codes, environment variables, file locations, and supported agents.\"\n---\n\nThis page is the complete, precise reference for the `skills` command surface, JSON output, exit codes, environment variables, file locations, and supported agents. It is meant for lookup, not for learning. To learn by doing, start at [Installing Skills](./installing-skills.md) and [Authoring Skills](./authoring-skills.md).\n\nEvery command prints the same per-command help at the terminal. Run `dnx skills <command> --help` to see the synopsis, arguments, and options for that command.\n\n```shell\ndnx skills add --help\n```\n\n```text\nDescription:\n  Add a skill from a source\n\nUsage:\n  skills add [<source>] [options]\n\nArguments:\n  <source>  Source to fetch skills from (e.g., owner/repo, URL, local path)\n\nOptions:\n  -g, --global    Install globally\n  -a, --agent     Target agent(s)\n  -s, --skill     Skill name filter(s)\n  -y, --yes       Skip prompts (non-interactive)\n  --all           Install all skills to all agents\n  --copy          Copy instead of symlinking\n  --full-depth    Scan nested directories for skills\n  -l, --list      List available skills without installing\n  -?, -h, --help  Show help and usage information\n```\n\n> The binary on your PATH is `skills`. Install it with `#!shell dotnet tool install -g skills`, or run it without installing via `dnx skills <command>` (requires the .NET 10 SDK or later). Both forms accept the same commands, arguments, and options documented below.\n\n# Commands\n\n`skills` has five commands: `add`, `remove`, `list`, `update`, and `init`. Each command's options are independent. There are no shared global options beyond `--help` and `--version` (see [Global flags](#global-flags)).\n\n## skills add &lt;source&gt;\n\nAdd skills from a source. Skills are discovered at the source, then materialized into a canonical store and linked into each target agent's skills directory.\n\n```text\ndnx skills add <source> [options]\n```\n\n### Arguments\n\n| Argument | Arity | Required | Description                                                                                                                                                        |\n| -------- | ----- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `source` | one   | yes      | Source to fetch skills from (for example `owner/repo`, a full git URL, or a local path). If omitted, the command exits 1 with `Missing required argument: source`. |\n\n### Options\n\n| Option         | Alias  | Type                | Default         | Description                                                                                                                                                                                         |\n| -------------- | ------ | ------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--global`     | `-g`   | bool                | `false`         | Install to the global scope (your home directory) instead of the current project.                                                                                                                   |\n| `--agent`      | `-a`   | string (repeatable) | (auto-detected) | Target agent(s). Repeatable and space-separated (`--agent claude-code cursor` or `--agent claude-code --agent cursor`). `--agent *` targets every agent. See [Supported agents](#supported-agents). |\n| `--skill`      | `-s`   | string (repeatable) | (all)           | Install only skills whose name matches the given filter(s). Repeatable.                                                                                                                             |\n| `--yes`        | `-y`   | bool                | `false`         | Skip all prompts and run non-interactively.                                                                                                                                                         |\n| `--all`        | (none) | bool                | `false`         | Install all skills to all agents. Implies `--skill *`, `--agent *`, and `--yes`.                                                                                                                    |\n| `--copy`       | (none) | bool                | `false`         | Copy skill files into each agent directory instead of symlinking. Use for agents that do not follow symlinks.                                                                                       |\n| `--full-depth` | (none) | bool                | `false`         | Widen discovery to scan nested directories in the source, not only the source root. This does not change the git clone (clones are always shallow).                                                 |\n| `--list`       | `-l`   | bool                | `false`         | List the available skills at the source without installing anything, then exit.                                                                                                                     |\n\nThe default install mode is symlink: the CLI materializes each skill once into a canonical store and creates a relative symlink from each agent directory back to it. Pass `--copy` to copy instead. When every selected agent shares one skills directory, copy is used automatically.\n\nFor sources, scopes, and install mechanics, see [Installing Skills](./installing-skills.md). For agent targeting, see [Supported agents](#supported-agents).\n\n## skills remove [skills...]\n\nRemove installed skills. With no skill names and an interactive terminal, the CLI prompts you to select which skills to remove.\n\n```text\ndnx skills remove [skills...] [options]\n```\n\n### Arguments\n\n| Argument | Arity        | Required | Description                                                                                          |\n| -------- | ------------ | -------- | ---------------------------------------------------------------------------------------------------- |\n| `skills` | zero or more | no       | Skill names to remove. Matched case-insensitively. With no names and no `--all`, runs interactively. |\n\n### Options\n\n| Option     | Alias  | Type                | Default | Description                                                  |\n| ---------- | ------ | ------------------- | ------- | ------------------------------------------------------------ |\n| `--global` | `-g`   | bool                | `false` | Remove from the global scope instead of the current project. |\n| `--agent`  | `-a`   | string (repeatable) | (all)   | Limit removal to specific agent(s). Repeatable.              |\n| `--yes`    | `-y`   | bool                | `false` | Skip prompts and run non-interactively.                      |\n| `--all`    | (none) | bool                | `false` | Remove every installed skill.                                |\n\nIn interactive mode, the CLI shows a multiselect prompt followed by a confirmation prompt. The confirmation defaults to no. Declining the confirmation prints `Removal cancelled` and exits with code 130 (see [Exit codes](#exit-codes)).\n\n```text\n$ dnx skills remove alpha\n# exit 130\n\nRemoval cancelled\n```\n\n## skills list\n\nList installed skills. With no options, lists the current project's skills.\n\n```text\ndnx skills list [options]\n```\n\nThis command takes no positional arguments.\n\n### Options\n\n| Option     | Alias  | Type                | Default | Description                                                                           |\n| ---------- | ------ | ------------------- | ------- | ------------------------------------------------------------------------------------- |\n| `--global` | `-g`   | bool                | `false` | List skills in the global scope instead of the current project.                       |\n| `--agent`  | `-a`   | string (repeatable) | (none)  | Filter the listing to specific agent(s). Repeatable.                                  |\n| `--format` | (none) | `text` \\| `json`    | `text`  | Output format. `json` emits a JSON array to stdout (see [JSON output](#json-output)). |\n| `--json`   | (none) | bool                | `false` | Shorthand for `--format json`.                                                        |\n\nJSON output is enabled when either `--json` is present or `--format json` is set (case-insensitive). Enabling JSON suppresses the banner and writes the array to stdout.\n\n## skills update [skills...]\n\nCheck for available updates and print the exact command to apply each one.\n\n```text\ndnx skills update [skills...] [options]\n```\n\n> Aliases: `upgrade` and `check`. `dnx skills upgrade` and `dnx skills check` are identical to `dnx skills update`.\n\n> [!WARNING]\n> **`update` only reports.** It never modifies files or lock files. For each skill that has an update, it prints a `skills add ...` command you can copy and run to apply it (run it as `dnx skills add ...` if you use `dnx`). The command always exits 0, even when updates are available. Its output ends with `no updates were applied.`\n\n### Arguments\n\n| Argument | Arity        | Required | Description                                                                                                        |\n| -------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------ |\n| `skills` | zero or more | no       | Optional skill names to check. Scope is resolved the same way with or without names (see the scope options below). |\n\n### Options\n\n| Option      | Alias | Type | Default | Description                                                                |\n| ----------- | ----- | ---- | ------- | -------------------------------------------------------------------------- |\n| `--global`  | `-g`  | bool | `false` | Check global skills only.                                                  |\n| `--project` | `-p`  | bool | `false` | Check project skills only.                                                 |\n| `--yes`     | `-y`  | bool | `false` | Skip the interactive scope prompt. Non-interactive runs check both scopes. |\n\nWith neither `-g` nor `-p`, an interactive terminal prompts you to choose Project, Global, or Both. Passing both flags, or running non-interactively, checks both scopes.\n\n```text\n$ dnx skills update -g\n\nChecking for skill updates...\n\nChecking global skill 1/1: my-skill\nFound 1 global update(s)\n\nUpdate available: my-skill\n  Run: skills add owner/repo/skills/my-skill -g -y\n\nUpdates available for 1 skill(s); no updates were applied.\n```\n\n## skills init [name]\n\nScaffold a new skill directory containing a `SKILL.md` template. This command has no options.\n\n```text\ndnx skills init [name]\n```\n\n### Arguments\n\n| Argument | Arity       | Required | Description                                                                                                                                                       |\n| -------- | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `name`   | zero or one | no       | Skill name. Creates `<name>/SKILL.md`. The name is sanitized to a slug. With no name, derives the slug from the current directory and writes `SKILL.md` in place. |\n\nIf the target `SKILL.md` already exists, the CLI does not overwrite it. It prints `Skill already exists at <path>` and exits 0.\n\n```text\n$ dnx skills init my-skill\n\nInitialized skill: my-skill\n\nCreated:\n  my-skill/SKILL.md\n\nNext steps:\n  1. Edit my-skill/SKILL.md to define your skill instructions\n  2. Update the name and description in the frontmatter\n\nPublishing:\n  GitHub: Push to a repo, then skills add <owner>/<repo>\n  URL:    Host the file, then skills add https://example.com/my-skill/SKILL.md\n```\n\nSee [Authoring Skills](./authoring-skills.md) for the `SKILL.md` format and publishing workflow.\n\n## Global flags\n\nThese are provided on the root command and on every subcommand.\n\n| Option      | Aliases    | Type | Description                                            |\n| ----------- | ---------- | ---- | ------------------------------------------------------ |\n| `--help`    | `-h`, `-?` | bool | Show help. On a subcommand, shows that command's help. |\n| `--version` | (none)     | bool | Print the installed CLI version and exit 0.            |\n\nRunning `skills` with no arguments shows the banner and exits 0. Running `#!shell dnx skills --help` shows curated top-level help. A bare `--` token is removed before parsing, so `#!shell dnx skills add --agent codex -- owner/repo` parses the same as without it.\n\n# JSON output\n\n`#!shell dnx skills list --json` (equivalently `#!shell dnx skills list --format json`) prints a JSON array to stdout. Each element describes one installed skill.\n\n```shell\ndnx skills list --json\n```\n\n```json\n[\n  {\n    \"name\": \"alpha\",\n    \"path\": \"/home/you/project/.agents/skills/alpha\",\n    \"scope\": \"project\",\n    \"agents\": [\"Claude Code\", \"Windsurf\"]\n  }\n]\n```\n\n| Field    | Type     | Description                                                                                                                |\n| -------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |\n| `name`   | string   | The skill's sanitized name (its on-disk directory name).                                                                   |\n| `path`   | string   | Absolute path to the skill in the canonical store.                                                                         |\n| `scope`  | string   | `\"project\"` or `\"global\"`. `\"global\"` when listed with `-g`, otherwise `\"project\"`.                                        |\n| `agents` | string[] | Display names of agents linked to this skill (for example `Claude Code`). Empty when the skill is not linked to any agent. |\n\nThe array is written to stdout, so you can pipe it to a tool such as `jq`. Banner and progress output are suppressed in JSON mode.\n\n# Exit codes\n\n`skills` uses exactly three exit codes.\n\n| Code  | Name      | Meaning                                                                                                                                        |\n| ----- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| `0`   | Success   | The command completed. Note that `update` exits 0 even when updates are available, and `remove` exits 0 when there is nothing to remove.       |\n| `1`   | Failure   | The command failed (for example an invalid agent name, no valid skills found, or a file system error). The error message is written to stderr. |\n| `130` | Cancelled | The operation was cancelled, either by declining an interactive confirmation or by pressing Ctrl+C.                                            |\n\n# Environment variables\n\n| Variable                  | Default          | Effect                                                                                                                                                            |\n| ------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `SKILLS_CLONE_TIMEOUT_MS` | `300000`         | Git clone timeout in milliseconds (5 minutes). Must parse to a positive integer, otherwise the default is used. Raise it for large repositories or slow networks. |\n| `GITHUB_TOKEN`            | (unset)          | A GitHub API token. Used only by `update` to raise GitHub API rate limits when checking for updates. Not used for cloning.                                        |\n| `GH_TOKEN`                | (unset)          | Fallback GitHub API token. Consulted by `update` after `GITHUB_TOKEN`. Same effect.                                                                               |\n| `INSTALL_INTERNAL_SKILLS` | (unset)          | Set to `1` or `true` to include skills their authors marked as internal in discovery. By default such skills are hidden.                                          |\n| `CLAUDE_CONFIG_DIR`       | `~/.claude`      | Overrides the Claude Code configuration directory used for detection and global installs.                                                                         |\n| `CODEX_HOME`              | `~/.codex`       | Overrides the Codex configuration directory used for detection and global installs.                                                                               |\n| `VIBE_HOME`               | `~/.vibe`        | Overrides the Mistral Vibe configuration directory used for detection and global installs.                                                                        |\n| `XDG_DATA_HOME`           | `~/.local/share` | Root for the global lock location. The global lock lives at `$XDG_DATA_HOME/skills/.skill-lock.json`.                                                             |\n\n`XDG_CONFIG_HOME` (default `~/.config`) and `XDG_STATE_HOME` (default `~/.local/state`) affect where the CLI keeps its own configuration and logs, and where several agents resolve their global directories.\n\nFor private repositories, the CLI shells out to `git` and uses your existing git credentials (SSH agent, credential helper, `gh` auth). See [Troubleshooting](./troubleshooting.md) for authentication and rate-limit guidance.\n\n# File locations\n\nThe CLI writes a lock file per scope and materializes skills into a canonical store. Project scope is the current working directory; global scope is your home directory.\n\n| Scope   | Lock file                                                                              | Canonical skills store |\n| ------- | -------------------------------------------------------------------------------------- | ---------------------- |\n| Project | `skills-lock.json` (in the current working directory)                                  | `./.agents/skills`     |\n| Global  | `~/.local/share/skills/.skill-lock.json` (or `$XDG_DATA_HOME/skills/.skill-lock.json`) | `~/.agents/skills`     |\n\nNon-universal agents receive a symlink from their own directory (for example `.claude/skills/<name>`) back into the canonical store. Universal agents use the canonical store directly. See [Supported agents](#supported-agents) for per-agent directories.\n\n# Supported agents\n\nThe `skills` CLI supports 55+ agents. It detects which agents are installed on your machine by probing each agent's configuration directory, and it detects which agent it is running inside by reading environment variables that agent hosts set. When run inside a detected agent, `add` runs non-interactively and targets that agent plus the universal agents.\n\nAgent identifiers are case-sensitive (the identifier is `github-copilot`, not `copilot`). The `--agent` option is repeatable and accepts multiple values per token. `--agent *` targets all agents. \"Universal\" agents share the `.agents/skills` store, so installing a skill for one universal agent makes it visible to all of them.\n\nIn the table below, project directories are relative to the working directory and global directories are absolute (`~` is your home directory, `<config>` is `$XDG_CONFIG_HOME` or `~/.config`). Agents marked \"universal\" use the shared `.agents/skills` store at project scope.\n\n| Identifier       | Display name       | Project directory            | Global directory                             |\n| ---------------- | ------------------ | ---------------------------- | -------------------------------------------- |\n| `adal`           | AdaL               | `.adal/skills`               | `~/.adal/skills`                             |\n| `aider-desk`     | AiderDesk          | `.aider-desk/skills`         | `~/.aider-desk/skills`                       |\n| `amp`            | Amp                | `.agents/skills` (universal) | `<config>/agents/skills`                     |\n| `antigravity`    | Antigravity        | `.agents/skills` (universal) | `~/.gemini/antigravity/skills`               |\n| `augment`        | Augment            | `.augment/skills`            | `~/.augment/skills`                          |\n| `bob`            | IBM Bob            | `.bob/skills`                | `~/.bob/skills`                              |\n| `claude-code`    | Claude Code        | `.claude/skills`             | `~/.claude/skills` (via `CLAUDE_CONFIG_DIR`) |\n| `cline`          | Cline              | `.agents/skills` (universal) | `~/.agents/skills`                           |\n| `codearts-agent` | CodeArts Agent     | `.codeartsdoer/skills`       | `~/.codeartsdoer/skills`                     |\n| `codebuddy`      | CodeBuddy          | `.codebuddy/skills`          | `~/.codebuddy/skills`                        |\n| `codemaker`      | Codemaker          | `.codemaker/skills`          | `~/.codemaker/skills`                        |\n| `codestudio`     | Code Studio        | `.codestudio/skills`         | `~/.codestudio/skills`                       |\n| `codex`          | Codex              | `.agents/skills` (universal) | `~/.codex/skills` (via `CODEX_HOME`)         |\n| `command-code`   | Command Code       | `.commandcode/skills`        | `~/.commandcode/skills`                      |\n| `continue`       | Continue           | `.continue/skills`           | `~/.continue/skills`                         |\n| `cortex`         | Cortex Code        | `.cortex/skills`             | `~/.snowflake/cortex/skills`                 |\n| `crush`          | Crush              | `.crush/skills`              | `~/.config/crush/skills`                     |\n| `cursor`         | Cursor             | `.agents/skills` (universal) | `~/.cursor/skills`                           |\n| `deepagents`     | Deep Agents        | `.agents/skills` (universal) | `~/.deepagents/agent/skills`                 |\n| `devin`          | Devin for Terminal | `.devin/skills`              | `<config>/devin/skills`                      |\n| `dexto`          | Dexto              | `.agents/skills` (universal) | `~/.agents/skills`                           |\n| `droid`          | Droid              | `.factory/skills`            | `~/.factory/skills`                          |\n| `firebender`     | Firebender         | `.agents/skills` (universal) | `~/.firebender/skills`                       |\n| `forgecode`      | ForgeCode          | `.forge/skills`              | `~/.forge/skills`                            |\n| `gemini-cli`     | Gemini CLI         | `.agents/skills` (universal) | `~/.gemini/skills`                           |\n| `github-copilot` | GitHub Copilot     | `.agents/skills` (universal) | `~/.copilot/skills`                          |\n| `goose`          | Goose              | `.goose/skills`              | `<config>/goose/skills`                      |\n| `hermes-agent`   | Hermes Agent       | `.hermes/skills`             | `~/.hermes/skills`                           |\n| `iflow-cli`      | iFlow CLI          | `.iflow/skills`              | `~/.iflow/skills`                            |\n| `junie`          | Junie              | `.junie/skills`              | `~/.junie/skills`                            |\n| `kilo`           | Kilo Code          | `.kilocode/skills`           | `~/.kilocode/skills`                         |\n| `kimi-cli`       | Kimi Code CLI      | `.agents/skills` (universal) | `~/.config/agents/skills`                    |\n| `kiro-cli`       | Kiro CLI           | `.kiro/skills`               | `~/.kiro/skills`                             |\n| `kode`           | Kode               | `.kode/skills`               | `~/.kode/skills`                             |\n| `mcpjam`         | MCPJam             | `.mcpjam/skills`             | `~/.mcpjam/skills`                           |\n| `mistral-vibe`   | Mistral Vibe       | `.vibe/skills`               | `~/.vibe/skills` (via `VIBE_HOME`)           |\n| `mux`            | Mux                | `.mux/skills`                | `~/.mux/skills`                              |\n| `neovate`        | Neovate            | `.neovate/skills`            | `~/.neovate/skills`                          |\n| `openclaw`       | OpenClaw           | `skills`                     | `~/.openclaw/skills`                         |\n| `opencode`       | OpenCode           | `.agents/skills` (universal) | `<config>/opencode/skills`                   |\n| `openhands`      | OpenHands          | `.openhands/skills`          | `~/.openhands/skills`                        |\n| `pi`             | Pi                 | `.pi/skills`                 | `~/.pi/agent/skills`                         |\n| `pochi`          | Pochi              | `.pochi/skills`              | `~/.pochi/skills`                            |\n| `qoder`          | Qoder              | `.qoder/skills`              | `~/.qoder/skills`                            |\n| `qwen-code`      | Qwen Code          | `.qwen/skills`               | `~/.qwen/skills`                             |\n| `replit`         | Replit             | `.agents/skills` (universal) | `<config>/agents/skills`                     |\n| `roo`            | Roo Code           | `.roo/skills`                | `~/.roo/skills`                              |\n| `rovodev`        | Rovo Dev           | `.rovodev/skills`            | `~/.rovodev/skills`                          |\n| `tabnine-cli`    | Tabnine CLI        | `.tabnine/agent/skills`      | `~/.tabnine/agent/skills`                    |\n| `trae`           | Trae               | `.trae/skills`               | `~/.trae/skills`                             |\n| `trae-cn`        | Trae CN            | `.trae/skills`               | `~/.trae-cn/skills`                          |\n| `universal`      | Universal          | `.agents/skills` (universal) | `<config>/agents/skills`                     |\n| `warp`           | Warp               | `.agents/skills` (universal) | `~/.agents/skills`                           |\n| `windsurf`       | Windsurf           | `.windsurf/skills`           | `~/.codeium/windsurf/skills`                 |\n| `zencoder`       | Zencoder           | `.zencoder/skills`           | `~/.zencoder/skills`                         |\n\nPassing an unknown identifier exits 1 and prints the full list of valid identifiers:\n\n```text\n$ dnx skills add ./local-path --yes --agent bogus\n# exit 1\n\nInvalid agents: bogus\n```\n\n# See also\n\n- [Installing Skills](./installing-skills.md): sources, scopes, and the install workflow in depth.\n- [Authoring Skills](./authoring-skills.md): the `SKILL.md` format, `dnx skills init`, and publishing.\n- [Troubleshooting](./troubleshooting.md): authentication, rate limits, timeouts, and common errors.\n","website/content/docs/skills/structure.yaml":"title: Skills\nitems:\n  - path: index\n    title: Introduction\n  - path: getting-started\n    title: Getting Started\n  - path: installing-skills\n    title: Installing Skills\n  - path: authoring-skills\n    title: Authoring Skills\n  - path: reference\n    title: Reference\n  - path: troubleshooting\n    title: Troubleshooting\n","src/HotChocolate/CostAnalysis/tools/oracle/LICENSE-graphql-static-analysis-rs.md":"# License notice: graphql-static-analysis-rs\n\n`dump_corpus.rs` in this directory is built against, and the vendored\n`exact-case.json` corpus is generated from,\n[`graphql-static-analysis-rs`](https://github.com/duckki/graphql-static-analysis-rs)\nat commit `fec57fd7a980b5399637fa464a9bdce0781d91dd` (v0.2.0):\n\n```\nMIT License\n\nCopyright 2026 graphql-static-analysis contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n\n`oracle.patch` and `dump_corpus.rs` are original files written for this\nrepository; they are not derived from the crate's own source and are covered\nby this repository's own license.\n","src/HotChocolate/CostAnalysis/tools/oracle/README.md":"# Cost differential oracle\n\nRegenerates the vendored ExactCase cost corpus\n(`../../test/CostAnalysis.Core.Conformance.Tests/__resources__/rust-corpus/`)\nfrom the MIT-licensed\n[`graphql-static-analysis-rs`](https://github.com/duckki/graphql-static-analysis-rs)\ncrate, the differential oracle for this cost analysis implementation.\n\n## Prerequisites\n\nCorpus regeneration and live differential runs require rustup with stable\nRust >= 1.90 (the pinned commit's `rust-version`) and a C++ compiler. The\ncrate's `fuzz` package links `libfuzzer-sys` 0.4 unconditionally, including\nfor a plain `cargo build` or `cargo run`. Install Rust with:\n\n```bash\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal\n. \"$HOME/.cargo/env\" && rustup toolchain install stable\n```\n\nThe scripts install nothing. `clone-oracle.sh` and `run-nightly.sh` print the\ninstall line when `cargo` is missing, and `run-nightly.sh` also rejects Rust\nversions below 1.90 and missing C++ compilers. Pull-request CI does not run\nRust. The scheduled workflow provisions stable Rust and uses the compiler on\n`ubuntu-26.04`.\n\n## Files\n\n- `clone-oracle.sh`: clones `graphql-static-analysis-rs` at the pinned commit\n  into the gitignored `.oracle/` next to this file, applies `oracle.patch`,\n  and copies `dump_corpus.rs` into the checkout's `fuzz/examples/`.\n- `oracle.patch`: a small patch against the pinned commit. `SCHEMA` and\n  `variable_values` in the crate's `fuzz/src/tree_summary/operation.rs` are\n  `pub(super)` (private to the fuzz package's own targets); the patch adds\n  `pub fn schema()` and `pub fn variables_json(variable_case: u8)` accessors\n  and registers `dump_corpus` as a `[[example]]` in `fuzz/Cargo.toml`.\n- `dump_corpus.rs`: the dump program itself (see below).\n- `oracle.rs`: a Rust example that coerces generated variables, builds a\n  `CostModel`, and evaluates each case with `ExactCase` and its declared\n  default list size.\n- `Fuzz/`: the deterministic .NET generator and comparison command. It emits\n  real `AddCostAnalyzer` interceptor schemas and synthetic annotated schemas.\n- `run-nightly.sh`: generates cases, runs the live oracle, compares raw f64\n  bits, and writes a standalone fixture for the first disagreement.\n- `LICENSE-graphql-static-analysis-rs.md`: the crate's MIT license text and\n  attribution for the vendored commit.\n\n## Running the live oracle\n\n```bash\nbash src/HotChocolate/CostAnalysis/tools/oracle/run-nightly.sh \\\n    --seed 1 --cases 200\n```\n\nEvery case stores its seed and uses the same finite `DefaultListSize` on both\nimplementations. Generated operations are query-only and reject introspection\nmeta-fields, `@defer`, and `@stream` before emission. Variables are valid for\nthe generated operation and are coerced by `apollo_compiler` before the Rust\nestimator runs.\n\nReal schemas are printed from servers configured with `AddCostAnalyzer`,\ncursor and offset paging, filtering, sorting, and list-of-scalar fields. The\nprinted SDL therefore carries explicit resolver, filter, sort, paging, and\nlist-of-scalar annotations. Synthetic schemas cover signed weights,\n`@listSize`, input defaults, interfaces, unions, and directive argument\nweights. Operations cover named fragments, Boolean directives, aliases, and\nduplicate response names.\n\n`slicingArgumentDefaultValue` is a ChilliCream extension. When a generated\noperation supplies none of a field's slicing arguments, the generator adds\nthe declared default literal to the oracle copy of that operation only. It\ndoes not rewrite the schema, and it adds nothing when any slicing argument is\nalready supplied.\n\nComparison uses the hexadecimal IEEE-754 bit patterns for `typeCost` and\n`fieldCost`. A mismatch exits nonzero and writes one isolated\n`source: \"fuzz-found\"` fixture under the conformance resources. Add this\nfixture to the conformance suite to run it without Rust.\n\n## Regenerating the corpus\n\n```bash\ncd src/HotChocolate/CostAnalysis/tools/oracle\n./clone-oracle.sh\ncargo run --manifest-path .oracle/fuzz/Cargo.toml --example dump_corpus -- \\\n    ../../test/CostAnalysis.Core.Conformance.Tests/__resources__/rust-corpus\n```\n\nThis overwrites `exact-case.json` and `manifest.json` in that directory.\nThe same pinned commit produces byte-identical output.\n\n## What the dump does\n\nThe corpus contains the ExactCase IBM-cost cases from the crate's 15,840-case\nmatrix. There are 1,980 candidates before invalid-variable exclusions and\ndeduplication.\n\nFor each row:\n\n- Rows with variables that fail GraphQL coercion are excluded and counted\n  in the manifest's `excludedInvalidVariables`.\n- Duplicate `(operation, variables, defaultListSize)` rows are excluded and\n  counted in `deduplicated`. Missing variables and an empty variables object\n  are equivalent.\n- The remaining rows are costed with the crate's own `CostEstimator` in\n  `ExactCase` mode, with `default_list_size` set to the row's `list_size`\n  (0..4 for the legacy-family rows; the structural rows fix it at 2). The\n  emitted `typeCost`/`fieldCost` are the raw `f64` values `CostEstimator`\n  returns, never the crate's `cost:T,F` display format.\n- `emitted + excludedInvalidVariables + deduplicated == exactCostRows` always\n  holds (asserted by the dump itself); the manifest records all four numbers\n  plus the pinned commit.\n\nThe emitted schema excludes the crate's `@tag` definition. None of the\nemitted operations uses that directive.\n\n## Rust-free validation\n\nThe generator can build and emit cases without cloning or running the oracle:\n\n```bash\ndotnet run --project src/HotChocolate/CostAnalysis/tools/oracle/Fuzz \\\n    --framework net11.0 -- --seed 1 --cases 20 \\\n    --emit-only /tmp/fuzz-cases.json\n```\n\nReviewers without Rust installed can still validate the committed artifact\nshape:\n\n```bash\npython3 -c \"\nimport json\nd = json.load(open('../../test/CostAnalysis.Core.Conformance.Tests/__resources__/rust-corpus/exact-case.json'))\nm = json.load(open('../../test/CostAnalysis.Core.Conformance.Tests/__resources__/rust-corpus/manifest.json'))\nassert m['matrixSize'] == 15840 and m['exactCostRows'] == 1980\nassert len(d) == m['emitted'] == 1980 - m['excludedInvalidVariables'] - m['deduplicated'], m\nassert all(r['backend'] == 'exact-case' and 'directive @tag' not in r['sdl'] for r in d)\nprint('ok', len(d))\n\"\n```\n\nThis does not re-run the estimator, so it cannot catch a wrong `typeCost` or\n`fieldCost`; it only checks the corpus's shape and bookkeeping.\n","src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/ReplyMailCommandTests.Reply_Should_ThreadUnderOriginalMessage_AndInheritRootSubject_When_JsonOutputIsRequested.md":"# Command: /replymailcommandtests.reply_should_threadunderoriginalmessage_andinheritrootsubject_when_jsonoutputisrequested\n\nPath: `src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/ReplyMailCommandTests.Reply_Should_ThreadUnderOriginalMessage_AndInheritRootSubject_When_JsonOutputIsRequested.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/ReplyMailCommandTests.Reply_Should_ThreadUnderOriginalMessage_AndInheritRootSubject_When_JsonOutputIsRequested.md)","src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/SendMailCommandTests.Send_Should_ReturnSendResult_When_JsonOutputIsRequested.md":"# Command: /sendmailcommandtests.send_should_returnsendresult_when_jsonoutputisrequested\n\nPath: `src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/SendMailCommandTests.Send_Should_ReturnSendResult_When_JsonOutputIsRequested.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/SendMailCommandTests.Send_Should_ReturnSendResult_When_JsonOutputIsRequested.md)","src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Tasks/__snapshots__/TaskStoreTests.ReleaseAssigneeAsync_Should_ReleaseInProgressTasksAndAppearInReady.md":"# Command: /taskstoretests.releaseassigneeasync_should_releaseinprogresstasksandappearinready\n\nPath: `src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Tasks/__snapshots__/TaskStoreTests.ReleaseAssigneeAsync_Should_ReleaseInProgressTasksAndAppearInReady.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Tasks/__snapshots__/TaskStoreTests.ReleaseAssigneeAsync_Should_ReleaseInProgressTasksAndAppearInReady.md)"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# AGENTS.md\n\nThis file provides guidance to coding agents when working with this repository.\n\n## Attribution\n\n- Do not add `Co-authored-by` trailers or other co-author attribution for agents.\n\n## Pull Requests\n\n- Start a bug fix PR title with `Fix`: `Fix the gateway ignoring subgraph timeouts`. The title becomes the squash commit subject and the release note entry.\n- Area prefixes are optional. Write them in title case (`[Fusion]`, not `[fusion]`), and put `Fix` after one: `[Fusion] Fix the gateway ignoring subgraph timeouts`.\n\n## Build\n\n### Website\n\nUse `npm`.\n\n```bash\ncd website\nnpm ci\n```\n\nnpm 11 before 11.21.1 and npm 12 before 12.2.1 write `allowScripts` entries from `npm install-scripts approve` that npm cannot match under the linked install strategy ([npm/cli#9939](https://github.com/npm/cli/issues/9939)), so on those versions add approvals by hand as `\"<package>@<version>\": true`.\n\n### C# Source Code\n\nBuilds report IDE code-style violations (`IDE*`) as build errors, the same as CI does. Fix every reported style error.\n\nBuild the full solution:\n\n```bash\ndotnet build src/All.slnx\n```\n\nEach area has its own solution file, so you can build or test a subset directly:\n\n```bash\ndotnet test src/HotChocolate/Fusion\n```\n\n## Updating .NET\n\nWhen a change edits `TargetFrameworks` in `src/Directory.Build.props` or the SDK version in `global.json`, work through [docs/updating-dotnet.md](docs/updating-dotnet.md) before handoff.\n\n## Code Quality\n\n### C# / .NET\n\n- Always use curly braces for loops and conditionals, no exceptions.\n- Use file-scoped namespaces and 4-space indentation.\n- Test naming: `Method_Should_Outcome_When_Condition`.\n- No vacuous assertions (`Assert.NotNull` alone is not a test).\n- If a test requires excessive stubs and reflection, you're at the wrong test tier.\n- Do not use em dash style sentences in docs, comments, or XML documentation. Use commas, periods, parentheses, or colons instead.\n- XML docs should describe the contract and concepts, not internals like pooling or iteration mechanics, and should not leak other implementation details.\n- XML docs and comments are 1-2 sentences stating the contract: what it is, what null or edge values mean. No rationale, no use-case examples, no design justification. If a sentence explains why the design is right instead of what the member promises, delete it. The same applies to docs pages: every sentence must inform the reader, none may justify the design.\n- Do not make new parameters optional just to avoid updating call sites. A parameter should only be optional when it has a sensible semantic default and the API is frequently used (where call-site brevity outweighs explicitness). If a parameter is logically required, make it required and update all call sites.\n\n### Testing\n\n- Prefer snapshot tests over manual `Assert` calls, use **CookieCrumble** for snapshots.\n- CookieCrumble has native snapshot support for `IExecutionResult`, `GraphQLHttpResponse`, and other core types.\n- For smaller snapshots, prefer **inline snapshots** (`MatchInlineSnapshot`) over snapshot files.\n- For a collection of results (for example a stream of subscription events), snapshot the list with `MatchInlineSnapshots` (a parallel list of per-element inline snapshots). Do NOT concatenate with `string.Join(\"---\", values).MatchInlineSnapshot(...)`: a manual separator hides element boundaries and reinvents what the collection overload does natively.\n- For tests with multiple assertions, use **Markdown snapshots** (`MatchMarkdownSnapshot`).\n- Hard limit: a single test method must contain at most 5 `Assert.*` calls. Anything beyond that is too hard to reason about in review, switch to a snapshot (Markdown for multi-shape state, inline or file for a single output).\n- Use the AAA section marker style. Each section starts with a single-line comment, the test name documents intent, no paragraph-style block comments above sections:\n\n  ```csharp\n  // arrange\n  // optional one-line description, only when the next code is non-obvious\n  ... arrange code ...\n\n  // act\n  ... act code ...\n\n  // assert\n  ... assert code ...\n  ```\n\n- Avoid `Assert.DoesNotContain` as it is a weak assertion that easily goes out of date, it only proves something is absent without verifying what *is* present. Prefer `Assert.Equal` to check the entire string value, or `Assert.Collection` to verify the complete contents of a collection.\n- Snapshot tests: update from `__mismatch__/` directory, understand ordering issues before updating.\n- Filter tests during iteration, never run the full suite unnecessarily.\n- Use real databases in integration tests, not mocks (unless explicitly instructed otherwise).\n\n## Performance\n\n### C# / .NET\n\nThis is framework code, performance matters. Aim for zero allocations on hot paths.\n\n- Use `ChunkedArrayWriter` or `PooledArrayWriter` when you need an `IBufferWriter<byte>` for in-memory byte writing.\n\n## Tools\n\n### C# / .NET\n\nIf you need to search for packages on nuget.org, use the `dotnet` CLI, e.g. `dotnet package search HotChocolate`.\n\n### Profiling\n\nThe dev container has `dotnet-trace`, `dotnet-counters`, `dotnet-gcdump`, `dotnet-dump`, `dotnet-symbol`, `dottrace` and `dotmemory` installed. Versions are pinned in `.devcontainer/dockerfile`, and `docs/profiling.md` has the full commands and caveats. The tools attach to a running process in the same container. Write outputs to `perf/<label>-<git-short-sha>/`, which is gitignored.\n\n```bash\nOUT=perf/<label>-$(git rev-parse --short HEAD); mkdir -p \"$OUT\"\ndotnet-trace ps\ndotnet-trace collect -p <pid> --duration 00:00:00:30 --format speedscope -o \"$OUT/cpu.nettrace\"\ndotnet-trace report \"$OUT/cpu.nettrace\" topN -n 25 --inclusive\ndotnet-trace collect -p <pid> --profile gc-verbose --duration 00:00:00:15 -o \"$OUT/alloc.nettrace\"\ndotnet-gcdump collect -p <pid> -o \"$OUT/heap.gcdump\" && dotnet-gcdump report \"$OUT/heap.gcdump\" > \"$OUT/heap-report.txt\"\ndotnet-counters collect -p <pid> --format json -o \"$OUT/counters.json\" --duration 00:00:00:20 --counters System.Runtime,Microsoft.AspNetCore.Hosting,System.Net.Http\n```\n\n- Profile Release builds. Debug builds distort time and allocations.\n- Sampling gives time, not call counts. Call counts need dotTrace Tracing mode, which only `dottrace start` offers; `dottrace attach` is limited to Sampling and Timeline.\n- On Linux, EventPipe samples measure thread time. Ignore idle thread pool frames such as `LowLevelLifoSemaphore.WaitForSignal` and `WaitHandle.WaitOneNoCheck`.\n- `.dtp` (dotTrace) and `.dmw` (dotMemory) snapshots are for Rider on the host. Use the `dotnet-trace` and `dotnet-gcdump` outputs for analysis inside the container.\n\n### Nitro persisted operations (Fusion Aspire)\n\nAfter adding or editing any `.graphql` document under `src/HotChocolate/Fusion/src/Fusion.Aspire/Nitro/Operations`, regenerate the `.sha256` sidecars and verify them:\n\n```bash\n.github/scripts/nitro-aspire-operations.sh update \\\n    --source src/HotChocolate/Fusion/src/Fusion.Aspire/Nitro/Operations\n.github/scripts/nitro-aspire-operations.sh verify \\\n    --source src/HotChocolate/Fusion/src/Fusion.Aspire/Nitro/Operations \\\n    --output /tmp/nitro-aspire-operations.json\n```\n\nNever hand-write or hand-edit a `.sha256` sidecar. The `update` command is the only source of sidecar content, and `verify` must pass before handoff.\n\n## Components\n\n### All components\n\n#### Exceptions\n\nCreate exceptions through the `ThrowHelper` class of the project you are editing instead of inlining `throw new ...`. Each project keeps its own, which centralizes exception messages.\nExample: `src/HotChocolate/Fusion/src/Fusion.Execution/Execution/ThrowHelper.cs`\n\n#### GraphQL errors\n\nCreate GraphQL errors through the `ErrorHelper` class of the project you are editing instead of inlining `ErrorBuilder` calls. Each project keeps its own, which centralizes error messages.\nExample: `src/HotChocolate/AspNetCore/src/AspNetCore.Pipeline/Utilities/ErrorHelper.cs`\n\n### src/Fusion\n\n#### Execution nodes\n\nWhen you add a value to `ExecutionNodeType`, map it in two places:\n\n- `ExecutePlanNodeSpan.KindValues` in `src/HotChocolate/Fusion/src/Fusion.Diagnostics/Spans/ExecutePlanNodeSpan.cs`\n- `GraphQL.Operation.Step.KindValues` in `src/HotChocolate/Diagnostics/src/Diagnostics.Core/SemanticConventions.cs`, if the kind needs a new constant. Tag values are snake_case.\n\n`KindValues` supplies the `graphql.operation.step.kind` tag on the step span. An unmapped type does not fail execution. `ExecutePlanNodeSpan.Start` falls back to an untagged span, so the node silently loses its kind in traces. The guard test `StepSpan_Should_MapEveryExecutionNodeTypeToAKindValue` in `src/HotChocolate/Fusion/test/Fusion.Diagnostics.Tests/FusionActivityExecutionDiagnosticListenerTests.cs` fails until the mapping exists.\n\n#### Operation planner version\n\n`OperationPlanner.Version` identifies planning behavior and is independent of the package version. Bump the minor version when an existing operation can plan differently, the major version when consumers must react to a new plan structure. Refactors, performance work and fixes that cannot change a plan do not bump it.\n\n#### Operation plan JSON format\n\n`JsonOperationPlanFormatter` in `src/HotChocolate/Fusion/src/Fusion.Execution/Execution/Nodes/Serialization/JsonOperationPlanFormatter.cs` writes the plan document that tooling consumes. Its shape is published as a JSON schema, so any change to the emitted JSON is a two part change:\n\n1. Bump `JsonOperationPlanFormatter.FormatVersion`. It is written as the root `version` property and is the discriminator consumers pin against. Additive optional properties bump the minor version, anything that changes or removes an existing property bumps the major version.\n2. Add the matching variant to `website/public/schemas/fusion/operation-plan.json`, published at `https://chillicream.com/schemas/fusion/operation-plan.json`. Add a `#/$defs/<version>_plan` entry and the `allOf` branch that selects it for that root `version`, and list the new version in the root `version` enum. Every other definition is unprefixed and shared across versions. When a version changes one of them, fork only that definition to `<version>_<name>` and point the new plan at the fork, so a released version keeps validating exactly what it validated before.\n\nThe root `version` enum and the `allOf` branch that selects `v1_0_0_plan` are the pattern to copy: a new version adds one enum entry, one branch and one plan definition.\n\nThe internal `Format(IBufferWriter<byte>, Operation, ImmutableArray<ExecutionNode>)` overload feeds the SHA-256 that becomes `OperationPlan.Id`. It deliberately omits the `version` property, so leave it alone unless you intend to change every plan id.\n","isInternal":false,"tokens":2499,"sizeBytes":10730},{"name":"AGENTS.md","path":"website/AGENTS.md","rawUrl":"https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/website/AGENTS.md","title":"website - AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"<!-- BEGIN:nextjs-agent-rules -->\n\n# This is NOT the Next.js you know\n\nThis version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.\n\n<!-- END:nextjs-agent-rules -->\n\n# Authoring markdown content\n\nWhen creating or editing content under `content/docs/` or `content/blog/`, follow\nthe conventions in [README.md → Authoring Markdown Content](./README.md#authoring-markdown-content).\nIt covers frontmatter, `structure.yaml` sidebars, links, images, YouTube videos,\nadmonitions, Mermaid diagrams, and MDX gotchas.\n\nWhen creating or editing a video under `content/videos/`, also follow\n[README.md → Videos](./README.md#videos) for the file name and frontmatter.\n\n# Components\n\nThis site is built to be extended agent-first: adding a page or component should\nbe mechanical and consistent. Keep the quality bar high; do not cut corners\nbecause an agent is doing the work.\n\n## Where code lives\n\n- **Pages**: `app/` route segments. Content/marketing routes live under\n  `app/(content)/`. Keep page files thin: compose section components, do not\n  inline large markup.\n- **Reusable components**: `src/components/`, one component per file\n  (PascalCase filename).\n- **Design-system primitives** (Button, Input, Image, Typography, ...):\n  `src/design-system/`.\n- **Icons and inline SVG art**: `src/icons/`, one per file.\n- A component that is only a child of one parent and is not reused elsewhere may\n  live in the parent's file. As soon as it is reused or is independently\n  meaningful, move it to its own file under `src/components/`.\n\n## Props\n\n- Declare props as an `interface` named `<Component>Props`.\n- Every property is `readonly`.\n- Do **not** export the props interface; it is the component's own\n  implementation detail.\n\n```tsx\ninterface ButtonProps {\n  readonly label: string;\n  readonly onClick?: () => void;\n}\n\nexport function Button({ label, onClick }: ButtonProps) {\n  // ...\n}\n```\n\n## SVG and icons\n\n- Add SVGs as inline React components in `src/icons/` that return `<svg>…</svg>`\n  directly, so the markup is inlined into the HTML.\n- Do **not** add raw `.svg` files to `public/` to load via `<img>` / `Image`:\n  the image pipeline does not process SVG, and inlining lets icons inherit\n  `currentColor` and be sized/positioned with CSS.\n- Accept `className` (and `style` when the caller positions the icon). Default\n  decorative icons to `aria-hidden=\"true\"`.\n- If the SVG uses element ids (e.g. gradient ids), prefix them per icon so\n  several inlined icons on the same page do not collide.\n\n## Typography\n\nUse the type scale from `app/globals.css` (`@theme`): the `text-hero` /\n`text-h1`…`text-h6` / `text-lead` / `text-body` / `text-caption` utilities (each\nships its line-height), the `font-heading` / `font-body` families (Tailwind\n`font-sans` maps to the body voice), and the `.hero` / `.lead` / `.caption`\nhelper classes. Avoid ad-hoc `text-4xl`-style sizes for display headings.\n\n## Before you finish\n\n- Verify visually against the running dev server (`npm run dev`).\n- `npx eslint <changed files>` must pass.\n- `npm run format` must be run and `npm run format:check` must pass (Prettier\n  formatting, including Tailwind class sorting, is enforced in CI).\n","isInternal":false,"tokens":828,"sizeBytes":3341},{"name":"LICENSE-graphql-static-analysis-rs.md","path":"src/HotChocolate/CostAnalysis/tools/oracle/LICENSE-graphql-static-analysis-rs.md","rawUrl":"https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/src/HotChocolate/CostAnalysis/tools/oracle/LICENSE-graphql-static-analysis-rs.md","title":"Oracle Skill","category":"anthropic-skill","format":"markdown","content":"# License notice: graphql-static-analysis-rs\n\n`dump_corpus.rs` in this directory is built against, and the vendored\n`exact-case.json` corpus is generated from,\n[`graphql-static-analysis-rs`](https://github.com/duckki/graphql-static-analysis-rs)\nat commit `fec57fd7a980b5399637fa464a9bdce0781d91dd` (v0.2.0):\n\n```\nMIT License\n\nCopyright 2026 graphql-static-analysis contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n\n`oracle.patch` and `dump_corpus.rs` are original files written for this\nrepository; they are not derived from the crate's own source and are covered\nby this repository's own license.\n","isInternal":false,"tokens":352,"sizeBytes":1590},{"name":"authoring-skills.md","path":"website/content/docs/skills/authoring-skills.md","rawUrl":"https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/website/content/docs/skills/authoring-skills.md","title":"Skills Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: \"Authoring Skills\"\ndescription: \"Author Agent Skills with the `skills` CLI: scaffold a folder with `dnx skills init`, write the SKILL.md frontmatter and instructions, and publish through git.\"\n---\n\nPackage your team's conventions once, and any agent can pick them up. A skill is a folder with a `SKILL.md` file that tells an agent how to do something the way your team does it: your release checklist, your code review rules, your API client patterns. You write it once, push it to a git repo, and your teammates install it with one command. From then on, every agent they run loads that knowledge on demand, no copy-pasting prompts into each session.\n\nThis page teaches you to scaffold a skill, write a correct `SKILL.md`, add supporting files, and publish it so others can install it with [`dnx skills add`](./installing-skills.md). The skill format is the open [Agent Skills](https://agentskills.io/home) standard, so what you write here works across [55+ agents](./index.md), not only the one you author it in.\n\n# Scaffold a skill\n\n> Prerequisite: the .NET 10 SDK. See [Getting Started](./getting-started.md) before running the commands below.\n\nTo create a new skill in its own folder, run `dnx skills init` with a name.\n\n```shell\ndnx skills init my-skill\n```\n\n```text\nInitialized skill: my-skill\n\nCreated:\n  my-skill/SKILL.md\n\nNext steps:\n  1. Edit my-skill/SKILL.md to define your skill instructions\n  2. Update the name and description in the frontmatter\n\nPublishing:\n  GitHub: Push to a repo, then skills add <owner>/<repo>\n  URL:    Host the file, then skills add https://example.com/my-skill/SKILL.md\n```\n\nThis creates `my-skill/SKILL.md`. If everything worked, you have a folder named `my-skill` with one file inside it.\n\nTo scaffold a skill in the current directory instead, run `dnx skills init` with no name. The CLI derives the skill name from the folder you are in and writes `SKILL.md` next to your other files.\n\n```shell\ndnx skills init\n```\n\n```text\nInitialized skill: my-skill\n\nCreated:\n  SKILL.md\n\nNext steps:\n  1. Edit SKILL.md to define your skill instructions\n  2. Update the name and description in the frontmatter\n\nPublishing:\n  GitHub: Push to a repo, then skills add <owner>/<repo>\n  URL:    Host the file, then skills add https://example.com/my-skill/SKILL.md\n```\n\n`dnx skills init` never overwrites an existing skill. If `SKILL.md` is already present, it leaves your file untouched and tells you so.\n\n```text\nSkill already exists at my-skill/SKILL.md\n```\n\n## The generated template\n\n`dnx skills init` writes a spec-compliant starting point: the two required frontmatter fields, then a body with a heading and the sections most skills need.\n\n```markdown\n---\nname: my-skill\ndescription: A brief description of what this skill does\n---\n\n# my-skill\n\nInstructions for the agent to follow when this skill is activated.\n\n## When to use\n\nDescribe when this skill should be used.\n\n## Instructions\n\n1. First step\n2. Second step\n3. Additional steps as needed\n```\n\nReplace the placeholder `description`, then fill in the body. The next sections explain each part.\n\n# Structure a SKILL.md\n\nA `SKILL.md` has two parts: YAML frontmatter between `---` fences, and a Markdown body below it. The frontmatter is metadata the agent reads to decide whether your skill is relevant. The body is the instructions the agent follows once it decides to use the skill.\n\nThe \"Required frontmatter\" and \"Optional frontmatter\" subsections below are reference material: field-by-field constraint tables you can scan when you fill in the frontmatter. For the complete, authoritative field list see the [Reference](./reference.md).\n\n## Required frontmatter\n\nEvery skill needs `name` and `description`. The CLI skips any skill that is missing either field, so getting these right is the difference between a skill that installs and one that silently disappears.\n\n| Field         | Constraints                                                                                                                                                                                                                                               |\n| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `name`        | 1 to 64 characters. Lowercase letters, digits, and hyphens only. No leading or trailing hyphen. No consecutive hyphens. Should match the skill's folder name. Must not contain XML tags, and must not contain the reserved words `anthropic` or `claude`. |\n| `description` | 1 to 1024 characters. Must say BOTH what the skill does AND when to use it. Include specific trigger keywords that match the tasks where the skill applies. Must not contain XML tags.                                                                    |\n\nThe `description` is the single most important field you write. At startup the agent loads only your `name` and `description` (not the body), then matches the user's request against that description to decide whether to read the rest. A vague description means the agent never triggers your skill. Front-load what the skill does, then state the conditions that should activate it, and name the tools, file types, or commands involved.\n\n```markdown\n---\nname: release-checklist\ndescription: Runs our release checklist before publishing a NuGet package. Use when cutting a release, bumping a version, or preparing a package for nuget.org.\n---\n```\n\nThese constraints are the union of two authorities: the open spec at [agentskills.io/specification](https://agentskills.io/specification) (which adds the \"match the folder name\" and \"no consecutive hyphens\" rules) and the [Anthropic platform rules](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) (which add the reserved-word and XML-tag prohibitions). Honoring both keeps your skill portable across every agent.\n\n## Optional frontmatter\n\nAdd these fields only when you need them. The open spec at [agentskills.io/specification](https://agentskills.io/specification) is the authoritative field list; the most useful fields are below.\n\n| Field           | Purpose                                                                                                                                                                     |\n| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `license`       | A license name or a reference to a bundled license file. Keep it short.                                                                                                     |\n| `compatibility` | Up to 500 characters describing environment needs (intended product, system packages, network access). Most skills do not need it. Example: `Requires git, docker, and jq`. |\n| `metadata`      | A string-to-string map for client-defined properties the spec does not cover, such as `author` or `version`. Use distinctive key names to avoid collisions.                 |\n| `allowed-tools` | A space-separated list of pre-approved tools, for example `Bash(git:*) Read`.                                                                                               |\n\nFor the exhaustive list of frontmatter fields and their constraints, see the [Reference](./reference.md).\n\n> [!WARNING]\n> **`allowed-tools` is experimental.** Support varies between agents, and `dnx skills init` does not emit it. Treat it as a hint that some agents honor and others ignore, not a security boundary.\n\n## The instructions body\n\nThe body is plain Markdown the agent follows when your skill activates. There are no format restrictions, so write it the way you would brief a new teammate: step-by-step instructions, input and output examples, and the edge cases people get wrong.\n\nKeep `SKILL.md` focused. The recommendation from both [Anthropic](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) and the open spec is to keep the body under roughly 500 lines and move long detail into supporting files (see the next section). A tight body loads fast and keeps the agent on the steps that matter.\n\n# Add supporting files\n\nA skill folder can hold more than `SKILL.md`. Three conventional subdirectories cover most needs.\n\n```text\nmy-skill/\n├── SKILL.md          # Required: frontmatter + instructions\n├── references/       # Docs loaded on demand (REFERENCE.md, API.md, ...)\n├── scripts/          # Code the agent runs\n└── assets/           # Templates, data files, schemas\n```\n\nThe CLI copies or symlinks the whole folder as a unit, so every supporting file ships with the skill. (A few build artifacts are excluded automatically, including `.git`, `node_modules`, and `__pycache__`.)\n\nThese directories exist because of [progressive disclosure](./index.md#how-skills-load-progressive-disclosure): the agent loads your skill in stages so a large skill costs almost nothing until it is needed.\n\n- At startup the agent loads only `name` and `description`.\n- When the skill triggers, the agent reads the `SKILL.md` body.\n- A file under `references/`, `scripts/`, or `assets/` loads only when the body points the agent at it.\n\nThis is why moving detail out of `SKILL.md` and into `references/` is free: that material never enters the context window until the agent actually follows a link to it. Reference your supporting files with relative paths one level deep (for example `references/api.md`), and avoid deep nesting chains. For more on the three-stage model, see the [Introduction](./index.md#how-skills-load-progressive-disclosure) and [Anthropic's overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).\n\n# How installed skills are named\n\nWhen someone installs your skill, the CLI derives the on-disk directory name by sanitizing the `name` field. It lowercases the name, replaces every run of characters outside `a-z`, `0-9`, `.`, and `_` with a single hyphen, and trims leading and trailing dots and hyphens.\n\nFor a clean lowercase-hyphen name like `release-checklist`, the on-disk name is identical, with no surprises. A name with spaces or uppercase letters gets rewritten (`My Skill` becomes `my-skill`), which can mismatch what you and your teammates expect on disk and during removal. Pick a clean lowercase-hyphen name that already satisfies the [required frontmatter rules](#required-frontmatter), and the install name matches your folder name exactly.\n\n# Publish and install\n\nA skill is a folder in a git repo, so publishing is committing and pushing. Any repository the CLI can reach with git works.\n\nTo publish, commit your skill folder and push it to GitHub, GitLab, or any git remote. Then anyone installs it with `dnx skills add` pointed at the repo. The forms below show what an installer runs against your published skill; for the full add workflow, including expected output, scoping, and agent targeting, see [Installing Skills](./installing-skills.md).\n\n```shell\n# install every skill in the repo\ndnx skills add my-org/my-skills\n\n# install only one skill from a multi-skill repo\ndnx skills add my-org/my-skills@release-checklist\n\n# install a single SKILL.md hosted at a URL\ndnx skills add https://example.com/my-skill/SKILL.md\n```\n\nPrivate repositories work with no extra configuration. The CLI shells out to your own `git`, so it uses your existing credentials (SSH agent keys, a git credential helper, or `gh auth`). If you can `git clone` the repo, `skills` can install from it. When authentication fails, see [Troubleshooting](./troubleshooting.md).\n\nTo keep a work-in-progress skill out of default discovery, set `metadata.internal` to `true` in the frontmatter. The CLI hides internal skills unless the installer explicitly opts in (by filtering for the skill by name, or by setting the `INSTALL_INTERNAL_SKILLS` environment variable).\n\n```markdown\n---\nname: experimental-skill\ndescription: An in-progress skill. Use when testing new conventions before rollout.\nmetadata:\n  internal: \"true\"\n---\n```\n\n# Validate a skill\n\nTo check a skill against the open spec before you publish, use the reference validator `skills-ref` from the [agentskills/agentskills](https://github.com/agentskills/agentskills) repository. It validates your frontmatter and naming conventions.\n\n```shell\nskills-ref validate ./my-skill\n```\n\nIt reports a clean pass when the skill is valid, or names the offending field and rule when it is not (for example, an empty `description` or a `name` that breaks the naming rules).\n\nRunning it after `dnx skills init` and again before you push catches a malformed `name` or an empty `description` while it is still fast to fix, rather than discovering that the CLI skipped your skill on install.\n\n# Next steps\n\n- [Installing Skills](./installing-skills.md): install your published skill, target specific agents, and choose project or global scope.\n- [Reference](./reference.md): the complete command and flag surface, including `dnx skills init`.\n","frontmatter":{"title":"Authoring Skills","description":"Author Agent Skills with the `skills` CLI: scaffold a folder with `dnx skills init`, write the SKILL.md frontmatter and instructions, and publish through git."},"isInternal":false,"tokens":2791,"sizeBytes":13218},{"name":"getting-started.md","path":"website/content/docs/skills/getting-started.md","rawUrl":"https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/website/content/docs/skills/getting-started.md","title":"Skills Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: \"Getting Started\"\ndescription: \"Run the `skills` CLI with `dnx` and add your first Agent Skill to Claude Code or another AI coding agent in five minutes using `dnx skills add`.\"\n---\n\nBy the end of this guide you will have run `skills` and added your first skill to your agent.\n\n`skills` is a .NET CLI that installs, updates, and authors [Agent Skills](https://agentskills.io/home), the portable `SKILL.md` files that extend AI coding agents like Claude Code, Cursor, and GitHub Copilot. You point it at a source (a GitHub repo, a git URL, or a local folder), and it places the skill where your agent looks for it. Your agent then loads the skill on demand when a task matches it.\n\nThis page takes you from zero to one working skill. It takes about five minutes.\n\n# Prerequisites\n\nBefore you start, make sure you have the following:\n\n| Requirement                                                   | Why you need it                                                                                                                                                             |\n| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [.NET 10 SDK or newer](https://dotnet.microsoft.com/download) | To run `skills` with `dnx`, the way these docs show it. The `dnx` command ships with the .NET 10 SDK.                                                                       |\n| An AI coding agent                                            | The target for your skill. This guide uses [Claude Code](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview). The `skills` CLI supports 55+ agents. |\n\nThese docs run `skills` with `dnx`, so there is nothing to install first. If you would rather have `skills` on your `PATH`, install the global tool instead (it needs only the .NET SDK 8.0 or newer). See [Install as a global tool](#install-as-a-global-tool).\n\n# Run `skills`\n\nThese docs run `skills` with `dnx`, which needs no install. You can also install it as a global tool if you prefer `skills` on your `PATH`.\n\n## Run with dnx\n\n`dnx` ships with the .NET 10 SDK and runs a tool straight from NuGet, the way `npx` runs a package from npm. Nothing is installed up front.\n\n```shell\ndnx skills add anthropics/skills --agent claude-code\n```\n\nOn the first run, `dnx` prompts you to confirm the package download before it proceeds:\n\n```text\nTool package skills@<version> will be downloaded from source https://api.nuget.org/v3/index.json.\nProceed? [y/n] (y):\n```\n\nAfter you confirm, the install proceeds and prints the summary shown in [Add your first skill](#add-your-first-skill). The first run downloads the package into your NuGet cache; later runs reuse it and start immediately. `dnx skills` is shorthand for `dotnet tool exec skills`.\n\nTo skip the download prompt (for example in CI), pass `--yes`:\n\n```shell\ndnx --yes skills add anthropics/skills --agent claude-code\n```\n\nYou can control the `skills` version that `dnx` runs and where it fetches it from:\n\n| Command                                      | What it does                        |\n| -------------------------------------------- | ----------------------------------- |\n| `#!shell dnx skills@0.3.0 add ...`           | Runs an exact version.              |\n| `#!shell dnx skills@0.3.* add ...`           | Runs the latest 0.3.x version.      |\n| `#!shell dnx --prerelease skills add ...`    | Allows prerelease versions.         |\n| `#!shell dnx --source <feed> skills add ...` | Fetches from a specific NuGet feed. |\n\nIf your repository has a `.config/dotnet-tools.json` manifest that lists `skills`, `dnx` honors the pinned version from the manifest, which keeps one-shot runs consistent with the version your team committed.\n\n## Install as a global tool\n\nIf you would rather have `skills` on your `PATH`, install it as a global [.NET tool](https://learn.microsoft.com/dotnet/core/tools/global-tools). This needs the .NET SDK 8.0 or newer.\n\n```shell\ndotnet tool install -g skills\n```\n\n```text\nYou can invoke the tool using the following command: skills\nTool 'skills' (version '0.3.0') was successfully installed.\n```\n\nWith the global tool you run `skills` directly: drop the `dnx` prefix from every example in these docs (`dnx skills add ...` becomes `skills add ...`). Confirm the install with `skills --version`, which prints a value like `0.3.0+<git-sha>` (the trailing suffix records the exact commit the build came from).\n\nTo pin `skills` to a version your whole team shares, install it as a local tool through a manifest instead. From the repository root:\n\n```shell\ndotnet new tool-manifest\ndotnet tool install skills\n```\n\nLocal tools are restored with `dotnet tool restore` and run through `dotnet skills`. Check the manifest (`./.config/dotnet-tools.json`) into source control so every collaborator uses the same version.\n\n# Add your first skill\n\nYou are ready to install a skill. The example below installs skills from [anthropics/skills](https://github.com/anthropics/skills), Anthropic's reference repository, targeting Claude Code.\n\n```shell\ndnx skills add anthropics/skills --agent claude-code\n```\n\nAgent names are case-sensitive. Use `claude-code`, not `claude` or `Claude`. For GitHub Copilot the name is `github-copilot`.\n\nThe `skills` CLI fetches the source, discovers the skills, installs them, and prints a summary:\n\n```text\nSource: https://github.com/anthropics/skills.git\nFound 2 skill(s)\n\n┌─Installation Summary─────────────────────────────────────────────────────────┐\n│ Canonical: /your-project/.agents/skills                                      │\n│ Symlinked:  Claude Code                                                      │\n└──────────────────────────────────────────────────────────────────────────────┘\n┌─Installed 2 skill(s)─────────────────────────────────────────────────────────┐\n│ ✓ pdf                                                                        │\n│   → /your-project/.claude/skills/pdf                                         │\n│ ✓ docx                                                                       │\n│   → /your-project/.claude/skills/docx                                        │\n└──────────────────────────────────────────────────────────────────────────────┘\n\nDone!  Review skills before use; they run with full agent permissions.\n```\n\n> The trailing line is a deliberate safety nudge. A skill can include scripts that the agent runs with your agent's full permissions. Install skills only from sources you trust, and read a new skill before you use it.\n\nIf you omit `--agent`, the CLI runs interactively and lets you pick which agents to target from the ones it detects on your machine. To install only specific skills from a multi-skill source, add `--skill <name>` (repeatable). For the full set of source forms, scopes, and flags, see [Installing Skills](./installing-skills.md).\n\n**Checkpoint.** If everything worked, you should see the `Installed 2 skill(s)` panel and the `Done!` line, with no error. If you saw an `Invalid agents` panel, you misspelled the agent name (it is case-sensitive). If you saw `No valid skills found`, the source had no `SKILL.md` with both a `name` and a `description`. See [Troubleshooting](./troubleshooting.md) for more.\n\n# See what is installed\n\nTo confirm what landed in your project, list the installed skills:\n\n```shell\ndnx skills list\n```\n\n```text\nProject Skills\n\nSkill  Path                   Agents\npdf    ./.claude/skills/pdf   Claude Code\ndocx   ./.claude/skills/docx  Claude Code\n```\n\nThe table shows each skill's name, where it lives on disk, and the agents linked to it (shown by their display name, `Claude Code`). To list global skills instead, add `-g`. For machine-readable output, add `--json`.\n\n# Use the skill\n\nThe skill now lives where your agent looks for it. You do not need to do anything else.\n\nYour agent loads each installed skill's `name` and `description` at startup, then reads the full skill only when a task matches the description. This is [progressive disclosure](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview): the description is the trigger, and the body loads on demand. Start a task that matches the skill, and your agent picks it up automatically.\n\n# Update or remove the global tool\n\nIf you run `skills` with `dnx`, you never update it yourself: each run fetches the version you ask for. The commands below apply when you installed the global tool.\n\nTo update the global `skills` tool to the latest version:\n\n```shell\ndotnet tool update -g skills\n```\n\n```text\nTool 'skills' was successfully updated from version '0.3.0' to version '<new>'.\n```\n\nTo uninstall it:\n\n```shell\ndotnet tool uninstall -g skills\n```\n\n```text\nTool 'skills' (version '0.3.0') was successfully uninstalled.\n```\n\nNote that `dotnet tool update` updates the `skills` CLI, not your installed skills. To check your skills for updates, use the `dnx skills update` command, covered in [Installing Skills](./installing-skills.md).\n\n# Next steps\n\n- [Installing Skills](./installing-skills.md): every source form, project versus global scope, picking agents and skills, symlink versus copy, and checking for skill updates.\n- [Authoring Skills](./authoring-skills.md): scaffold a `SKILL.md` with `dnx skills init`, write a good description, and publish your skill.\n- [Reference](./reference.md): the complete command and flag surface.\n","frontmatter":{"title":"Getting Started","description":"Run the `skills` CLI with `dnx` and add your first Agent Skill to Claude Code or another AI coding agent in five minutes using `dnx skills add`."},"isInternal":false,"tokens":2139,"sizeBytes":10128},{"name":"index.md","path":"website/content/docs/skills/index.md","rawUrl":"https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/website/content/docs/skills/index.md","title":"Skills Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: Skills\nmetaTitle: \"Skills: Agent Skills CLI for .NET\"\ndescription: \"The `skills` .NET CLI installs, updates, and authors Agent Skills: portable SKILL.md files you can share across Claude Code, Cursor, and 55+ agents.\"\n---\n\n`skills` is the .NET CLI that installs, updates, and authors [Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills): portable `SKILL.md` files that teach an AI coding agent how you work. Stop re-explaining your conventions every session. Package the knowledge once, then hand the same skill to Claude Code, Cursor, GitHub Copilot, or another of the 55+ supported agents with a single command.\n\nRun it with `dnx`, which ships with the .NET 10 SDK, so there is nothing to install first:\n\n```shell\ndnx skills add anthropics/skills --agent claude-code\n```\n\n```text\nSource: https://github.com/anthropics/skills.git\nFound 2 skill(s)\n\n┌─Installation Summary─────────────────────────────────────────────────────────┐\n│ Canonical: /your-project/.agents/skills                                      │\n│ Symlinked:  Claude Code                                                      │\n└──────────────────────────────────────────────────────────────────────────────┘\n┌─Installed 2 skill(s)─────────────────────────────────────────────────────────┐\n│ ✓ pdf                                                                        │\n│   → /your-project/.claude/skills/pdf                                         │\n│ ✓ docx                                                                       │\n│   → /your-project/.claude/skills/docx                                        │\n└──────────────────────────────────────────────────────────────────────────────┘\n\nDone!  Review skills before use; they run with full agent permissions.\n```\n\nThe CLI detects the agents you have installed, then symlinks the skill into each one from a single canonical store. The agent loads the skill on its own when a task matches.\n\nThese docs show every command as `dnx skills`. Prefer `skills` on your `PATH`? Install the global tool with `#!shell dotnet tool install -g skills`, then drop the `dnx` prefix and run `skills` directly.\n\nNeed the prerequisites or a step-by-step walkthrough? See [Get started](./getting-started.md). The [source repository](https://github.com/ChilliCream/skills) and [`skills` package on NuGet](https://www.nuget.org/packages/skills) are public.\n\n# What are Agent Skills\n\nA skill is a folder with a single `SKILL.md` file. That file has YAML frontmatter (a `name` and a `description`) followed by a Markdown body of instructions. Optional subfolders carry supporting material the agent reads only when it needs it.\n\nThink of a skill as an onboarding guide for a new team member. You write down a procedure once (how to run your test suite, how your commit messages are formatted, which API your team prefers), and the agent references the relevant section when a task calls for it. A general-purpose agent becomes a specialist in your codebase without bespoke prompt engineering on every request.\n\nSkills differ from prompts. A prompt is conversation-level guidance you paste in for one task. A skill loads on demand across every conversation, so you never repaste the same instructions again.\n\nThe `SKILL.md` format is an open standard created by Anthropic and adopted across the ecosystem. The same file works in 55+ supported agents, including Claude Code, Cursor, and GitHub Copilot. To go deeper, read Anthropic's [Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) and the [open specification](https://agentskills.io/specification) at agentskills.io.\n\n# How skills load: progressive disclosure\n\nSkills stay out of the agent's context window until they are needed. The format loads in three levels, each at a different time. This is the single most important idea to understand, because it is why you can install many skills without paying a context penalty.\n\n| Level                 | What loads                                            | When                                    | Token cost            |\n| --------------------- | ----------------------------------------------------- | --------------------------------------- | --------------------- |\n| Level 1: Metadata     | The `name` and `description` from the frontmatter     | Always, at startup                      | ~100 tokens per skill |\n| Level 2: Instructions | The `SKILL.md` Markdown body                          | When the skill is triggered             | Keep under ~5k tokens |\n| Level 3: Resources    | Bundled files in `references/`, `scripts/`, `assets/` | On demand, when the body points to them | Effectively unlimited |\n\nAt startup the agent loads only each skill's `name` and `description`. The `description` is what the agent matches against your request to decide whether to activate the skill, so write it to describe both what the skill does and when to use it. When a request matches, the agent reads the full body. Bundled resources never enter context until the body references them, which is why supporting material can be effectively unbounded.\n\nThe open standard frames the same flow as Discovery, Activation, and Execution. For the full model, see Anthropic's [overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) and the [agentskills.io home page](https://agentskills.io/home).\n\n# What a skill looks like\n\nA skill is, at minimum, a folder containing one `SKILL.md` file. Everything else is optional and loaded only when referenced:\n\n```text\nmy-skill/\n├── SKILL.md       # Required: frontmatter (name + description) + Markdown instructions\n├── references/    # Optional: extra docs the agent reads on demand\n├── scripts/       # Optional: code the agent runs via the shell\n└── assets/        # Optional: templates, schemas, images, data files\n```\n\nThe folder name should match the `name` in the frontmatter. Here is a minimal, valid `SKILL.md` with the two required fields:\n\n```markdown\n---\nname: roll-dice\ndescription: Rolls one or more dice and returns the results. Use when the user asks to roll dice, flip for a decision, or pick a random number in a range.\n---\n\n# Roll dice\n\nWhen the user asks to roll dice, parse the count and number of sides (default to one six-sided die),\nthen return each roll and the total.\n```\n\nThe `dnx skills init` command scaffolds this layout for you; [Authoring Skills](./authoring-skills.md) walks through it with the generated `SKILL.md` and folder tree. The full field reference, including optional frontmatter, lives in the [open specification](https://agentskills.io/specification) and in [Authoring Skills](./authoring-skills.md).\n\n# Why Skills\n\nThe `skills` CLI brings the install-once, run-anywhere skill workflow to the .NET SDK. Three things make it worth adding to your toolbox.\n\nProject-scoped installs are recorded in a `skills-lock.json` file in your working directory. Commit it, and your whole team shares one reproducible skill set, the same way a lock file pins your package dependencies.\n\nOne install reaches every detected agent. The CLI materializes each skill once in a canonical store, then links it into the directory each installed agent expects. You do not manage per-agent copies by hand.\n\nPersonal skills install globally with `--global`. Those live outside any single project and follow you across every repository you work in.\n\n# The ecosystem\n\nThe Agent Skills world has three distinct layers. Knowing which is which helps you find what you need.\n\n| Layer         | What it is                                | Where                                                                                                             |\n| ------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| Format / spec | The open `SKILL.md` standard              | [agentskills.io](https://agentskills.io/specification), [anthropics/skills](https://github.com/anthropics/skills) |\n| Discovery     | A directory of published skills to browse | [skills.sh](https://www.skills.sh/)                                                                               |\n| Installers    | CLIs that fetch and install skills        | `skills` (.NET), [npx skills](https://github.com/vercel-labs/skills) (Node)                                       |\n\nThe `skills` CLI brings the [npx skills](https://github.com/vercel-labs/skills) workflow to the .NET SDK via `dnx`, so you can run it without a global install. The command surface deliberately mirrors what Node developers already know. The CLI has no registry of its own: you point `dnx skills add` at any git repository or local folder, and you discover skills to install from directories like [skills.sh](https://www.skills.sh/).\n\n# Next steps\n\n- [Get started](./getting-started.md): run `skills` and add your first skill end to end.\n- [Author a skill](./authoring-skills.md): scaffold a `SKILL.md`, write a strong description, and publish it.\n","frontmatter":{"title":"Skills","metaTitle":"Skills: Agent Skills CLI for .NET","description":"The `skills` .NET CLI installs, updates, and authors Agent Skills: portable SKILL.md files you can share across Claude Code, Cursor, and 55+ agents."},"isInternal":false,"tokens":1913,"sizeBytes":9719},{"name":"installing-skills.md","path":"website/content/docs/skills/installing-skills.md","rawUrl":"https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/website/content/docs/skills/installing-skills.md","title":"Skills Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: \"Installing Skills\"\ndescription: \"Install Agent Skills from GitHub repos, git URLs, or local folders with `dnx skills add`: the CLI finds every SKILL.md and wires it into your agents.\"\n---\n\n`dnx skills add` installs skills from a source into the AI coding agents you already have. Point it at a GitHub repository and the CLI discovers every `SKILL.md`, detects your agents, and wires the skill into each one.\n\n```shell\ndnx skills add anthropics/skills\n```\n\nThat single command fetches [Anthropic's reference skills](https://github.com/anthropics/skills), then either prompts you to choose which skills and agents you want or, when it is running inside an agent, installs non-interactively. This page walks the full lifecycle: choosing a source, narrowing to specific skills and agents, picking a scope, keeping skills current, and removing them.\n\nIf you have not installed the CLI yet, start with [Getting Started](./getting-started.md).\n\n> [!WARNING]\n> **Skills run with your agent's full permissions.** A skill is executable instructions plus optional scripts that your agent runs on your machine. Install only from sources you trust, and review a skill before you use it. After every successful install, `skills` reminds you: `Review skills before use; they run with full agent permissions.`\n\n# Choose a source\n\nThe `source` argument tells the CLI where to fetch skills from. It infers the kind of source from the string, so you pass one positional value and nothing else.\n\nThe most common form is a GitHub `owner/repo` shorthand:\n\n```shell\ndnx skills add anthropics/skills\n```\n\nEvery source form below is accepted. The first matching rule wins, and clones are always shallow (the CLI fetches only the latest commit, not the full history).\n\n| Source form            | Example                                                                      | What it does                                                              |\n| ---------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------- |\n| GitHub `owner/repo`    | `#!shell dnx skills add anthropics/skills`                                   | Installs from the repository root. The default shorthand.                 |\n| GitHub subpath         | `#!shell dnx skills add anthropics/skills/document-skills/pdf`               | Installs only the skill at that path in the repo.                         |\n| GitHub branch or tag   | `#!shell dnx skills add owner/repo#main`                                     | Installs from a specific ref (`#branch` or `#tag`).                       |\n| GitHub skill filter    | `#!shell dnx skills add owner/repo@my-skill`                                 | Installs only the skill named `my-skill` from the repo.                   |\n| GitHub URL             | `#!shell dnx skills add https://github.com/owner/repo`                       | Full URL, with or without a trailing `.git`.                              |\n| GitHub `tree` URL      | `#!shell dnx skills add https://github.com/owner/repo/tree/main/skills/foo`  | A `/tree/<ref>/<path>` URL pins the ref and subpath.                      |\n| GitLab shorthand       | `#!shell dnx skills add gitlab:group/project`                                | Installs from GitLab. Subgroups are supported (`group/subgroup/project`). |\n| GitLab URL             | `#!shell dnx skills add https://gitlab.com/group/project/-/tree/main/skills` | GitLab uses `/-/tree/` (note the `-` segment).                            |\n| Generic git or SSH     | `#!shell dnx skills add git@github.com:owner/repo.git`                       | Any `https`, `ssh://`, `git://`, or scp-style git transport.              |\n| Local directory        | `#!shell dnx skills add ./my-skills`                                         | A local path: `./`, `../`, an absolute path, or a Windows drive path.     |\n| Well-known HTTP(S) URL | `#!shell dnx skills add https://example.com/skills`                          | A non-git site that serves skills via `.well-known` discovery.            |\n\nA few notes that save time:\n\n- A bare name like `my-skills` (no `./` prefix) is treated as `owner/repo` shorthand, not a local path. Use `./my-skills` when you mean a local directory.\n- You can combine a ref and a skill filter: `owner/repo#main@my-skill`.\n- Any credentials embedded in a URL are stripped before they appear in output or in the lock file. The `Source:` line that the CLI prints shows `https://<redacted>@host/...`.\n\n> A well-known HTTP source fetches a `.well-known/agent-skills/index.json` (or `.well-known/skills/index.json`) discovery document from the site and downloads the listed skills. Every fetch is pinned to the same origin as the index, and indexes verify a SHA-256 digest per skill.\n\n# Choose which skills to install\n\nA source can contain many skills. By default, when you do not pass any filter, the CLI lists what it found and lets you select interactively. To narrow the set up front, use the options below.\n\nTo preview the available skills without installing anything, pass `--list` (or `-l`):\n\n```shell\ndnx skills add anthropics/skills --list\n```\n\n```text\nSource: https://github.com/anthropics/skills.git\nFound 2 skill(s)\n\nAvailable Skills\n  pdf\n    the pdf skill\n  docx\n    the docx skill\n\nUse --skill <name> to install specific skills\n```\n\nTo install one or more specific skills by name, pass `--skill` (or `-s`). The option is repeatable:\n\n```shell\ndnx skills add anthropics/skills --skill pdf --skill docx\n```\n\nYou can also embed a single skill filter in the source string with `@name`:\n\n```shell\ndnx skills add anthropics/skills@pdf\n```\n\nTo install every skill from the source into every detected agent, non-interactively, pass `--all`:\n\n```shell\ndnx skills add anthropics/skills --all\n```\n\nA successful run prints the `Installation Summary` and `Installed N skill(s)` panels followed by the safety reminder, the same shape shown under [How skills reach each agent](#how-skills-reach-each-agent).\n\n`--all` is a shortcut: it selects all skills, targets all agents, and skips every prompt.\n\nIf a `--skill` filter matches nothing, the CLI lists what was available so you can correct the name, and exits with a non-zero code:\n\n```text\nSource: /home/you/my-skills\nFound 2 skill(s)\nNo matching skills found for: nope\nAvailable skills:\n  alpha\n  beta\n```\n\nA skill is any folder that contains a `SKILL.md` with both a `name` and a `description`. If the source contains no valid skills, the CLI reports `No valid skills found. Skills require a SKILL.md with name and description.` and exits non-zero. See [Authoring Skills](./authoring-skills.md) for the format.\n\n# Choose which agents\n\nBy default, the CLI detects which agents are installed on your machine and targets them. To choose explicitly, pass `--agent` (or `-a`). The option is repeatable and accepts multiple values per token, and `*` means every supported agent:\n\n```shell\n# repeated flags\ndnx skills add anthropics/skills --agent claude-code --agent cursor\n\n# space-separated values in one token\ndnx skills add anthropics/skills --agent claude-code cursor\n\n# every supported agent\ndnx skills add anthropics/skills --agent \"*\"\n```\n\nA valid `--agent` run prints the `Installation Summary` and `Installed N skill(s)` panels shown under [How skills reach each agent](#how-skills-reach-each-agent), naming each agent that was linked or copied.\n\nThe CLI resolves the target agents like this:\n\n- **Running inside an agent.** When the CLI runs inside an agent (for example, when your agent invokes it for you), it goes non-interactive and targets that agent plus the shared store.\n- **Run from your shell, one agent installed.** The CLI auto-selects that agent plus the shared store.\n- **Run from your shell, several agents installed.** The CLI prompts you to choose, pre-selecting your last-used agents (or the common defaults `claude-code`, `codex`, `opencode` on a first run).\n- **`--agent` passed.** The CLI uses exactly what you specify, after validation.\n\nThese are the headline agent identifiers. Names are case-sensitive.\n\n| Agent          | `--agent` identifier |\n| -------------- | -------------------- |\n| Claude Code    | `claude-code`        |\n| Cursor         | `cursor`             |\n| GitHub Copilot | `github-copilot`     |\n| Codex          | `codex`              |\n| Continue       | `continue`           |\n| Gemini CLI     | `gemini-cli`         |\n| Windsurf       | `windsurf`           |\n\nThe `skills` CLI supports 55+ agents. For the complete list, plus the exact directory each agent installs into, see the [Reference](./reference.md).\n\nBecause identifiers are case-sensitive, `copilot` and `Claude-Code` are not valid. An invalid value fails fast and lists every valid name so you can copy the right one:\n\n```text\n┌─Invalid agents───────────────────────────────────────────────────────────────┐\n│ Invalid agents: bogus                                                        │\n│                                                                              │\n│ Valid agents: adal, aider-desk, amp, antigravity, augment, bob, claude-code, │\n│ cline, codearts-agent, codebuddy, codemaker, codestudio, codex,              │\n│ command-code, continue, cortex, crush, cursor, deepagents, devin, dexto,     │\n│ droid, firebender, forgecode, gemini-cli, github-copilot, goose,             │\n│ hermes-agent, iflow-cli, junie, kilo, kimi-cli, kiro-cli, kode, mcpjam,      │\n│ mistral-vibe, mux, neovate, openclaw, opencode, openhands, pi, pochi, qoder, │\n│ qwen-code, replit, roo, rovodev, tabnine-cli, trae, trae-cn, universal,      │\n│ warp, windsurf, zencoder                                                     │\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\n# Project and global scope\n\nThe CLI installs into one of two scopes. Understanding the difference tells you where skills live and who shares them.\n\n**Project scope is the default.** The CLI records the installed skills in a `skills-lock.json` file in your working directory and materializes the skill folders under `./.agents/skills`. Commit `skills-lock.json` so everyone who clones the repository shares the same skill set. This is the right scope for skills your whole team should use on a given project.\n\n**Global scope (`--global` or `-g`) installs skills for your user account**, across every project.\n\n```shell\ndnx skills add anthropics/skills --global\n```\n\nIn global scope the lock file lives at `~/.local/share/skills/.skill-lock.json` (honoring `XDG_DATA_HOME` if you set it), and the skill folders are materialized under `~/.agents/skills`.\n\nIn both scopes, the CLI materializes each skill once in a canonical store, then makes each targeted agent point at it.\n\n# How skills reach each agent\n\nBy default, the CLI writes each skill once into the canonical store and creates a symlink from every targeted agent's directory back to it. Editing the one canonical copy updates the skill for every agent at once, so you maintain a single source of truth.\n\n```mermaid\nflowchart LR\n  S[\"Source (repo, URL, or local path)\"] --> C[\"Canonical store (.agents/skills)\"]\n  C -. \"symlink\" .-> A1[\".claude/skills\"]\n  C -. \"symlink\" .-> A2[\".windsurf/skills\"]\n  C --> A3[\"Universal agents (.agents/skills is the store)\"]\n```\n\nSome agents read directly from the shared `.agents/skills` store, so their skills directory _is_ that store and no symlink is needed. The [Reference](./reference.md) lists which agents read from the shared store and the directory each agent installs into.\n\nTo copy files instead of symlinking, pass `--copy`. Use it for sandboxed agents that cannot follow symlinks (for example, agents running in containers where symlinks across mounts break):\n\n```shell\ndnx skills add anthropics/skills --copy --agent claude-code --agent windsurf\n```\n\nThe CLI also copies automatically in two cases, so you rarely need `--copy` by hand:\n\n- When a symlink cannot be created (for example, on Windows without the symlink privilege), the CLI falls back to copying for that agent.\n- When every targeted agent shares one skills directory, the CLI copies, because symlinking only makes sense across distinct directories.\n\nA successful install reports which agents were linked or copied and where each skill landed:\n\n```text\nSource: https://github.com/owner/skills.git\nFound 1 skill(s)\n\n┌─Installation Summary─────────────────────────────────────────────────────────┐\n│ Canonical: /your-project/.agents/skills/alpha                                │\n│ Symlinked:  Claude Code, Windsurf                                            │\n└──────────────────────────────────────────────────────────────────────────────┘\n┌─Installed 1 skill(s)─────────────────────────────────────────────────────────┐\n│ ✓ alpha                                                                      │\n│   → /your-project/.claude/skills/alpha                                       │\n└──────────────────────────────────────────────────────────────────────────────┘\n\nDone!  Review skills before use; they run with full agent permissions.\n```\n\nIf everything worked, you should see the `Installation Summary` panel followed by an `Installed N skill(s)` panel and the safety reminder. To confirm later, run `dnx skills list` (see the [Reference](./reference.md)).\n\n# Scan nested skills with --full-depth\n\nBy default, the CLI installs the skill at the source root if one exists there. If the root is not itself a skill, it discovers every nested skill instead. That fast path covers most repositories.\n\nTo find skills in nested and curated directories that the default scan does not reach, pass `--full-depth`:\n\n```shell\ndnx skills add owner/curated-skills --full-depth\n```\n\nThe install reports the same `Installation Summary` and `Installed N skill(s)` panels shown under [How skills reach each agent](#how-skills-reach-each-agent); only the set of discovered skills differs.\n\n`--full-depth` widens _discovery_: it scans nested directories and curated locations (such as `skills/.curated`) so the CLI finds skills the default scan would skip. It does not change clone depth. Clones are always shallow regardless of this flag.\n\n# Install from a private repository\n\nThe CLI never manages or prompts for credentials. It shells out to `git`, which uses your own setup: SSH agent keys, a git credential helper, `gh` authentication, or `~/.netrc`. To avoid hanging on a missing credential, it sets `GIT_TERMINAL_PROMPT=0`, so an unauthenticated clone fails fast with a clear error instead of waiting at a prompt.\n\nTo install from a private repository, make sure your normal git auth already works, then run `add` as usual:\n\n```shell\ndnx skills add owner/private-skills --agent claude-code\n```\n\nThis prints the same `Installation Summary` and `Installed N skill(s)` panels shown under [How skills reach each agent](#how-skills-reach-each-agent), once the clone authenticates.\n\nBefore you install, verify your access with one of:\n\n```shell\nssh -T git@github.com   # confirm your SSH key reaches GitHub\ngh auth login           # or authenticate the GitHub CLI\n```\n\nA working SSH key prints the well-known success line (GitHub closes the connection because it does not provide shell access):\n\n```text\nHi <user>! You've successfully authenticated, but GitHub does not provide shell access.\n```\n\nIf a clone fails with an authentication error, the CLI prints guidance pointing you back to your git credentials. See [Troubleshooting](./troubleshooting.md) for the full list of clone and auth failures.\n\n# Keep skills up to date\n\n`dnx skills update` checks your installed skills for newer versions. It has the aliases `upgrade` and `check`.\n\n```shell\ndnx skills update -g\n```\n\n```text\nChecking for skill updates...\n\nChecking global skill 1/1: my-skill\nFound 1 global update(s)\n\nUpdate available: my-skill\n  Run: skills add owner/repo/skills/my-skill -g -y\n\nUpdates available for 1 skill(s); no updates were applied.\n```\n\n**`update` only reports; it never applies changes.** It prints the exact `skills add ... -y` command to run for each skill that has an update (prefix it with `dnx` when you run through `dnx`). Copy that command and run it yourself to apply the update. The output is explicit: `no updates were applied.`\n\nScope the check the same way you scope an install:\n\n- `-g` (or `--global`) checks global skills only.\n- `-p` (or `--project`) checks project skills only.\n- Pass both, or name specific skills, to check both scopes.\n- With no scope flag in an interactive shell, the CLI prompts you to choose. Non-interactively (for example with `-y`), it checks both scopes.\n\nWhen there is nothing to update, you get a clean report:\n\n```text\nChecking for skill updates...\n\nChecking global skill 1/1: my-skill\nAll global skills are up to date\n```\n\nThe update check calls the GitHub API. If you hit a rate limit, set a `GITHUB_TOKEN` or `GH_TOKEN` environment variable (or sign in with `gh auth login`) and the CLI uses it for the check. See [Troubleshooting](./troubleshooting.md) for rate-limit and timeout details.\n\n# Remove skills\n\n`dnx skills remove` uninstalls skills. It unlinks each agent's copy and removes the canonical store entry once no remaining agent references it, then updates the lock file.\n\nTo remove specific skills by name, list them:\n\n```shell\ndnx skills remove alpha --yes\n```\n\n```text\nSuccessfully removed 1 skill(s)\n```\n\nTo remove everything, pass `--all`:\n\n```shell\ndnx skills remove --all\n```\n\n```text\nSuccessfully removed 1 skill(s)\n```\n\nTo limit removal to specific agents, add `--agent`. To target your user-level skills, add `--global`.\n\nRun `dnx skills remove` with no names to remove interactively: the CLI shows a multi-select prompt, then a confirmation that defaults to **no**. Declining cancels and removes nothing:\n\n```text\n$ dnx skills remove\n\nRemoval cancelled\n```\n\nIf a named skill is not installed, the CLI tells you and exits cleanly without changing anything:\n\n```text\nNo matching skills found for: nope\n```\n\n# Next steps\n\n- [Authoring Skills](./authoring-skills.md): write and publish your own `SKILL.md` with `dnx skills init`.\n- [Reference](./reference.md): every command, flag, the full list of 55+ agents, and per-agent install directories.\n- [Troubleshooting](./troubleshooting.md): clone failures, authentication errors, rate limits, and symlink fallbacks.\n","frontmatter":{"title":"Installing Skills","description":"Install Agent Skills from GitHub repos, git URLs, or local folders with `dnx skills add`: the CLI finds every SKILL.md and wires it into your agents."},"isInternal":false,"tokens":4221,"sizeBytes":19295},{"name":"reference.md","path":"website/content/docs/skills/reference.md","rawUrl":"https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/website/content/docs/skills/reference.md","title":"Skills Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: \"Reference\"\ndescription: \"Complete `skills` CLI reference covering every command and flag, JSON output, exit codes, environment variables, file locations, and supported agents.\"\n---\n\nThis page is the complete, precise reference for the `skills` command surface, JSON output, exit codes, environment variables, file locations, and supported agents. It is meant for lookup, not for learning. To learn by doing, start at [Installing Skills](./installing-skills.md) and [Authoring Skills](./authoring-skills.md).\n\nEvery command prints the same per-command help at the terminal. Run `dnx skills <command> --help` to see the synopsis, arguments, and options for that command.\n\n```shell\ndnx skills add --help\n```\n\n```text\nDescription:\n  Add a skill from a source\n\nUsage:\n  skills add [<source>] [options]\n\nArguments:\n  <source>  Source to fetch skills from (e.g., owner/repo, URL, local path)\n\nOptions:\n  -g, --global    Install globally\n  -a, --agent     Target agent(s)\n  -s, --skill     Skill name filter(s)\n  -y, --yes       Skip prompts (non-interactive)\n  --all           Install all skills to all agents\n  --copy          Copy instead of symlinking\n  --full-depth    Scan nested directories for skills\n  -l, --list      List available skills without installing\n  -?, -h, --help  Show help and usage information\n```\n\n> The binary on your PATH is `skills`. Install it with `#!shell dotnet tool install -g skills`, or run it without installing via `dnx skills <command>` (requires the .NET 10 SDK or later). Both forms accept the same commands, arguments, and options documented below.\n\n# Commands\n\n`skills` has five commands: `add`, `remove`, `list`, `update`, and `init`. Each command's options are independent. There are no shared global options beyond `--help` and `--version` (see [Global flags](#global-flags)).\n\n## skills add &lt;source&gt;\n\nAdd skills from a source. Skills are discovered at the source, then materialized into a canonical store and linked into each target agent's skills directory.\n\n```text\ndnx skills add <source> [options]\n```\n\n### Arguments\n\n| Argument | Arity | Required | Description                                                                                                                                                        |\n| -------- | ----- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `source` | one   | yes      | Source to fetch skills from (for example `owner/repo`, a full git URL, or a local path). If omitted, the command exits 1 with `Missing required argument: source`. |\n\n### Options\n\n| Option         | Alias  | Type                | Default         | Description                                                                                                                                                                                         |\n| -------------- | ------ | ------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--global`     | `-g`   | bool                | `false`         | Install to the global scope (your home directory) instead of the current project.                                                                                                                   |\n| `--agent`      | `-a`   | string (repeatable) | (auto-detected) | Target agent(s). Repeatable and space-separated (`--agent claude-code cursor` or `--agent claude-code --agent cursor`). `--agent *` targets every agent. See [Supported agents](#supported-agents). |\n| `--skill`      | `-s`   | string (repeatable) | (all)           | Install only skills whose name matches the given filter(s). Repeatable.                                                                                                                             |\n| `--yes`        | `-y`   | bool                | `false`         | Skip all prompts and run non-interactively.                                                                                                                                                         |\n| `--all`        | (none) | bool                | `false`         | Install all skills to all agents. Implies `--skill *`, `--agent *`, and `--yes`.                                                                                                                    |\n| `--copy`       | (none) | bool                | `false`         | Copy skill files into each agent directory instead of symlinking. Use for agents that do not follow symlinks.                                                                                       |\n| `--full-depth` | (none) | bool                | `false`         | Widen discovery to scan nested directories in the source, not only the source root. This does not change the git clone (clones are always shallow).                                                 |\n| `--list`       | `-l`   | bool                | `false`         | List the available skills at the source without installing anything, then exit.                                                                                                                     |\n\nThe default install mode is symlink: the CLI materializes each skill once into a canonical store and creates a relative symlink from each agent directory back to it. Pass `--copy` to copy instead. When every selected agent shares one skills directory, copy is used automatically.\n\nFor sources, scopes, and install mechanics, see [Installing Skills](./installing-skills.md). For agent targeting, see [Supported agents](#supported-agents).\n\n## skills remove [skills...]\n\nRemove installed skills. With no skill names and an interactive terminal, the CLI prompts you to select which skills to remove.\n\n```text\ndnx skills remove [skills...] [options]\n```\n\n### Arguments\n\n| Argument | Arity        | Required | Description                                                                                          |\n| -------- | ------------ | -------- | ---------------------------------------------------------------------------------------------------- |\n| `skills` | zero or more | no       | Skill names to remove. Matched case-insensitively. With no names and no `--all`, runs interactively. |\n\n### Options\n\n| Option     | Alias  | Type                | Default | Description                                                  |\n| ---------- | ------ | ------------------- | ------- | ------------------------------------------------------------ |\n| `--global` | `-g`   | bool                | `false` | Remove from the global scope instead of the current project. |\n| `--agent`  | `-a`   | string (repeatable) | (all)   | Limit removal to specific agent(s). Repeatable.              |\n| `--yes`    | `-y`   | bool                | `false` | Skip prompts and run non-interactively.                      |\n| `--all`    | (none) | bool                | `false` | Remove every installed skill.                                |\n\nIn interactive mode, the CLI shows a multiselect prompt followed by a confirmation prompt. The confirmation defaults to no. Declining the confirmation prints `Removal cancelled` and exits with code 130 (see [Exit codes](#exit-codes)).\n\n```text\n$ dnx skills remove alpha\n# exit 130\n\nRemoval cancelled\n```\n\n## skills list\n\nList installed skills. With no options, lists the current project's skills.\n\n```text\ndnx skills list [options]\n```\n\nThis command takes no positional arguments.\n\n### Options\n\n| Option     | Alias  | Type                | Default | Description                                                                           |\n| ---------- | ------ | ------------------- | ------- | ------------------------------------------------------------------------------------- |\n| `--global` | `-g`   | bool                | `false` | List skills in the global scope instead of the current project.                       |\n| `--agent`  | `-a`   | string (repeatable) | (none)  | Filter the listing to specific agent(s). Repeatable.                                  |\n| `--format` | (none) | `text` \\| `json`    | `text`  | Output format. `json` emits a JSON array to stdout (see [JSON output](#json-output)). |\n| `--json`   | (none) | bool                | `false` | Shorthand for `--format json`.                                                        |\n\nJSON output is enabled when either `--json` is present or `--format json` is set (case-insensitive). Enabling JSON suppresses the banner and writes the array to stdout.\n\n## skills update [skills...]\n\nCheck for available updates and print the exact command to apply each one.\n\n```text\ndnx skills update [skills...] [options]\n```\n\n> Aliases: `upgrade` and `check`. `dnx skills upgrade` and `dnx skills check` are identical to `dnx skills update`.\n\n> [!WARNING]\n> **`update` only reports.** It never modifies files or lock files. For each skill that has an update, it prints a `skills add ...` command you can copy and run to apply it (run it as `dnx skills add ...` if you use `dnx`). The command always exits 0, even when updates are available. Its output ends with `no updates were applied.`\n\n### Arguments\n\n| Argument | Arity        | Required | Description                                                                                                        |\n| -------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------ |\n| `skills` | zero or more | no       | Optional skill names to check. Scope is resolved the same way with or without names (see the scope options below). |\n\n### Options\n\n| Option      | Alias | Type | Default | Description                                                                |\n| ----------- | ----- | ---- | ------- | -------------------------------------------------------------------------- |\n| `--global`  | `-g`  | bool | `false` | Check global skills only.                                                  |\n| `--project` | `-p`  | bool | `false` | Check project skills only.                                                 |\n| `--yes`     | `-y`  | bool | `false` | Skip the interactive scope prompt. Non-interactive runs check both scopes. |\n\nWith neither `-g` nor `-p`, an interactive terminal prompts you to choose Project, Global, or Both. Passing both flags, or running non-interactively, checks both scopes.\n\n```text\n$ dnx skills update -g\n\nChecking for skill updates...\n\nChecking global skill 1/1: my-skill\nFound 1 global update(s)\n\nUpdate available: my-skill\n  Run: skills add owner/repo/skills/my-skill -g -y\n\nUpdates available for 1 skill(s); no updates were applied.\n```\n\n## skills init [name]\n\nScaffold a new skill directory containing a `SKILL.md` template. This command has no options.\n\n```text\ndnx skills init [name]\n```\n\n### Arguments\n\n| Argument | Arity       | Required | Description                                                                                                                                                       |\n| -------- | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `name`   | zero or one | no       | Skill name. Creates `<name>/SKILL.md`. The name is sanitized to a slug. With no name, derives the slug from the current directory and writes `SKILL.md` in place. |\n\nIf the target `SKILL.md` already exists, the CLI does not overwrite it. It prints `Skill already exists at <path>` and exits 0.\n\n```text\n$ dnx skills init my-skill\n\nInitialized skill: my-skill\n\nCreated:\n  my-skill/SKILL.md\n\nNext steps:\n  1. Edit my-skill/SKILL.md to define your skill instructions\n  2. Update the name and description in the frontmatter\n\nPublishing:\n  GitHub: Push to a repo, then skills add <owner>/<repo>\n  URL:    Host the file, then skills add https://example.com/my-skill/SKILL.md\n```\n\nSee [Authoring Skills](./authoring-skills.md) for the `SKILL.md` format and publishing workflow.\n\n## Global flags\n\nThese are provided on the root command and on every subcommand.\n\n| Option      | Aliases    | Type | Description                                            |\n| ----------- | ---------- | ---- | ------------------------------------------------------ |\n| `--help`    | `-h`, `-?` | bool | Show help. On a subcommand, shows that command's help. |\n| `--version` | (none)     | bool | Print the installed CLI version and exit 0.            |\n\nRunning `skills` with no arguments shows the banner and exits 0. Running `#!shell dnx skills --help` shows curated top-level help. A bare `--` token is removed before parsing, so `#!shell dnx skills add --agent codex -- owner/repo` parses the same as without it.\n\n# JSON output\n\n`#!shell dnx skills list --json` (equivalently `#!shell dnx skills list --format json`) prints a JSON array to stdout. Each element describes one installed skill.\n\n```shell\ndnx skills list --json\n```\n\n```json\n[\n  {\n    \"name\": \"alpha\",\n    \"path\": \"/home/you/project/.agents/skills/alpha\",\n    \"scope\": \"project\",\n    \"agents\": [\"Claude Code\", \"Windsurf\"]\n  }\n]\n```\n\n| Field    | Type     | Description                                                                                                                |\n| -------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |\n| `name`   | string   | The skill's sanitized name (its on-disk directory name).                                                                   |\n| `path`   | string   | Absolute path to the skill in the canonical store.                                                                         |\n| `scope`  | string   | `\"project\"` or `\"global\"`. `\"global\"` when listed with `-g`, otherwise `\"project\"`.                                        |\n| `agents` | string[] | Display names of agents linked to this skill (for example `Claude Code`). Empty when the skill is not linked to any agent. |\n\nThe array is written to stdout, so you can pipe it to a tool such as `jq`. Banner and progress output are suppressed in JSON mode.\n\n# Exit codes\n\n`skills` uses exactly three exit codes.\n\n| Code  | Name      | Meaning                                                                                                                                        |\n| ----- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| `0`   | Success   | The command completed. Note that `update` exits 0 even when updates are available, and `remove` exits 0 when there is nothing to remove.       |\n| `1`   | Failure   | The command failed (for example an invalid agent name, no valid skills found, or a file system error). The error message is written to stderr. |\n| `130` | Cancelled | The operation was cancelled, either by declining an interactive confirmation or by pressing Ctrl+C.                                            |\n\n# Environment variables\n\n| Variable                  | Default          | Effect                                                                                                                                                            |\n| ------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `SKILLS_CLONE_TIMEOUT_MS` | `300000`         | Git clone timeout in milliseconds (5 minutes). Must parse to a positive integer, otherwise the default is used. Raise it for large repositories or slow networks. |\n| `GITHUB_TOKEN`            | (unset)          | A GitHub API token. Used only by `update` to raise GitHub API rate limits when checking for updates. Not used for cloning.                                        |\n| `GH_TOKEN`                | (unset)          | Fallback GitHub API token. Consulted by `update` after `GITHUB_TOKEN`. Same effect.                                                                               |\n| `INSTALL_INTERNAL_SKILLS` | (unset)          | Set to `1` or `true` to include skills their authors marked as internal in discovery. By default such skills are hidden.                                          |\n| `CLAUDE_CONFIG_DIR`       | `~/.claude`      | Overrides the Claude Code configuration directory used for detection and global installs.                                                                         |\n| `CODEX_HOME`              | `~/.codex`       | Overrides the Codex configuration directory used for detection and global installs.                                                                               |\n| `VIBE_HOME`               | `~/.vibe`        | Overrides the Mistral Vibe configuration directory used for detection and global installs.                                                                        |\n| `XDG_DATA_HOME`           | `~/.local/share` | Root for the global lock location. The global lock lives at `$XDG_DATA_HOME/skills/.skill-lock.json`.                                                             |\n\n`XDG_CONFIG_HOME` (default `~/.config`) and `XDG_STATE_HOME` (default `~/.local/state`) affect where the CLI keeps its own configuration and logs, and where several agents resolve their global directories.\n\nFor private repositories, the CLI shells out to `git` and uses your existing git credentials (SSH agent, credential helper, `gh` auth). See [Troubleshooting](./troubleshooting.md) for authentication and rate-limit guidance.\n\n# File locations\n\nThe CLI writes a lock file per scope and materializes skills into a canonical store. Project scope is the current working directory; global scope is your home directory.\n\n| Scope   | Lock file                                                                              | Canonical skills store |\n| ------- | -------------------------------------------------------------------------------------- | ---------------------- |\n| Project | `skills-lock.json` (in the current working directory)                                  | `./.agents/skills`     |\n| Global  | `~/.local/share/skills/.skill-lock.json` (or `$XDG_DATA_HOME/skills/.skill-lock.json`) | `~/.agents/skills`     |\n\nNon-universal agents receive a symlink from their own directory (for example `.claude/skills/<name>`) back into the canonical store. Universal agents use the canonical store directly. See [Supported agents](#supported-agents) for per-agent directories.\n\n# Supported agents\n\nThe `skills` CLI supports 55+ agents. It detects which agents are installed on your machine by probing each agent's configuration directory, and it detects which agent it is running inside by reading environment variables that agent hosts set. When run inside a detected agent, `add` runs non-interactively and targets that agent plus the universal agents.\n\nAgent identifiers are case-sensitive (the identifier is `github-copilot`, not `copilot`). The `--agent` option is repeatable and accepts multiple values per token. `--agent *` targets all agents. \"Universal\" agents share the `.agents/skills` store, so installing a skill for one universal agent makes it visible to all of them.\n\nIn the table below, project directories are relative to the working directory and global directories are absolute (`~` is your home directory, `<config>` is `$XDG_CONFIG_HOME` or `~/.config`). Agents marked \"universal\" use the shared `.agents/skills` store at project scope.\n\n| Identifier       | Display name       | Project directory            | Global directory                             |\n| ---------------- | ------------------ | ---------------------------- | -------------------------------------------- |\n| `adal`           | AdaL               | `.adal/skills`               | `~/.adal/skills`                             |\n| `aider-desk`     | AiderDesk          | `.aider-desk/skills`         | `~/.aider-desk/skills`                       |\n| `amp`            | Amp                | `.agents/skills` (universal) | `<config>/agents/skills`                     |\n| `antigravity`    | Antigravity        | `.agents/skills` (universal) | `~/.gemini/antigravity/skills`               |\n| `augment`        | Augment            | `.augment/skills`            | `~/.augment/skills`                          |\n| `bob`            | IBM Bob            | `.bob/skills`                | `~/.bob/skills`                              |\n| `claude-code`    | Claude Code        | `.claude/skills`             | `~/.claude/skills` (via `CLAUDE_CONFIG_DIR`) |\n| `cline`          | Cline              | `.agents/skills` (universal) | `~/.agents/skills`                           |\n| `codearts-agent` | CodeArts Agent     | `.codeartsdoer/skills`       | `~/.codeartsdoer/skills`                     |\n| `codebuddy`      | CodeBuddy          | `.codebuddy/skills`          | `~/.codebuddy/skills`                        |\n| `codemaker`      | Codemaker          | `.codemaker/skills`          | `~/.codemaker/skills`                        |\n| `codestudio`     | Code Studio        | `.codestudio/skills`         | `~/.codestudio/skills`                       |\n| `codex`          | Codex              | `.agents/skills` (universal) | `~/.codex/skills` (via `CODEX_HOME`)         |\n| `command-code`   | Command Code       | `.commandcode/skills`        | `~/.commandcode/skills`                      |\n| `continue`       | Continue           | `.continue/skills`           | `~/.continue/skills`                         |\n| `cortex`         | Cortex Code        | `.cortex/skills`             | `~/.snowflake/cortex/skills`                 |\n| `crush`          | Crush              | `.crush/skills`              | `~/.config/crush/skills`                     |\n| `cursor`         | Cursor             | `.agents/skills` (universal) | `~/.cursor/skills`                           |\n| `deepagents`     | Deep Agents        | `.agents/skills` (universal) | `~/.deepagents/agent/skills`                 |\n| `devin`          | Devin for Terminal | `.devin/skills`              | `<config>/devin/skills`                      |\n| `dexto`          | Dexto              | `.agents/skills` (universal) | `~/.agents/skills`                           |\n| `droid`          | Droid              | `.factory/skills`            | `~/.factory/skills`                          |\n| `firebender`     | Firebender         | `.agents/skills` (universal) | `~/.firebender/skills`                       |\n| `forgecode`      | ForgeCode          | `.forge/skills`              | `~/.forge/skills`                            |\n| `gemini-cli`     | Gemini CLI         | `.agents/skills` (universal) | `~/.gemini/skills`                           |\n| `github-copilot` | GitHub Copilot     | `.agents/skills` (universal) | `~/.copilot/skills`                          |\n| `goose`          | Goose              | `.goose/skills`              | `<config>/goose/skills`                      |\n| `hermes-agent`   | Hermes Agent       | `.hermes/skills`             | `~/.hermes/skills`                           |\n| `iflow-cli`      | iFlow CLI          | `.iflow/skills`              | `~/.iflow/skills`                            |\n| `junie`          | Junie              | `.junie/skills`              | `~/.junie/skills`                            |\n| `kilo`           | Kilo Code          | `.kilocode/skills`           | `~/.kilocode/skills`                         |\n| `kimi-cli`       | Kimi Code CLI      | `.agents/skills` (universal) | `~/.config/agents/skills`                    |\n| `kiro-cli`       | Kiro CLI           | `.kiro/skills`               | `~/.kiro/skills`                             |\n| `kode`           | Kode               | `.kode/skills`               | `~/.kode/skills`                             |\n| `mcpjam`         | MCPJam             | `.mcpjam/skills`             | `~/.mcpjam/skills`                           |\n| `mistral-vibe`   | Mistral Vibe       | `.vibe/skills`               | `~/.vibe/skills` (via `VIBE_HOME`)           |\n| `mux`            | Mux                | `.mux/skills`                | `~/.mux/skills`                              |\n| `neovate`        | Neovate            | `.neovate/skills`            | `~/.neovate/skills`                          |\n| `openclaw`       | OpenClaw           | `skills`                     | `~/.openclaw/skills`                         |\n| `opencode`       | OpenCode           | `.agents/skills` (universal) | `<config>/opencode/skills`                   |\n| `openhands`      | OpenHands          | `.openhands/skills`          | `~/.openhands/skills`                        |\n| `pi`             | Pi                 | `.pi/skills`                 | `~/.pi/agent/skills`                         |\n| `pochi`          | Pochi              | `.pochi/skills`              | `~/.pochi/skills`                            |\n| `qoder`          | Qoder              | `.qoder/skills`              | `~/.qoder/skills`                            |\n| `qwen-code`      | Qwen Code          | `.qwen/skills`               | `~/.qwen/skills`                             |\n| `replit`         | Replit             | `.agents/skills` (universal) | `<config>/agents/skills`                     |\n| `roo`            | Roo Code           | `.roo/skills`                | `~/.roo/skills`                              |\n| `rovodev`        | Rovo Dev           | `.rovodev/skills`            | `~/.rovodev/skills`                          |\n| `tabnine-cli`    | Tabnine CLI        | `.tabnine/agent/skills`      | `~/.tabnine/agent/skills`                    |\n| `trae`           | Trae               | `.trae/skills`               | `~/.trae/skills`                             |\n| `trae-cn`        | Trae CN            | `.trae/skills`               | `~/.trae-cn/skills`                          |\n| `universal`      | Universal          | `.agents/skills` (universal) | `<config>/agents/skills`                     |\n| `warp`           | Warp               | `.agents/skills` (universal) | `~/.agents/skills`                           |\n| `windsurf`       | Windsurf           | `.windsurf/skills`           | `~/.codeium/windsurf/skills`                 |\n| `zencoder`       | Zencoder           | `.zencoder/skills`           | `~/.zencoder/skills`                         |\n\nPassing an unknown identifier exits 1 and prints the full list of valid identifiers:\n\n```text\n$ dnx skills add ./local-path --yes --agent bogus\n# exit 1\n\nInvalid agents: bogus\n```\n\n# See also\n\n- [Installing Skills](./installing-skills.md): sources, scopes, and the install workflow in depth.\n- [Authoring Skills](./authoring-skills.md): the `SKILL.md` format, `dnx skills init`, and publishing.\n- [Troubleshooting](./troubleshooting.md): authentication, rate limits, timeouts, and common errors.\n","frontmatter":{"title":"Reference","description":"Complete `skills` CLI reference covering every command and flag, JSON output, exit codes, environment variables, file locations, and supported agents."},"isInternal":false,"tokens":5596,"sizeBytes":27102},{"name":"structure.yaml","path":"website/content/docs/skills/structure.yaml","rawUrl":"https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/website/content/docs/skills/structure.yaml","title":"Skills Skill","category":"anthropic-skill","format":"yaml","content":"title: Skills\nitems:\n  - path: index\n    title: Introduction\n  - path: getting-started\n    title: Getting Started\n  - path: installing-skills\n    title: Installing Skills\n  - path: authoring-skills\n    title: Authoring Skills\n  - path: reference\n    title: Reference\n  - path: troubleshooting\n    title: Troubleshooting\n","isInternal":false,"tokens":85,"sizeBytes":320},{"name":"troubleshooting.md","path":"website/content/docs/skills/troubleshooting.md","rawUrl":"https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/website/content/docs/skills/troubleshooting.md","title":"Skills Skill","category":"anthropic-skill","format":"markdown","content":"---\ntitle: \"Troubleshooting\"\ndescription: \"Troubleshoot `skills` CLI errors: each section maps the exact message the CLI prints to its cause and a copy-pasteable fix for installing and updating skills.\"\n---\n\nThis page maps the errors and surprises you hit when running `skills` to their cause and fix. Each section starts with the exact message the CLI prints (where one exists), explains why it happens, and gives you a copy-pasteable way out.\n\nIf you are new to `skills`, start with [Getting Started](./getting-started.md). For the full command and flag surface, see the [Reference](./reference.md). For what each agent identifier means and where skills land, see [Installing Skills](./installing-skills.md).\n\n# \"No valid skills found. Skills require a SKILL.md with name and description.\"\n\nYou ran `dnx skills add <source>` and the CLI reached the source but found nothing to install:\n\n```text\n$ dnx skills add ./my-skills --yes --agent claude-code\n# exit 1\n\nSource: /home/you/my-skills\nNo valid skills found. Skills require a SKILL.md with name and description.\n```\n\nCause: a skill is a directory that contains a `SKILL.md` file with both `name` and `description` in its YAML frontmatter. The CLI silently skips any folder that is missing the file, missing either field, or whose `name`/`description` collapses to empty. By default, it only looks at the source root (or the subpath you pointed it at), so a `SKILL.md` buried in a nested directory is not discovered.\n\nTo see exactly what the CLI finds without installing anything, run `--list`:\n\n```shell\ndnx skills add owner/repo --list\n```\n\n```text\nSource: https://github.com/owner/repo.git\nFound 2 skill(s)\n\nAvailable Skills\n  alpha\n    the alpha skill\n  beta\n    the beta skill\n\nUse --skill <name> to install specific skills\n```\n\nIf `--list` reports `Found 0 skill(s)`, work through these in order:\n\n| Check                                                     | Fix                                                                                                                            |\n| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| Is your path or subpath pointing at the right folder?     | Point at the directory that contains `SKILL.md`, or add the repo subpath: `#!shell dnx skills add owner/repo/skills/my-skill`. |\n| Does the `SKILL.md` have both `name:` and `description:`? | Add the missing field. Both must be non-empty. See [Authoring Skills](./authoring-skills.md).                                  |\n| Are the skills in nested directories?                     | Add `--full-depth` to scan nested directories: `#!shell dnx skills add owner/repo --full-depth --list`.                        |\n\n> `--full-depth` widens discovery so the CLI scans nested directories for skills. It does not change how much of the repository is cloned. Clones are always shallow regardless of this flag.\n\n# \"Invalid agents: &lt;name&gt;\"\n\nYou passed an `--agent` value that the CLI does not recognize:\n\n```text\n$ dnx skills add ./my-skills --yes --agent bogus\n# exit 1\n\nSource: /home/you/my-skills\nFound 1 skill(s)\n\n┌─Invalid agents───────────────────────────────────────────────────────────────┐\n│ Invalid agents: bogus                                                        │\n│                                                                              │\n│ Valid agents: adal, aider-desk, amp, antigravity, augment, bob, claude-code, │\n│ cline, codearts-agent, codebuddy, codemaker, codestudio, codex,              │\n│ command-code, continue, cortex, crush, cursor, deepagents, devin, dexto,     │\n│ droid, firebender, forgecode, gemini-cli, github-copilot, goose,             │\n│ hermes-agent, iflow-cli, junie, kilo, kimi-cli, kiro-cli, kode, mcpjam,      │\n│ mistral-vibe, mux, neovate, openclaw, opencode, openhands, pi, pochi, qoder, │\n│ qwen-code, replit, roo, rovodev, tabnine-cli, trae, trae-cn, universal,      │\n│ warp, windsurf, zencoder                                                     │\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\nCause: the value is misspelled or uses the wrong case. Agent identifiers are case-sensitive, and several differ from the product's marketing name. The most common mistakes:\n\n| You typed                   | Use instead      |\n| --------------------------- | ---------------- |\n| `copilot`, `github_copilot` | `github-copilot` |\n| `Claude-Code`, `claude`     | `claude-code`    |\n| `gemini`                    | `gemini-cli`     |\n| `roo-code`                  | `roo`            |\n\nThe error panel always prints every valid identifier, so copy the correct one from the list. The same `Invalid agents: <name>` message appears (without the panel) from `dnx skills list` and `dnx skills remove`. For the full table of identifiers and where each one installs skills, see [Installing Skills](./installing-skills.md) and the [Reference](./reference.md).\n\n# Cloning a private repository fails with \"Authentication failed\"\n\n`dnx skills add` reports an authentication error and stops before installing.\n\nCause: the CLI never prompts for credentials. It shells out to your own `git`, which uses your existing setup (SSH agent keys, a git credential helper, `gh` auth, or `~/.netrc`). When git cannot authenticate, the CLI surfaces the failure instead of hanging. Any credentials embedded in a URL are redacted from the output, so secrets never appear in errors or in the lock file.\n\nTo fix it, confirm your machine can reach the repository, then retry the same `dnx skills add` command.\n\nFor SSH sources (`git@github.com:owner/repo.git`):\n\n```shell\nssh -T git@github.com\n# Hi <you>! You've successfully authenticated, but GitHub does not provide shell access.\n```\n\nFor HTTPS sources, authenticate with the GitHub CLI or configure a git credential helper. These are one-time setup commands whose output varies by environment:\n\n```shell\ngh auth login                         # uses the gh credential helper\n# or\ngit config --global credential.helper store\n```\n\nAfter `gh auth login` completes, it confirms the authenticated account.\n\nOnce `git clone <repo>` succeeds on its own, `dnx skills add <repo>` will succeed too.\n\n# The clone times out\n\nA large repository can exceed the default clone budget and cause the CLI to abort the fetch.\n\nCause: the CLI caps each clone at 5 minutes (300000 ms). The clone is always shallow (latest commit only), but a very large repository or a slow connection can still run past the limit.\n\nTo raise the timeout, set `SKILLS_CLONE_TIMEOUT_MS` in milliseconds before running the command:\n\n```shell\nSKILLS_CLONE_TIMEOUT_MS=600000 dnx skills add owner/big-repo --agent claude-code   # 10 minutes\n```\n\nWith the longer budget the clone finishes and the install completes with the usual `Installed 1 skill(s)` panel.\n\nAlternatively, clone the repository yourself and point `skills` at the local copy. This skips the network step entirely:\n\n```shell\ngit clone --depth 1 https://github.com/owner/big-repo.git\ndnx skills add ./big-repo --agent claude-code\n```\n\nPointing `skills` at the local clone installs the skill without touching the network and prints the same `Installed 1 skill(s)` panel.\n\n# A skill does not appear for one agent\n\n`dnx skills add` reports success, the skill shows up in `dnx skills list`, but one of your agents does not see it.\n\nCause: agents that keep skills in their own directory (for example `.claude/skills` for Claude Code or `.windsurf/skills` for Windsurf) only get a link when that agent's directory already exists in your project. The CLI will not create a config directory for an agent you do not use. When the directory is missing, it skips the link for that agent but still materializes the skill in the shared `.agents/skills` store, so the skill is installed; it is only the per-agent link that is missing.\n\nPick whichever fix matches your intent:\n\n| Goal                                                           | Fix                                                                                                                                   |\n| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |\n| You do use that agent in this project                          | Create its directory, then re-run the install: `#!shell mkdir -p .claude && dnx skills add owner/repo --agent claude-code`.           |\n| You want a self-contained copy regardless of agent directories | Add `--copy` to write the skill straight into each agent's directory: `#!shell dnx skills add owner/repo --agent claude-code --copy`. |\n| You meant a different agent                                    | Re-run with the correct `--agent` value. See [Installing Skills](./installing-skills.md).                                             |\n\nAfter the directory exists, re-running the install links the skill into `.claude/skills`. The Installation Summary then lists `Symlinked:  Claude Code` instead of skipping that agent.\n\nAgents that share the universal `.agents/skills` store (Cursor, Codex, GitHub Copilot, Gemini CLI, and others) always see the skill because their directory is the canonical store.\n\n# Symlinks are not created (Windows)\n\nOn Windows, `skills` copies skills into agent directories instead of linking them.\n\nCause: creating a symlink on Windows requires either an elevated process or Developer Mode. When the CLI cannot create the link, it automatically falls back to copying the skill so the install still succeeds. The skill works either way; the only difference is that copies do not share a single editable source of truth the way symlinks do.\n\nTo get symlinks instead of copies, choose one:\n\n- Enable Developer Mode (Settings, \"For developers\", \"Developer Mode\"), then re-run the command.\n- Run your terminal elevated (\"Run as administrator\") and re-run the command.\n\nIf you prefer copies and want the CLI to copy without attempting a symlink first, pass `--copy` explicitly:\n\n```shell\ndnx skills add owner/repo --agent claude-code --copy\n```\n\nThe output shows the skill was copied rather than linked: the Installation Summary lists `Copied:  Claude Code`, and the skill is written directly into `.claude/skills`.\n\n# \"skills update\" cannot check a skill or hits a rate limit\n\n`dnx skills update` reports that one or more skills could not be checked:\n\n```text\n$ dnx skills update -g\n\nChecking for skill updates...\n\n\n1 skill(s) cannot be checked automatically:\n  * legacy (Private or deleted repo)\n    To update: skills add https://github.com/owner/repo -g -y\n```\n\nCause: `update` checks for newer versions by calling the GitHub API, and unauthenticated calls are rate-limited. It also cannot diff every kind of source. Skills installed from a local path, a generic git URL, a well-known HTTP source, or a private or deleted repository have no checkable remote tree, so they are reported as \"cannot be checked automatically\" with a manual refresh hint.\n\nTo raise the rate limit, give `skills` a GitHub token and re-run. The CLI reads `GITHUB_TOKEN`, then `GH_TOKEN`, then falls back to `gh auth token`:\n\n```shell\nexport GITHUB_TOKEN=ghp_...   # or: gh auth login\ndnx skills update\n```\n\nWith the token in place the rate limit clears and the check completes:\n\n```text\nChecking for skill updates...\n\nAll skills are up to date.\n```\n\nFor sources that can never be checked automatically, re-install with `dnx skills add` to refresh them. The `update` output prints the exact command to run for each one:\n\n```shell\ndnx skills add owner/repo/skills/my-skill -y\n```\n\nThe refresh re-installs the skill from its source and prints the usual `Installed 1 skill(s)` panel.\n\n> `dnx skills update` only checks for and reports available updates. It never applies them. Whatever it finds, it prints the precise `skills add ...` command for you to run (prefix it with `dnx` when you use `dnx`). The aliases `dnx skills upgrade` and `dnx skills check` behave identically. See the [Reference](./reference.md).\n\n# \"... is newer than this skills supports\"\n\nA command refuses to write to a lock file and reports that the on-disk version is newer than this version of `skills` supports.\n\nCause: the lock file (`skills-lock.json` in your project, or the global `.skill-lock.json`) was written by a newer version of `skills` than the one you are running. The CLI reads newer lock files but refuses to modify them, so it does not corrupt state written by a version it does not understand.\n\nTo fix it, update `skills` to the latest release:\n\n```shell\ndotnet tool update -g skills\n```\n\nA successful upgrade reports the version change:\n\n```text\nTool 'skills' was successfully updated from version 0.1.0 to version 0.3.0.\n```\n\nIf you no longer need the existing lock state and want to start fresh, delete the lock file and re-install your skills. The project lock lives at `skills-lock.json` in your working directory; the global lock lives at `~/.local/share/skills/.skill-lock.json` (or under `$XDG_DATA_HOME/skills` if that variable is set).\n\n> [!WARNING]\n> **Deleting a lock file discards update tracking.** The CLI uses the lock file to know what is installed and to check for updates. After deleting it, run `dnx skills add` again for each skill so the CLI can rebuild the lock. The installed skill folders themselves are not removed by deleting the lock.\n\n# Bundled binary assets are missing from a skill\n\nA skill installs, but a binary file it ships (an image, a model, a compiled tool) is a tiny placeholder or absent.\n\nCause: the CLI disables Git LFS while cloning, so only LFS pointer files are fetched, not the large binaries they track. This keeps clones fast and shallow, but it means LFS-tracked assets do not arrive with the skill.\n\nTo fix it, change how the skill stores its assets:\n\n- Store skill assets without Git LFS so they travel as ordinary files in the repository.\n- Vendor the assets directly into the skill folder (commit the real files alongside `SKILL.md`).\n\nIf you author the skill yourself, see [Authoring Skills](./authoring-skills.md) for how to lay out bundled resources.\n\n# \"Failed to remove\" a skill\n\n`dnx skills remove` reports that it could not remove a skill:\n\n```text\n$ dnx skills remove \"My Skill\" --yes\n# exit 1\n\nFailed to remove 1 skill(s)\n  My Skill: ...\n```\n\nCause: the CLI removes a skill by the sanitized, lowercase, hyphenated name it uses on disk (for example `my-skill`). A folder created outside `skills` whose name does not match that sanitized form is not something the CLI will delete automatically, so it reports the failure rather than falsely claiming success. The CLI also refuses to delete a real non-empty directory or file it did not create, which protects your own data.\n\nTo fix it, delete the folder yourself from the skills directory. For a project install that is `./.agents/skills/<folder>`; for the corresponding agent directory it is, for example, `./.claude/skills/<folder>`. For a global install the canonical store is `~/.agents/skills/<folder>`.\n\n```shell\nrm -rf \"./.agents/skills/My Skill\"\n```\n\nRun `dnx skills list` afterward to confirm the skill is gone. The listing no longer shows the removed skill:\n\n```text\n$ dnx skills list\n\nNo project skills found.\nTry listing global skills with -g\n```\n\n# Next steps\n\n- [Reference](./reference.md): every command, flag, exit code, and environment variable in one place.\n- [Installing Skills](./installing-skills.md): sources, scopes, agent targeting, and the symlink versus copy model.\n- Still stuck? Ask in the [ChilliCream Slack](https://slack.chillicream.com/).\n","frontmatter":{"title":"Troubleshooting","description":"Troubleshoot `skills` CLI errors: each section maps the exact message the CLI prints to its cause and a copy-pasteable fix for installing and updating skills."},"isInternal":false,"tokens":3527,"sizeBytes":16073},{"name":"README.md","path":"src/HotChocolate/CostAnalysis/tools/oracle/README.md","rawUrl":"https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/src/HotChocolate/CostAnalysis/tools/oracle/README.md","title":"oracle Documentation","category":"plugin-manifest","format":"markdown","content":"# Cost differential oracle\n\nRegenerates the vendored ExactCase cost corpus\n(`../../test/CostAnalysis.Core.Conformance.Tests/__resources__/rust-corpus/`)\nfrom the MIT-licensed\n[`graphql-static-analysis-rs`](https://github.com/duckki/graphql-static-analysis-rs)\ncrate, the differential oracle for this cost analysis implementation.\n\n## Prerequisites\n\nCorpus regeneration and live differential runs require rustup with stable\nRust >= 1.90 (the pinned commit's `rust-version`) and a C++ compiler. The\ncrate's `fuzz` package links `libfuzzer-sys` 0.4 unconditionally, including\nfor a plain `cargo build` or `cargo run`. Install Rust with:\n\n```bash\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal\n. \"$HOME/.cargo/env\" && rustup toolchain install stable\n```\n\nThe scripts install nothing. `clone-oracle.sh` and `run-nightly.sh` print the\ninstall line when `cargo` is missing, and `run-nightly.sh` also rejects Rust\nversions below 1.90 and missing C++ compilers. Pull-request CI does not run\nRust. The scheduled workflow provisions stable Rust and uses the compiler on\n`ubuntu-26.04`.\n\n## Files\n\n- `clone-oracle.sh`: clones `graphql-static-analysis-rs` at the pinned commit\n  into the gitignored `.oracle/` next to this file, applies `oracle.patch`,\n  and copies `dump_corpus.rs` into the checkout's `fuzz/examples/`.\n- `oracle.patch`: a small patch against the pinned commit. `SCHEMA` and\n  `variable_values` in the crate's `fuzz/src/tree_summary/operation.rs` are\n  `pub(super)` (private to the fuzz package's own targets); the patch adds\n  `pub fn schema()` and `pub fn variables_json(variable_case: u8)` accessors\n  and registers `dump_corpus` as a `[[example]]` in `fuzz/Cargo.toml`.\n- `dump_corpus.rs`: the dump program itself (see below).\n- `oracle.rs`: a Rust example that coerces generated variables, builds a\n  `CostModel`, and evaluates each case with `ExactCase` and its declared\n  default list size.\n- `Fuzz/`: the deterministic .NET generator and comparison command. It emits\n  real `AddCostAnalyzer` interceptor schemas and synthetic annotated schemas.\n- `run-nightly.sh`: generates cases, runs the live oracle, compares raw f64\n  bits, and writes a standalone fixture for the first disagreement.\n- `LICENSE-graphql-static-analysis-rs.md`: the crate's MIT license text and\n  attribution for the vendored commit.\n\n## Running the live oracle\n\n```bash\nbash src/HotChocolate/CostAnalysis/tools/oracle/run-nightly.sh \\\n    --seed 1 --cases 200\n```\n\nEvery case stores its seed and uses the same finite `DefaultListSize` on both\nimplementations. Generated operations are query-only and reject introspection\nmeta-fields, `@defer`, and `@stream` before emission. Variables are valid for\nthe generated operation and are coerced by `apollo_compiler` before the Rust\nestimator runs.\n\nReal schemas are printed from servers configured with `AddCostAnalyzer`,\ncursor and offset paging, filtering, sorting, and list-of-scalar fields. The\nprinted SDL therefore carries explicit resolver, filter, sort, paging, and\nlist-of-scalar annotations. Synthetic schemas cover signed weights,\n`@listSize`, input defaults, interfaces, unions, and directive argument\nweights. Operations cover named fragments, Boolean directives, aliases, and\nduplicate response names.\n\n`slicingArgumentDefaultValue` is a ChilliCream extension. When a generated\noperation supplies none of a field's slicing arguments, the generator adds\nthe declared default literal to the oracle copy of that operation only. It\ndoes not rewrite the schema, and it adds nothing when any slicing argument is\nalready supplied.\n\nComparison uses the hexadecimal IEEE-754 bit patterns for `typeCost` and\n`fieldCost`. A mismatch exits nonzero and writes one isolated\n`source: \"fuzz-found\"` fixture under the conformance resources. Add this\nfixture to the conformance suite to run it without Rust.\n\n## Regenerating the corpus\n\n```bash\ncd src/HotChocolate/CostAnalysis/tools/oracle\n./clone-oracle.sh\ncargo run --manifest-path .oracle/fuzz/Cargo.toml --example dump_corpus -- \\\n    ../../test/CostAnalysis.Core.Conformance.Tests/__resources__/rust-corpus\n```\n\nThis overwrites `exact-case.json` and `manifest.json` in that directory.\nThe same pinned commit produces byte-identical output.\n\n## What the dump does\n\nThe corpus contains the ExactCase IBM-cost cases from the crate's 15,840-case\nmatrix. There are 1,980 candidates before invalid-variable exclusions and\ndeduplication.\n\nFor each row:\n\n- Rows with variables that fail GraphQL coercion are excluded and counted\n  in the manifest's `excludedInvalidVariables`.\n- Duplicate `(operation, variables, defaultListSize)` rows are excluded and\n  counted in `deduplicated`. Missing variables and an empty variables object\n  are equivalent.\n- The remaining rows are costed with the crate's own `CostEstimator` in\n  `ExactCase` mode, with `default_list_size` set to the row's `list_size`\n  (0..4 for the legacy-family rows; the structural rows fix it at 2). The\n  emitted `typeCost`/`fieldCost` are the raw `f64` values `CostEstimator`\n  returns, never the crate's `cost:T,F` display format.\n- `emitted + excludedInvalidVariables + deduplicated == exactCostRows` always\n  holds (asserted by the dump itself); the manifest records all four numbers\n  plus the pinned commit.\n\nThe emitted schema excludes the crate's `@tag` definition. None of the\nemitted operations uses that directive.\n\n## Rust-free validation\n\nThe generator can build and emit cases without cloning or running the oracle:\n\n```bash\ndotnet run --project src/HotChocolate/CostAnalysis/tools/oracle/Fuzz \\\n    --framework net11.0 -- --seed 1 --cases 20 \\\n    --emit-only /tmp/fuzz-cases.json\n```\n\nReviewers without Rust installed can still validate the committed artifact\nshape:\n\n```bash\npython3 -c \"\nimport json\nd = json.load(open('../../test/CostAnalysis.Core.Conformance.Tests/__resources__/rust-corpus/exact-case.json'))\nm = json.load(open('../../test/CostAnalysis.Core.Conformance.Tests/__resources__/rust-corpus/manifest.json'))\nassert m['matrixSize'] == 15840 and m['exactCostRows'] == 1980\nassert len(d) == m['emitted'] == 1980 - m['excludedInvalidVariables'] - m['deduplicated'], m\nassert all(r['backend'] == 'exact-case' and 'directive @tag' not in r['sdl'] for r in d)\nprint('ok', len(d))\n\"\n```\n\nThis does not re-run the estimator, so it cannot catch a wrong `typeCost` or\n`fieldCost`; it only checks the corpus's shape and bookkeeping.\n","isInternal":false,"tokens":1559,"sizeBytes":6432},{"name":"mcp.json","path":".vscode/mcp.json","rawUrl":"https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/.vscode/mcp.json","title":"Model Context Protocol (MCP) Configuration","category":"mcp-config","format":"json","content":"{\n  \"servers\": {\n    \"microsoft.docs.mcp\": {\n      \"type\": \"http\",\n      \"url\": \"https://learn.microsoft.com/api/mcp\"\n    },\n    \"nuget\": {\n      \"type\": \"stdio\",\n      \"command\": \"dotnet\",\n      \"args\": [\n        \"dnx\",\n        \"NuGet.Mcp.Server\",\n        \"--source\",\n        \"https://api.nuget.org/v3/index.json\",\n        \"--yes\"\n      ]\n    },\n    \"lighthouse\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@danielsogl/lighthouse-mcp@latest\"]\n    },\n    \"playwright\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@playwright/mcp@latest\"]\n    },\n  }\n}\n","isInternal":false,"tokens":188,"sizeBytes":606},{"name":"ReplyMailCommandTests.Reply_Should_ThreadUnderOriginalMessage_AndInheritRootSubject_When_JsonOutputIsRequested.md","path":"src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/ReplyMailCommandTests.Reply_Should_ThreadUnderOriginalMessage_AndInheritRootSubject_When_JsonOutputIsRequested.md","rawUrl":"https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/ReplyMailCommandTests.Reply_Should_ThreadUnderOriginalMessage_AndInheritRootSubject_When_JsonOutputIsRequested.md","title":"Command: /replymailcommandtests.reply_should_threadunderoriginalmessage_andinheritrootsubject_when_jsonoutputisrequested","category":"command-prompt","format":"markdown","content":"# Command: /replymailcommandtests.reply_should_threadunderoriginalmessage_andinheritrootsubject_when_jsonoutputisrequested\n\nPath: `src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/ReplyMailCommandTests.Reply_Should_ThreadUnderOriginalMessage_AndInheritRootSubject_When_JsonOutputIsRequested.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/ReplyMailCommandTests.Reply_Should_ThreadUnderOriginalMessage_AndInheritRootSubject_When_JsonOutputIsRequested.md)","tokens":300,"sizeBytes":616},{"name":"SendMailCommandTests.Send_Should_ReturnSendResult_When_JsonOutputIsRequested.md","path":"src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/SendMailCommandTests.Send_Should_ReturnSendResult_When_JsonOutputIsRequested.md","rawUrl":"https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/SendMailCommandTests.Send_Should_ReturnSendResult_When_JsonOutputIsRequested.md","title":"Command: /sendmailcommandtests.send_should_returnsendresult_when_jsonoutputisrequested","category":"command-prompt","format":"markdown","content":"# Command: /sendmailcommandtests.send_should_returnsendresult_when_jsonoutputisrequested\n\nPath: `src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/SendMailCommandTests.Send_Should_ReturnSendResult_When_JsonOutputIsRequested.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/SendMailCommandTests.Send_Should_ReturnSendResult_When_JsonOutputIsRequested.md)","tokens":300,"sizeBytes":514},{"name":"TaskStoreTests.ReleaseAssigneeAsync_Should_ReleaseInProgressTasksAndAppearInReady.md","path":"src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Tasks/__snapshots__/TaskStoreTests.ReleaseAssigneeAsync_Should_ReleaseInProgressTasksAndAppearInReady.md","rawUrl":"https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Tasks/__snapshots__/TaskStoreTests.ReleaseAssigneeAsync_Should_ReleaseInProgressTasksAndAppearInReady.md","title":"Command: /taskstoretests.releaseassigneeasync_should_releaseinprogresstasksandappearinready","category":"command-prompt","format":"markdown","content":"# Command: /taskstoretests.releaseassigneeasync_should_releaseinprogresstasksandappearinready\n\nPath: `src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Tasks/__snapshots__/TaskStoreTests.ReleaseAssigneeAsync_Should_ReleaseInProgressTasksAndAppearInReady.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Tasks/__snapshots__/TaskStoreTests.ReleaseAssigneeAsync_Should_ReleaseInProgressTasksAndAppearInReady.md)","tokens":300,"sizeBytes":531}],"systemPromptSnippet":"<yakaai_skills repo=\"ChilliCream/graphql-platform\">\n<!-- File: AGENTS.md (Tokens: ~2499 | Category: root-instruction) -->\n# AGENTS.md\n\nThis file provides guidance to coding agents when working with this repository.\n\n## Attribution\n\n- Do not add `Co-authored-by` trailers or other co-author attribution for agents.\n\n## Pull Requests\n\n- Start a bug fix PR title with `Fix`: `Fix the gateway ignoring subgraph timeouts`. The title becomes the squash commit subject and the release note entry.\n- Area prefixes are optional. Write them in title case (`[Fusion]`, not `[fusion]`), and put `Fix` after one: `[Fusion] Fix the gateway ignoring subgraph timeouts`.\n\n## Build\n\n### Website\n\nUse `npm`.\n\n```bash\ncd website\nnpm ci\n```\n\nnpm 11 before 11.21.1 and npm 12 before 12.2.1 write `allowScripts` entries from `npm install-scripts approve` that npm cannot match under the linked install strategy ([npm/cli#9939](https://github.com/npm/cli/issues/9939)), so on those versions add approvals by hand as `\"<package>@<version>\": true`.\n\n### C# Source Code\n\nBuilds report IDE code-style violations (`IDE*`) as build errors, the same as CI does. Fix every reported style error.\n\nBuild the full solution:\n\n```bash\ndotnet build src/All.slnx\n```\n\nEach area has its own solution file, so you can build or test a subset directly:\n\n```bash\ndotnet test src/HotChocolate/Fusion\n```\n\n## Updating .NET\n\nWhen a change edits `TargetFrameworks` in `src/Directory.Build.props` or the SDK version in `global.json`, work through [docs/updating-dotnet.md](docs/updating-dotnet.md) before handoff.\n\n## Code Quality\n\n### C# / .NET\n\n- Always use curly braces for loops and conditionals, no exceptions.\n- Use file-scoped namespaces and 4-space indentation.\n- Test naming: `Method_Should_Outcome_When_Condition`.\n- No vacuous assertions (`Assert.NotNull` alone is not a test).\n- If a test requires excessive stubs and reflection, you're at the wrong test tier.\n- Do not use em dash style sentences in docs, comments, or XML documentation. Use commas, periods, parentheses, or colons instead.\n- XML docs should describe the contract and concepts, not internals like pooling or iteration mechanics, and should not leak other implementation details.\n- XML docs and comments are 1-2 sentences stating the contract: what it is, what null or edge values mean. No rationale, no use-case examples, no design justification. If a sentence explains why the design is right instead of what the member promises, delete it. The same applies to docs pages: every sentence must inform the reader, none may justify the design.\n- Do not make new parameters optional just to avoid updating call sites. A parameter should only be optional when it has a sensible semantic default and the API is frequently used (where call-site brevity outweighs explicitness). If a parameter is logically required, make it required and update all call sites.\n\n### Testing\n\n- Prefer snapshot tests over manual `Assert` calls, use **CookieCrumble** for snapshots.\n- CookieCrumble has native snapshot support for `IExecutionResult`, `GraphQLHttpResponse`, and other core types.\n- For smaller snapshots, prefer **inline snapshots** (`MatchInlineSnapshot`) over snapshot files.\n- For a collection of results (for example a stream of subscription events), snapshot the list with `MatchInlineSnapshots` (a parallel list of per-element inline snapshots). Do NOT concatenate with `string.Join(\"---\", values).MatchInlineSnapshot(...)`: a manual separator hides element boundaries and reinvents what the collection overload does natively.\n- For tests with multiple assertions, use **Markdown snapshots** (`MatchMarkdownSnapshot`).\n- Hard limit: a single test method must contain at most 5 `Assert.*` calls. Anything beyond that is too hard to reason about in review, switch to a snapshot (Markdown for multi-shape state, inline or file for a single output).\n- Use the AAA section marker style. Each section starts with a single-line comment, the test name documents intent, no paragraph-style block comments above sections:\n\n  ```csharp\n  // arrange\n  // optional one-line description, only when the next code is non-obvious\n  ... arrange code ...\n\n  // act\n  ... act code ...\n\n  // assert\n  ... assert code ...\n  ```\n\n- Avoid `Assert.DoesNotContain` as it is a weak assertion that easily goes out of date, it only proves something is absent without verifying what *is* present. Prefer `Assert.Equal` to check the entire string value, or `Assert.Collection` to verify the complete contents of a collection.\n- Snapshot tests: update from `__mismatch__/` directory, understand ordering issues before updating.\n- Filter tests during iteration, never run the full suite unnecessarily.\n- Use real databases in integration tests, not mocks (unless explicitly instructed otherwise).\n\n## Performance\n\n### C# / .NET\n\nThis is framework code, performance matters. Aim for zero allocations on hot paths.\n\n- Use `ChunkedArrayWriter` or `PooledArrayWriter` when you need an `IBufferWriter<byte>` for in-memory byte writing.\n\n## Tools\n\n### C# / .NET\n\nIf you need to search for packages on nuget.org, use the `dotnet` CLI, e.g. `dotnet package search HotChocolate`.\n\n### Profiling\n\nThe dev container has `dotnet-trace`, `dotnet-counters`, `dotnet-gcdump`, `dotnet-dump`, `dotnet-symbol`, `dottrace` and `dotmemory` installed. Versions are pinned in `.devcontainer/dockerfile`, and `docs/profiling.md` has the full commands and caveats. The tools attach to a running process in the same container. Write outputs to `perf/<label>-<git-short-sha>/`, which is gitignored.\n\n```bash\nOUT=perf/<label>-$(git rev-parse --short HEAD); mkdir -p \"$OUT\"\ndotnet-trace ps\ndotnet-trace collect -p <pid> --duration 00:00:00:30 --format speedscope -o \"$OUT/cpu.nettrace\"\ndotnet-trace report \"$OUT/cpu.nettrace\" topN -n 25 --inclusive\ndotnet-trace collect -p <pid> --profile gc-verbose --duration 00:00:00:15 -o \"$OUT/alloc.nettrace\"\ndotnet-gcdump collect -p <pid> -o \"$OUT/heap.gcdump\" && dotnet-gcdump report \"$OUT/heap.gcdump\" > \"$OUT/heap-report.txt\"\ndotnet-counters collect -p <pid> --format json -o \"$OUT/counters.json\" --duration 00:00:00:20 --counters System.Runtime,Microsoft.AspNetCore.Hosting,System.Net.Http\n```\n\n- Profile Release builds. Debug builds distort time and allocations.\n- Sampling gives time, not call counts. Call counts need dotTrace Tracing mode, which only `dottrace start` offers; `dottrace attach` is limited to Sampling and Timeline.\n- On Linux, EventPipe samples measure thread time. Ignore idle thread pool frames such as `LowLevelLifoSemaphore.WaitForSignal` and `WaitHandle.WaitOneNoCheck`.\n- `.dtp` (dotTrace) and `.dmw` (dotMemory) snapshots are for Rider on the host. Use the `dotnet-trace` and `dotnet-gcdump` outputs for analysis inside the container.\n\n### Nitro persisted operations (Fusion Aspire)\n\nAfter adding or editing any `.graphql` document under `src/HotChocolate/Fusion/src/Fusion.Aspire/Nitro/Operations`, regenerate the `.sha256` sidecars and verify them:\n\n```bash\n.github/scripts/nitro-aspire-operations.sh update \\\n    --source src/HotChocolate/Fusion/src/Fusion.Aspire/Nitro/Operations\n.github/scripts/nitro-aspire-operations.sh verify \\\n    --source src/HotChocolate/Fusion/src/Fusion.Aspire/Nitro/Operations \\\n    --output /tmp/nitro-aspire-operations.json\n```\n\nNever hand-write or hand-edit a `.sha256` sidecar. The `update` command is the only source of sidecar content, and `verify` must pass before handoff.\n\n## Components\n\n### All components\n\n#### Exceptions\n\nCreate exceptions through the `ThrowHelper` class of the project you are editing instead of inlining `throw new ...`. Each project keeps its own, which centralizes exception messages.\nExample: `src/HotChocolate/Fusion/src/Fusion.Execution/Execution/ThrowHelper.cs`\n\n#### GraphQL errors\n\nCreate GraphQL errors through the `ErrorHelper` class of the project you are editing instead of inlining `ErrorBuilder` calls. Each project keeps its own, which centralizes error messages.\nExample: `src/HotChocolate/AspNetCore/src/AspNetCore.Pipeline/Utilities/ErrorHelper.cs`\n\n### src/Fusion\n\n#### Execution nodes\n\nWhen you add a value to `ExecutionNodeType`, map it in two places:\n\n- `ExecutePlanNodeSpan.KindValues` in `src/HotChocolate/Fusion/src/Fusion.Diagnostics/Spans/ExecutePlanNodeSpan.cs`\n- `GraphQL.Operation.Step.KindValues` in `src/HotChocolate/Diagnostics/src/Diagnostics.Core/SemanticConventions.cs`, if the kind needs a new constant. Tag values are snake_case.\n\n`KindValues` supplies the `graphql.operation.step.kind` tag on the step span. An unmapped type does not fail execution. `ExecutePlanNodeSpan.Start` falls back to an untagged span, so the node silently loses its kind in traces. The guard test `StepSpan_Should_MapEveryExecutionNodeTypeToAKindValue` in `src/HotChocolate/Fusion/test/Fusion.Diagnostics.Tests/FusionActivityExecutionDiagnosticListenerTests.cs` fails until the mapping exists.\n\n#### Operation planner version\n\n`OperationPlanner.Version` identifies planning behavior and is independent of the package version. Bump the minor version when an existing operation can plan differently, the major version when consumers must react to a new plan structure. Refactors, performance work and fixes that cannot change a plan do not bump it.\n\n#### Operation plan JSON format\n\n`JsonOperationPlanFormatter` in `src/HotChocolate/Fusion/src/Fusion.Execution/Execution/Nodes/Serialization/JsonOperationPlanFormatter.cs` writes the plan document that tooling consumes. Its shape is published as a JSON schema, so any change to the emitted JSON is a two part change:\n\n1. Bump `JsonOperationPlanFormatter.FormatVersion`. It is written as the root `version` property and is the discriminator consumers pin against. Additive optional properties bump the minor version, anything that changes or removes an existing property bumps the major version.\n2. Add the matching variant to `website/public/schemas/fusion/operation-plan.json`, published at `https://chillicream.com/schemas/fusion/operation-plan.json`. Add a `#/$defs/<version>_plan` entry and the `allOf` branch that selects it for that root `version`, and list the new version in the root `version` enum. Every other definition is unprefixed and shared across versions. When a version changes one of them, fork only that definition to `<version>_<name>` and point the new plan at the fork, so a released version keeps validating exactly what it validated before.\n\nThe root `version` enum and the `allOf` branch that selects `v1_0_0_plan` are the pattern to copy: a new version adds one enum entry, one branch and one plan definition.\n\nThe internal `Format(IBufferWriter<byte>, Operation, ImmutableArray<ExecutionNode>)` overload feeds the SHA-256 that becomes `OperationPlan.Id`. It deliberately omits the `version` property, so leave it alone unless you intend to change every plan id.\n\n<!-- File: website/AGENTS.md (Tokens: ~828 | Category: root-instruction) -->\n<!-- BEGIN:nextjs-agent-rules -->\n\n# This is NOT the Next.js you know\n\nThis version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.\n\n<!-- END:nextjs-agent-rules -->\n\n# Authoring markdown content\n\nWhen creating or editing content under `content/docs/` or `content/blog/`, follow\nthe conventions in [README.md → Authoring Markdown Content](./README.md#authoring-markdown-content).\nIt covers frontmatter, `structure.yaml` sidebars, links, images, YouTube videos,\nadmonitions, Mermaid diagrams, and MDX gotchas.\n\nWhen creating or editing a video under `content/videos/`, also follow\n[README.md → Videos](./README.md#videos) for the file name and frontmatter.\n\n# Components\n\nThis site is built to be extended agent-first: adding a page or component should\nbe mechanical and consistent. Keep the quality bar high; do not cut corners\nbecause an agent is doing the work.\n\n## Where code lives\n\n- **Pages**: `app/` route segments. Content/marketing routes live under\n  `app/(content)/`. Keep page files thin: compose section components, do not\n  inline large markup.\n- **Reusable components**: `src/components/`, one component per file\n  (PascalCase filename).\n- **Design-system primitives** (Button, Input, Image, Typography, ...):\n  `src/design-system/`.\n- **Icons and inline SVG art**: `src/icons/`, one per file.\n- A component that is only a child of one parent and is not reused elsewhere may\n  live in the parent's file. As soon as it is reused or is independently\n  meaningful, move it to its own file under `src/components/`.\n\n## Props\n\n- Declare props as an `interface` named `<Component>Props`.\n- Every property is `readonly`.\n- Do **not** export the props interface; it is the component's own\n  implementation detail.\n\n```tsx\ninterface ButtonProps {\n  readonly label: string;\n  readonly onClick?: () => void;\n}\n\nexport function Button({ label, onClick }: ButtonProps) {\n  // ...\n}\n```\n\n## SVG and icons\n\n- Add SVGs as inline React components in `src/icons/` that return `<svg>…</svg>`\n  directly, so the markup is inlined into the HTML.\n- Do **not** add raw `.svg` files to `public/` to load via `<img>` / `Image`:\n  the image pipeline does not process SVG, and inlining lets icons inherit\n  `currentColor` and be sized/positioned with CSS.\n- Accept `className` (and `style` when the caller positions the icon). Default\n  decorative icons to `aria-hidden=\"true\"`.\n- If the SVG uses element ids (e.g. gradient ids), prefix them per icon so\n  several inlined icons on the same page do not collide.\n\n## Typography\n\nUse the type scale from `app/globals.css` (`@theme`): the `text-hero` /\n`text-h1`…`text-h6` / `text-lead` / `text-body` / `text-caption` utilities (each\nships its line-height), the `font-heading` / `font-body` families (Tailwind\n`font-sans` maps to the body voice), and the `.hero` / `.lead` / `.caption`\nhelper classes. Avoid ad-hoc `text-4xl`-style sizes for display headings.\n\n## Before you finish\n\n- Verify visually against the running dev server (`npm run dev`).\n- `npx eslint <changed files>` must pass.\n- `npm run format` must be run and `npm run format:check` must pass (Prettier\n  formatting, including Tailwind class sorting, is enforced in CI).\n\n<!-- File: src/HotChocolate/CostAnalysis/tools/oracle/LICENSE-graphql-static-analysis-rs.md (Tokens: ~352 | Category: anthropic-skill) -->\n# License notice: graphql-static-analysis-rs\n\n`dump_corpus.rs` in this directory is built against, and the vendored\n`exact-case.json` corpus is generated from,\n[`graphql-static-analysis-rs`](https://github.com/duckki/graphql-static-analysis-rs)\nat commit `fec57fd7a980b5399637fa464a9bdce0781d91dd` (v0.2.0):\n\n```\nMIT License\n\nCopyright 2026 graphql-static-analysis contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n\n`oracle.patch` and `dump_corpus.rs` are original files written for this\nrepository; they are not derived from the crate's own source and are covered\nby this repository's own license.\n\n<!-- File: website/content/docs/skills/authoring-skills.md (Tokens: ~2791 | Category: anthropic-skill) -->\n---\ntitle: \"Authoring Skills\"\ndescription: \"Author Agent Skills with the `skills` CLI: scaffold a folder with `dnx skills init`, write the SKILL.md frontmatter and instructions, and publish through git.\"\n---\n\nPackage your team's conventions once, and any agent can pick them up. A skill is a folder with a `SKILL.md` file that tells an agent how to do something the way your team does it: your release checklist, your code review rules, your API client patterns. You write it once, push it to a git repo, and your teammates install it with one command. From then on, every agent they run loads that knowledge on demand, no copy-pasting prompts into each session.\n\nThis page teaches you to scaffold a skill, write a correct `SKILL.md`, add supporting files, and publish it so others can install it with [`dnx skills add`](./installing-skills.md). The skill format is the open [Agent Skills](https://agentskills.io/home) standard, so what you write here works across [55+ agents](./index.md), not only the one you author it in.\n\n# Scaffold a skill\n\n> Prerequisite: the .NET 10 SDK. See [Getting Started](./getting-started.md) before running the commands below.\n\nTo create a new skill in its own folder, run `dnx skills init` with a name.\n\n```shell\ndnx skills init my-skill\n```\n\n```text\nInitialized skill: my-skill\n\nCreated:\n  my-skill/SKILL.md\n\nNext steps:\n  1. Edit my-skill/SKILL.md to define your skill instructions\n  2. Update the name and description in the frontmatter\n\nPublishing:\n  GitHub: Push to a repo, then skills add <owner>/<repo>\n  URL:    Host the file, then skills add https://example.com/my-skill/SKILL.md\n```\n\nThis creates `my-skill/SKILL.md`. If everything worked, you have a folder named `my-skill` with one file inside it.\n\nTo scaffold a skill in the current directory instead, run `dnx skills init` with no name. The CLI derives the skill name from the folder you are in and writes `SKILL.md` next to your other files.\n\n```shell\ndnx skills init\n```\n\n```text\nInitialized skill: my-skill\n\nCreated:\n  SKILL.md\n\nNext steps:\n  1. Edit SKILL.md to define your skill instructions\n  2. Update the name and description in the frontmatter\n\nPublishing:\n  GitHub: Push to a repo, then skills add <owner>/<repo>\n  URL:    Host the file, then skills add https://example.com/my-skill/SKILL.md\n```\n\n`dnx skills init` never overwrites an existing skill. If `SKILL.md` is already present, it leaves your file untouched and tells you so.\n\n```text\nSkill already exists at my-skill/SKILL.md\n```\n\n## The generated template\n\n`dnx skills init` writes a spec-compliant starting point: the two required frontmatter fields, then a body with a heading and the sections most skills need.\n\n```markdown\n---\nname: my-skill\ndescription: A brief description of what this skill does\n---\n\n# my-skill\n\nInstructions for the agent to follow when this skill is activated.\n\n## When to use\n\nDescribe when this skill should be used.\n\n## Instructions\n\n1. First step\n2. Second step\n3. Additional steps as needed\n```\n\nReplace the placeholder `description`, then fill in the body. The next sections explain each part.\n\n# Structure a SKILL.md\n\nA `SKILL.md` has two parts: YAML frontmatter between `---` fences, and a Markdown body below it. The frontmatter is metadata the agent reads to decide whether your skill is relevant. The body is the instructions the agent follows once it decides to use the skill.\n\nThe \"Required frontmatter\" and \"Optional frontmatter\" subsections below are reference material: field-by-field constraint tables you can scan when you fill in the frontmatter. For the complete, authoritative field list see the [Reference](./reference.md).\n\n## Required frontmatter\n\nEvery skill needs `name` and `description`. The CLI skips any skill that is missing either field, so getting these right is the difference between a skill that installs and one that silently disappears.\n\n| Field         | Constraints                                                                                                                                                                                                                                               |\n| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `name`        | 1 to 64 characters. Lowercase letters, digits, and hyphens only. No leading or trailing hyphen. No consecutive hyphens. Should match the skill's folder name. Must not contain XML tags, and must not contain the reserved words `anthropic` or `claude`. |\n| `description` | 1 to 1024 characters. Must say BOTH what the skill does AND when to use it. Include specific trigger keywords that match the tasks where the skill applies. Must not contain XML tags.                                                                    |\n\nThe `description` is the single most important field you write. At startup the agent loads only your `name` and `description` (not the body), then matches the user's request against that description to decide whether to read the rest. A vague description means the agent never triggers your skill. Front-load what the skill does, then state the conditions that should activate it, and name the tools, file types, or commands involved.\n\n```markdown\n---\nname: release-checklist\ndescription: Runs our release checklist before publishing a NuGet package. Use when cutting a release, bumping a version, or preparing a package for nuget.org.\n---\n```\n\nThese constraints are the union of two authorities: the open spec at [agentskills.io/specification](https://agentskills.io/specification) (which adds the \"match the folder name\" and \"no consecutive hyphens\" rules) and the [Anthropic platform rules](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) (which add the reserved-word and XML-tag prohibitions). Honoring both keeps your skill portable across every agent.\n\n## Optional frontmatter\n\nAdd these fields only when you need them. The open spec at [agentskills.io/specification](https://agentskills.io/specification) is the authoritative field list; the most useful fields are below.\n\n| Field           | Purpose                                                                                                                                                                     |\n| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `license`       | A license name or a reference to a bundled license file. Keep it short.                                                                                                     |\n| `compatibility` | Up to 500 characters describing environment needs (intended product, system packages, network access). Most skills do not need it. Example: `Requires git, docker, and jq`. |\n| `metadata`      | A string-to-string map for client-defined properties the spec does not cover, such as `author` or `version`. Use distinctive key names to avoid collisions.                 |\n| `allowed-tools` | A space-separated list of pre-approved tools, for example `Bash(git:*) Read`.                                                                                               |\n\nFor the exhaustive list of frontmatter fields and their constraints, see the [Reference](./reference.md).\n\n> [!WARNING]\n> **`allowed-tools` is experimental.** Support varies between agents, and `dnx skills init` does not emit it. Treat it as a hint that some agents honor and others ignore, not a security boundary.\n\n## The instructions body\n\nThe body is plain Markdown the agent follows when your skill activates. There are no format restrictions, so write it the way you would brief a new teammate: step-by-step instructions, input and output examples, and the edge cases people get wrong.\n\nKeep `SKILL.md` focused. The recommendation from both [Anthropic](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) and the open spec is to keep the body under roughly 500 lines and move long detail into supporting files (see the next section). A tight body loads fast and keeps the agent on the steps that matter.\n\n# Add supporting files\n\nA skill folder can hold more than `SKILL.md`. Three conventional subdirectories cover most needs.\n\n```text\nmy-skill/\n├── SKILL.md          # Required: frontmatter + instructions\n├── references/       # Docs loaded on demand (REFERENCE.md, API.md, ...)\n├── scripts/          # Code the agent runs\n└── assets/           # Templates, data files, schemas\n```\n\nThe CLI copies or symlinks the whole folder as a unit, so every supporting file ships with the skill. (A few build artifacts are excluded automatically, including `.git`, `node_modules`, and `__pycache__`.)\n\nThese directories exist because of [progressive disclosure](./index.md#how-skills-load-progressive-disclosure): the agent loads your skill in stages so a large skill costs almost nothing until it is needed.\n\n- At startup the agent loads only `name` and `description`.\n- When the skill triggers, the agent reads the `SKILL.md` body.\n- A file under `references/`, `scripts/`, or `assets/` loads only when the body points the agent at it.\n\nThis is why moving detail out of `SKILL.md` and into `references/` is free: that material never enters the context window until the agent actually follows a link to it. Reference your supporting files with relative paths one level deep (for example `references/api.md`), and avoid deep nesting chains. For more on the three-stage model, see the [Introduction](./index.md#how-skills-load-progressive-disclosure) and [Anthropic's overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).\n\n# How installed skills are named\n\nWhen someone installs your skill, the CLI derives the on-disk directory name by sanitizing the `name` field. It lowercases the name, replaces every run of characters outside `a-z`, `0-9`, `.`, and `_` with a single hyphen, and trims leading and trailing dots and hyphens.\n\nFor a clean lowercase-hyphen name like `release-checklist`, the on-disk name is identical, with no surprises. A name with spaces or uppercase letters gets rewritten (`My Skill` becomes `my-skill`), which can mismatch what you and your teammates expect on disk and during removal. Pick a clean lowercase-hyphen name that already satisfies the [required frontmatter rules](#required-frontmatter), and the install name matches your folder name exactly.\n\n# Publish and install\n\nA skill is a folder in a git repo, so publishing is committing and pushing. Any repository the CLI can reach with git works.\n\nTo publish, commit your skill folder and push it to GitHub, GitLab, or any git remote. Then anyone installs it with `dnx skills add` pointed at the repo. The forms below show what an installer runs against your published skill; for the full add workflow, including expected output, scoping, and agent targeting, see [Installing Skills](./installing-skills.md).\n\n```shell\n# install every skill in the repo\ndnx skills add my-org/my-skills\n\n# install only one skill from a multi-skill repo\ndnx skills add my-org/my-skills@release-checklist\n\n# install a single SKILL.md hosted at a URL\ndnx skills add https://example.com/my-skill/SKILL.md\n```\n\nPrivate repositories work with no extra configuration. The CLI shells out to your own `git`, so it uses your existing credentials (SSH agent keys, a git credential helper, or `gh auth`). If you can `git clone` the repo, `skills` can install from it. When authentication fails, see [Troubleshooting](./troubleshooting.md).\n\nTo keep a work-in-progress skill out of default discovery, set `metadata.internal` to `true` in the frontmatter. The CLI hides internal skills unless the installer explicitly opts in (by filtering for the skill by name, or by setting the `INSTALL_INTERNAL_SKILLS` environment variable).\n\n```markdown\n---\nname: experimental-skill\ndescription: An in-progress skill. Use when testing new conventions before rollout.\nmetadata:\n  internal: \"true\"\n---\n```\n\n# Validate a skill\n\nTo check a skill against the open spec before you publish, use the reference validator `skills-ref` from the [agentskills/agentskills](https://github.com/agentskills/agentskills) repository. It validates your frontmatter and naming conventions.\n\n```shell\nskills-ref validate ./my-skill\n```\n\nIt reports a clean pass when the skill is valid, or names the offending field and rule when it is not (for example, an empty `description` or a `name` that breaks the naming rules).\n\nRunning it after `dnx skills init` and again before you push catches a malformed `name` or an empty `description` while it is still fast to fix, rather than discovering that the CLI skipped your skill on install.\n\n# Next steps\n\n- [Installing Skills](./installing-skills.md): install your published skill, target specific agents, and choose project or global scope.\n- [Reference](./reference.md): the complete command and flag surface, including `dnx skills init`.\n\n<!-- File: website/content/docs/skills/getting-started.md (Tokens: ~2139 | Category: anthropic-skill) -->\n---\ntitle: \"Getting Started\"\ndescription: \"Run the `skills` CLI with `dnx` and add your first Agent Skill to Claude Code or another AI coding agent in five minutes using `dnx skills add`.\"\n---\n\nBy the end of this guide you will have run `skills` and added your first skill to your agent.\n\n`skills` is a .NET CLI that installs, updates, and authors [Agent Skills](https://agentskills.io/home), the portable `SKILL.md` files that extend AI coding agents like Claude Code, Cursor, and GitHub Copilot. You point it at a source (a GitHub repo, a git URL, or a local folder), and it places the skill where your agent looks for it. Your agent then loads the skill on demand when a task matches it.\n\nThis page takes you from zero to one working skill. It takes about five minutes.\n\n# Prerequisites\n\nBefore you start, make sure you have the following:\n\n| Requirement                                                   | Why you need it                                                                                                                                                             |\n| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [.NET 10 SDK or newer](https://dotnet.microsoft.com/download) | To run `skills` with `dnx`, the way these docs show it. The `dnx` command ships with the .NET 10 SDK.                                                                       |\n| An AI coding agent                                            | The target for your skill. This guide uses [Claude Code](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview). The `skills` CLI supports 55+ agents. |\n\nThese docs run `skills` with `dnx`, so there is nothing to install first. If you would rather have `skills` on your `PATH`, install the global tool instead (it needs only the .NET SDK 8.0 or newer). See [Install as a global tool](#install-as-a-global-tool).\n\n# Run `skills`\n\nThese docs run `skills` with `dnx`, which needs no install. You can also install it as a global tool if you prefer `skills` on your `PATH`.\n\n## Run with dnx\n\n`dnx` ships with the .NET 10 SDK and runs a tool straight from NuGet, the way `npx` runs a package from npm. Nothing is installed up front.\n\n```shell\ndnx skills add anthropics/skills --agent claude-code\n```\n\nOn the first run, `dnx` prompts you to confirm the package download before it proceeds:\n\n```text\nTool package skills@<version> will be downloaded from source https://api.nuget.org/v3/index.json.\nProceed? [y/n] (y):\n```\n\nAfter you confirm, the install proceeds and prints the summary shown in [Add your first skill](#add-your-first-skill). The first run downloads the package into your NuGet cache; later runs reuse it and start immediately. `dnx skills` is shorthand for `dotnet tool exec skills`.\n\nTo skip the download prompt (for example in CI), pass `--yes`:\n\n```shell\ndnx --yes skills add anthropics/skills --agent claude-code\n```\n\nYou can control the `skills` version that `dnx` runs and where it fetches it from:\n\n| Command                                      | What it does                        |\n| -------------------------------------------- | ----------------------------------- |\n| `#!shell dnx skills@0.3.0 add ...`           | Runs an exact version.              |\n| `#!shell dnx skills@0.3.* add ...`           | Runs the latest 0.3.x version.      |\n| `#!shell dnx --prerelease skills add ...`    | Allows prerelease versions.         |\n| `#!shell dnx --source <feed> skills add ...` | Fetches from a specific NuGet feed. |\n\nIf your repository has a `.config/dotnet-tools.json` manifest that lists `skills`, `dnx` honors the pinned version from the manifest, which keeps one-shot runs consistent with the version your team committed.\n\n## Install as a global tool\n\nIf you would rather have `skills` on your `PATH`, install it as a global [.NET tool](https://learn.microsoft.com/dotnet/core/tools/global-tools). This needs the .NET SDK 8.0 or newer.\n\n```shell\ndotnet tool install -g skills\n```\n\n```text\nYou can invoke the tool using the following command: skills\nTool 'skills' (version '0.3.0') was successfully installed.\n```\n\nWith the global tool you run `skills` directly: drop the `dnx` prefix from every example in these docs (`dnx skills add ...` becomes `skills add ...`). Confirm the install with `skills --version`, which prints a value like `0.3.0+<git-sha>` (the trailing suffix records the exact commit the build came from).\n\nTo pin `skills` to a version your whole team shares, install it as a local tool through a manifest instead. From the repository root:\n\n```shell\ndotnet new tool-manifest\ndotnet tool install skills\n```\n\nLocal tools are restored with `dotnet tool restore` and run through `dotnet skills`. Check the manifest (`./.config/dotnet-tools.json`) into source control so every collaborator uses the same version.\n\n# Add your first skill\n\nYou are ready to install a skill. The example below installs skills from [anthropics/skills](https://github.com/anthropics/skills), Anthropic's reference repository, targeting Claude Code.\n\n```shell\ndnx skills add anthropics/skills --agent claude-code\n```\n\nAgent names are case-sensitive. Use `claude-code`, not `claude` or `Claude`. For GitHub Copilot the name is `github-copilot`.\n\nThe `skills` CLI fetches the source, discovers the skills, installs them, and prints a summary:\n\n```text\nSource: https://github.com/anthropics/skills.git\nFound 2 skill(s)\n\n┌─Installation Summary─────────────────────────────────────────────────────────┐\n│ Canonical: /your-project/.agents/skills                                      │\n│ Symlinked:  Claude Code                                                      │\n└──────────────────────────────────────────────────────────────────────────────┘\n┌─Installed 2 skill(s)─────────────────────────────────────────────────────────┐\n│ ✓ pdf                                                                        │\n│   → /your-project/.claude/skills/pdf                                         │\n│ ✓ docx                                                                       │\n│   → /your-project/.claude/skills/docx                                        │\n└──────────────────────────────────────────────────────────────────────────────┘\n\nDone!  Review skills before use; they run with full agent permissions.\n```\n\n> The trailing line is a deliberate safety nudge. A skill can include scripts that the agent runs with your agent's full permissions. Install skills only from sources you trust, and read a new skill before you use it.\n\nIf you omit `--agent`, the CLI runs interactively and lets you pick which agents to target from the ones it detects on your machine. To install only specific skills from a multi-skill source, add `--skill <name>` (repeatable). For the full set of source forms, scopes, and flags, see [Installing Skills](./installing-skills.md).\n\n**Checkpoint.** If everything worked, you should see the `Installed 2 skill(s)` panel and the `Done!` line, with no error. If you saw an `Invalid agents` panel, you misspelled the agent name (it is case-sensitive). If you saw `No valid skills found`, the source had no `SKILL.md` with both a `name` and a `description`. See [Troubleshooting](./troubleshooting.md) for more.\n\n# See what is installed\n\nTo confirm what landed in your project, list the installed skills:\n\n```shell\ndnx skills list\n```\n\n```text\nProject Skills\n\nSkill  Path                   Agents\npdf    ./.claude/skills/pdf   Claude Code\ndocx   ./.claude/skills/docx  Claude Code\n```\n\nThe table shows each skill's name, where it lives on disk, and the agents linked to it (shown by their display name, `Claude Code`). To list global skills instead, add `-g`. For machine-readable output, add `--json`.\n\n# Use the skill\n\nThe skill now lives where your agent looks for it. You do not need to do anything else.\n\nYour agent loads each installed skill's `name` and `description` at startup, then reads the full skill only when a task matches the description. This is [progressive disclosure](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview): the description is the trigger, and the body loads on demand. Start a task that matches the skill, and your agent picks it up automatically.\n\n# Update or remove the global tool\n\nIf you run `skills` with `dnx`, you never update it yourself: each run fetches the version you ask for. The commands below apply when you installed the global tool.\n\nTo update the global `skills` tool to the latest version:\n\n```shell\ndotnet tool update -g skills\n```\n\n```text\nTool 'skills' was successfully updated from version '0.3.0' to version '<new>'.\n```\n\nTo uninstall it:\n\n```shell\ndotnet tool uninstall -g skills\n```\n\n```text\nTool 'skills' (version '0.3.0') was successfully uninstalled.\n```\n\nNote that `dotnet tool update` updates the `skills` CLI, not your installed skills. To check your skills for updates, use the `dnx skills update` command, covered in [Installing Skills](./installing-skills.md).\n\n# Next steps\n\n- [Installing Skills](./installing-skills.md): every source form, project versus global scope, picking agents and skills, symlink versus copy, and checking for skill updates.\n- [Authoring Skills](./authoring-skills.md): scaffold a `SKILL.md` with `dnx skills init`, write a good description, and publish your skill.\n- [Reference](./reference.md): the complete command and flag surface.\n\n<!-- File: website/content/docs/skills/index.md (Tokens: ~1913 | Category: anthropic-skill) -->\n---\ntitle: Skills\nmetaTitle: \"Skills: Agent Skills CLI for .NET\"\ndescription: \"The `skills` .NET CLI installs, updates, and authors Agent Skills: portable SKILL.md files you can share across Claude Code, Cursor, and 55+ agents.\"\n---\n\n`skills` is the .NET CLI that installs, updates, and authors [Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills): portable `SKILL.md` files that teach an AI coding agent how you work. Stop re-explaining your conventions every session. Package the knowledge once, then hand the same skill to Claude Code, Cursor, GitHub Copilot, or another of the 55+ supported agents with a single command.\n\nRun it with `dnx`, which ships with the .NET 10 SDK, so there is nothing to install first:\n\n```shell\ndnx skills add anthropics/skills --agent claude-code\n```\n\n```text\nSource: https://github.com/anthropics/skills.git\nFound 2 skill(s)\n\n┌─Installation Summary─────────────────────────────────────────────────────────┐\n│ Canonical: /your-project/.agents/skills                                      │\n│ Symlinked:  Claude Code                                                      │\n└──────────────────────────────────────────────────────────────────────────────┘\n┌─Installed 2 skill(s)─────────────────────────────────────────────────────────┐\n│ ✓ pdf                                                                        │\n│   → /your-project/.claude/skills/pdf                                         │\n│ ✓ docx                                                                       │\n│   → /your-project/.claude/skills/docx                                        │\n└──────────────────────────────────────────────────────────────────────────────┘\n\nDone!  Review skills before use; they run with full agent permissions.\n```\n\nThe CLI detects the agents you have installed, then symlinks the skill into each one from a single canonical store. The agent loads the skill on its own when a task matches.\n\nThese docs show every command as `dnx skills`. Prefer `skills` on your `PATH`? Install the global tool with `#!shell dotnet tool install -g skills`, then drop the `dnx` prefix and run `skills` directly.\n\nNeed the prerequisites or a step-by-step walkthrough? See [Get started](./getting-started.md). The [source repository](https://github.com/ChilliCream/skills) and [`skills` package on NuGet](https://www.nuget.org/packages/skills) are public.\n\n# What are Agent Skills\n\nA skill is a folder with a single `SKILL.md` file. That file has YAML frontmatter (a `name` and a `description`) followed by a Markdown body of instructions. Optional subfolders carry supporting material the agent reads only when it needs it.\n\nThink of a skill as an onboarding guide for a new team member. You write down a procedure once (how to run your test suite, how your commit messages are formatted, which API your team prefers), and the agent references the relevant section when a task calls for it. A general-purpose agent becomes a specialist in your codebase without bespoke prompt engineering on every request.\n\nSkills differ from prompts. A prompt is conversation-level guidance you paste in for one task. A skill loads on demand across every conversation, so you never repaste the same instructions again.\n\nThe `SKILL.md` format is an open standard created by Anthropic and adopted across the ecosystem. The same file works in 55+ supported agents, including Claude Code, Cursor, and GitHub Copilot. To go deeper, read Anthropic's [Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) and the [open specification](https://agentskills.io/specification) at agentskills.io.\n\n# How skills load: progressive disclosure\n\nSkills stay out of the agent's context window until they are needed. The format loads in three levels, each at a different time. This is the single most important idea to understand, because it is why you can install many skills without paying a context penalty.\n\n| Level                 | What loads                                            | When                                    | Token cost            |\n| --------------------- | ----------------------------------------------------- | --------------------------------------- | --------------------- |\n| Level 1: Metadata     | The `name` and `description` from the frontmatter     | Always, at startup                      | ~100 tokens per skill |\n| Level 2: Instructions | The `SKILL.md` Markdown body                          | When the skill is triggered             | Keep under ~5k tokens |\n| Level 3: Resources    | Bundled files in `references/`, `scripts/`, `assets/` | On demand, when the body points to them | Effectively unlimited |\n\nAt startup the agent loads only each skill's `name` and `description`. The `description` is what the agent matches against your request to decide whether to activate the skill, so write it to describe both what the skill does and when to use it. When a request matches, the agent reads the full body. Bundled resources never enter context until the body references them, which is why supporting material can be effectively unbounded.\n\nThe open standard frames the same flow as Discovery, Activation, and Execution. For the full model, see Anthropic's [overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) and the [agentskills.io home page](https://agentskills.io/home).\n\n# What a skill looks like\n\nA skill is, at minimum, a folder containing one `SKILL.md` file. Everything else is optional and loaded only when referenced:\n\n```text\nmy-skill/\n├── SKILL.md       # Required: frontmatter (name + description) + Markdown instructions\n├── references/    # Optional: extra docs the agent reads on demand\n├── scripts/       # Optional: code the agent runs via the shell\n└── assets/        # Optional: templates, schemas, images, data files\n```\n\nThe folder name should match the `name` in the frontmatter. Here is a minimal, valid `SKILL.md` with the two required fields:\n\n```markdown\n---\nname: roll-dice\ndescription: Rolls one or more dice and returns the results. Use when the user asks to roll dice, flip for a decision, or pick a random number in a range.\n---\n\n# Roll dice\n\nWhen the user asks to roll dice, parse the count and number of sides (default to one six-sided die),\nthen return each roll and the total.\n```\n\nThe `dnx skills init` command scaffolds this layout for you; [Authoring Skills](./authoring-skills.md) walks through it with the generated `SKILL.md` and folder tree. The full field reference, including optional frontmatter, lives in the [open specification](https://agentskills.io/specification) and in [Authoring Skills](./authoring-skills.md).\n\n# Why Skills\n\nThe `skills` CLI brings the install-once, run-anywhere skill workflow to the .NET SDK. Three things make it worth adding to your toolbox.\n\nProject-scoped installs are recorded in a `skills-lock.json` file in your working directory. Commit it, and your whole team shares one reproducible skill set, the same way a lock file pins your package dependencies.\n\nOne install reaches every detected agent. The CLI materializes each skill once in a canonical store, then links it into the directory each installed agent expects. You do not manage per-agent copies by hand.\n\nPersonal skills install globally with `--global`. Those live outside any single project and follow you across every repository you work in.\n\n# The ecosystem\n\nThe Agent Skills world has three distinct layers. Knowing which is which helps you find what you need.\n\n| Layer         | What it is                                | Where                                                                                                             |\n| ------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| Format / spec | The open `SKILL.md` standard              | [agentskills.io](https://agentskills.io/specification), [anthropics/skills](https://github.com/anthropics/skills) |\n| Discovery     | A directory of published skills to browse | [skills.sh](https://www.skills.sh/)                                                                               |\n| Installers    | CLIs that fetch and install skills        | `skills` (.NET), [npx skills](https://github.com/vercel-labs/skills) (Node)                                       |\n\nThe `skills` CLI brings the [npx skills](https://github.com/vercel-labs/skills) workflow to the .NET SDK via `dnx`, so you can run it without a global install. The command surface deliberately mirrors what Node developers already know. The CLI has no registry of its own: you point `dnx skills add` at any git repository or local folder, and you discover skills to install from directories like [skills.sh](https://www.skills.sh/).\n\n# Next steps\n\n- [Get started](./getting-started.md): run `skills` and add your first skill end to end.\n- [Author a skill](./authoring-skills.md): scaffold a `SKILL.md`, write a strong description, and publish it.\n\n<!-- File: website/content/docs/skills/installing-skills.md (Tokens: ~4221 | Category: anthropic-skill) -->\n---\ntitle: \"Installing Skills\"\ndescription: \"Install Agent Skills from GitHub repos, git URLs, or local folders with `dnx skills add`: the CLI finds every SKILL.md and wires it into your agents.\"\n---\n\n`dnx skills add` installs skills from a source into the AI coding agents you already have. Point it at a GitHub repository and the CLI discovers every `SKILL.md`, detects your agents, and wires the skill into each one.\n\n```shell\ndnx skills add anthropics/skills\n```\n\nThat single command fetches [Anthropic's reference skills](https://github.com/anthropics/skills), then either prompts you to choose which skills and agents you want or, when it is running inside an agent, installs non-interactively. This page walks the full lifecycle: choosing a source, narrowing to specific skills and agents, picking a scope, keeping skills current, and removing them.\n\nIf you have not installed the CLI yet, start with [Getting Started](./getting-started.md).\n\n> [!WARNING]\n> **Skills run with your agent's full permissions.** A skill is executable instructions plus optional scripts that your agent runs on your machine. Install only from sources you trust, and review a skill before you use it. After every successful install, `skills` reminds you: `Review skills before use; they run with full agent permissions.`\n\n# Choose a source\n\nThe `source` argument tells the CLI where to fetch skills from. It infers the kind of source from the string, so you pass one positional value and nothing else.\n\nThe most common form is a GitHub `owner/repo` shorthand:\n\n```shell\ndnx skills add anthropics/skills\n```\n\nEvery source form below is accepted. The first matching rule wins, and clones are always shallow (the CLI fetches only the latest commit, not the full history).\n\n| Source form            | Example                                                                      | What it does                                                              |\n| ---------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------- |\n| GitHub `owner/repo`    | `#!shell dnx skills add anthropics/skills`                                   | Installs from the repository root. The default shorthand.                 |\n| GitHub subpath         | `#!shell dnx skills add anthropics/skills/document-skills/pdf`               | Installs only the skill at that path in the repo.                         |\n| GitHub branch or tag   | `#!shell dnx skills add owner/repo#main`                                     | Installs from a specific ref (`#branch` or `#tag`).                       |\n| GitHub skill filter    | `#!shell dnx skills add owner/repo@my-skill`                                 | Installs only the skill named `my-skill` from the repo.                   |\n| GitHub URL             | `#!shell dnx skills add https://github.com/owner/repo`                       | Full URL, with or without a trailing `.git`.                              |\n| GitHub `tree` URL      | `#!shell dnx skills add https://github.com/owner/repo/tree/main/skills/foo`  | A `/tree/<ref>/<path>` URL pins the ref and subpath.                      |\n| GitLab shorthand       | `#!shell dnx skills add gitlab:group/project`                                | Installs from GitLab. Subgroups are supported (`group/subgroup/project`). |\n| GitLab URL             | `#!shell dnx skills add https://gitlab.com/group/project/-/tree/main/skills` | GitLab uses `/-/tree/` (note the `-` segment).                            |\n| Generic git or SSH     | `#!shell dnx skills add git@github.com:owner/repo.git`                       | Any `https`, `ssh://`, `git://`, or scp-style git transport.              |\n| Local directory        | `#!shell dnx skills add ./my-skills`                                         | A local path: `./`, `../`, an absolute path, or a Windows drive path.     |\n| Well-known HTTP(S) URL | `#!shell dnx skills add https://example.com/skills`                          | A non-git site that serves skills via `.well-known` discovery.            |\n\nA few notes that save time:\n\n- A bare name like `my-skills` (no `./` prefix) is treated as `owner/repo` shorthand, not a local path. Use `./my-skills` when you mean a local directory.\n- You can combine a ref and a skill filter: `owner/repo#main@my-skill`.\n- Any credentials embedded in a URL are stripped before they appear in output or in the lock file. The `Source:` line that the CLI prints shows `https://<redacted>@host/...`.\n\n> A well-known HTTP source fetches a `.well-known/agent-skills/index.json` (or `.well-known/skills/index.json`) discovery document from the site and downloads the listed skills. Every fetch is pinned to the same origin as the index, and indexes verify a SHA-256 digest per skill.\n\n# Choose which skills to install\n\nA source can contain many skills. By default, when you do not pass any filter, the CLI lists what it found and lets you select interactively. To narrow the set up front, use the options below.\n\nTo preview the available skills without installing anything, pass `--list` (or `-l`):\n\n```shell\ndnx skills add anthropics/skills --list\n```\n\n```text\nSource: https://github.com/anthropics/skills.git\nFound 2 skill(s)\n\nAvailable Skills\n  pdf\n    the pdf skill\n  docx\n    the docx skill\n\nUse --skill <name> to install specific skills\n```\n\nTo install one or more specific skills by name, pass `--skill` (or `-s`). The option is repeatable:\n\n```shell\ndnx skills add anthropics/skills --skill pdf --skill docx\n```\n\nYou can also embed a single skill filter in the source string with `@name`:\n\n```shell\ndnx skills add anthropics/skills@pdf\n```\n\nTo install every skill from the source into every detected agent, non-interactively, pass `--all`:\n\n```shell\ndnx skills add anthropics/skills --all\n```\n\nA successful run prints the `Installation Summary` and `Installed N skill(s)` panels followed by the safety reminder, the same shape shown under [How skills reach each agent](#how-skills-reach-each-agent).\n\n`--all` is a shortcut: it selects all skills, targets all agents, and skips every prompt.\n\nIf a `--skill` filter matches nothing, the CLI lists what was available so you can correct the name, and exits with a non-zero code:\n\n```text\nSource: /home/you/my-skills\nFound 2 skill(s)\nNo matching skills found for: nope\nAvailable skills:\n  alpha\n  beta\n```\n\nA skill is any folder that contains a `SKILL.md` with both a `name` and a `description`. If the source contains no valid skills, the CLI reports `No valid skills found. Skills require a SKILL.md with name and description.` and exits non-zero. See [Authoring Skills](./authoring-skills.md) for the format.\n\n# Choose which agents\n\nBy default, the CLI detects which agents are installed on your machine and targets them. To choose explicitly, pass `--agent` (or `-a`). The option is repeatable and accepts multiple values per token, and `*` means every supported agent:\n\n```shell\n# repeated flags\ndnx skills add anthropics/skills --agent claude-code --agent cursor\n\n# space-separated values in one token\ndnx skills add anthropics/skills --agent claude-code cursor\n\n# every supported agent\ndnx skills add anthropics/skills --agent \"*\"\n```\n\nA valid `--agent` run prints the `Installation Summary` and `Installed N skill(s)` panels shown under [How skills reach each agent](#how-skills-reach-each-agent), naming each agent that was linked or copied.\n\nThe CLI resolves the target agents like this:\n\n- **Running inside an agent.** When the CLI runs inside an agent (for example, when your agent invokes it for you), it goes non-interactive and targets that agent plus the shared store.\n- **Run from your shell, one agent installed.** The CLI auto-selects that agent plus the shared store.\n- **Run from your shell, several agents installed.** The CLI prompts you to choose, pre-selecting your last-used agents (or the common defaults `claude-code`, `codex`, `opencode` on a first run).\n- **`--agent` passed.** The CLI uses exactly what you specify, after validation.\n\nThese are the headline agent identifiers. Names are case-sensitive.\n\n| Agent          | `--agent` identifier |\n| -------------- | -------------------- |\n| Claude Code    | `claude-code`        |\n| Cursor         | `cursor`             |\n| GitHub Copilot | `github-copilot`     |\n| Codex          | `codex`              |\n| Continue       | `continue`           |\n| Gemini CLI     | `gemini-cli`         |\n| Windsurf       | `windsurf`           |\n\nThe `skills` CLI supports 55+ agents. For the complete list, plus the exact directory each agent installs into, see the [Reference](./reference.md).\n\nBecause identifiers are case-sensitive, `copilot` and `Claude-Code` are not valid. An invalid value fails fast and lists every valid name so you can copy the right one:\n\n```text\n┌─Invalid agents───────────────────────────────────────────────────────────────┐\n│ Invalid agents: bogus                                                        │\n│                                                                              │\n│ Valid agents: adal, aider-desk, amp, antigravity, augment, bob, claude-code, │\n│ cline, codearts-agent, codebuddy, codemaker, codestudio, codex,              │\n│ command-code, continue, cortex, crush, cursor, deepagents, devin, dexto,     │\n│ droid, firebender, forgecode, gemini-cli, github-copilot, goose,             │\n│ hermes-agent, iflow-cli, junie, kilo, kimi-cli, kiro-cli, kode, mcpjam,      │\n│ mistral-vibe, mux, neovate, openclaw, opencode, openhands, pi, pochi, qoder, │\n│ qwen-code, replit, roo, rovodev, tabnine-cli, trae, trae-cn, universal,      │\n│ warp, windsurf, zencoder                                                     │\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\n# Project and global scope\n\nThe CLI installs into one of two scopes. Understanding the difference tells you where skills live and who shares them.\n\n**Project scope is the default.** The CLI records the installed skills in a `skills-lock.json` file in your working directory and materializes the skill folders under `./.agents/skills`. Commit `skills-lock.json` so everyone who clones the repository shares the same skill set. This is the right scope for skills your whole team should use on a given project.\n\n**Global scope (`--global` or `-g`) installs skills for your user account**, across every project.\n\n```shell\ndnx skills add anthropics/skills --global\n```\n\nIn global scope the lock file lives at `~/.local/share/skills/.skill-lock.json` (honoring `XDG_DATA_HOME` if you set it), and the skill folders are materialized under `~/.agents/skills`.\n\nIn both scopes, the CLI materializes each skill once in a canonical store, then makes each targeted agent point at it.\n\n# How skills reach each agent\n\nBy default, the CLI writes each skill once into the canonical store and creates a symlink from every targeted agent's directory back to it. Editing the one canonical copy updates the skill for every agent at once, so you maintain a single source of truth.\n\n```mermaid\nflowchart LR\n  S[\"Source (repo, URL, or local path)\"] --> C[\"Canonical store (.agents/skills)\"]\n  C -. \"symlink\" .-> A1[\".claude/skills\"]\n  C -. \"symlink\" .-> A2[\".windsurf/skills\"]\n  C --> A3[\"Universal agents (.agents/skills is the store)\"]\n```\n\nSome agents read directly from the shared `.agents/skills` store, so their skills directory _is_ that store and no symlink is needed. The [Reference](./reference.md) lists which agents read from the shared store and the directory each agent installs into.\n\nTo copy files instead of symlinking, pass `--copy`. Use it for sandboxed agents that cannot follow symlinks (for example, agents running in containers where symlinks across mounts break):\n\n```shell\ndnx skills add anthropics/skills --copy --agent claude-code --agent windsurf\n```\n\nThe CLI also copies automatically in two cases, so you rarely need `--copy` by hand:\n\n- When a symlink cannot be created (for example, on Windows without the symlink privilege), the CLI falls back to copying for that agent.\n- When every targeted agent shares one skills directory, the CLI copies, because symlinking only makes sense across distinct directories.\n\nA successful install reports which agents were linked or copied and where each skill landed:\n\n```text\nSource: https://github.com/owner/skills.git\nFound 1 skill(s)\n\n┌─Installation Summary─────────────────────────────────────────────────────────┐\n│ Canonical: /your-project/.agents/skills/alpha                                │\n│ Symlinked:  Claude Code, Windsurf                                            │\n└──────────────────────────────────────────────────────────────────────────────┘\n┌─Installed 1 skill(s)─────────────────────────────────────────────────────────┐\n│ ✓ alpha                                                                      │\n│   → /your-project/.claude/skills/alpha                                       │\n└──────────────────────────────────────────────────────────────────────────────┘\n\nDone!  Review skills before use; they run with full agent permissions.\n```\n\nIf everything worked, you should see the `Installation Summary` panel followed by an `Installed N skill(s)` panel and the safety reminder. To confirm later, run `dnx skills list` (see the [Reference](./reference.md)).\n\n# Scan nested skills with --full-depth\n\nBy default, the CLI installs the skill at the source root if one exists there. If the root is not itself a skill, it discovers every nested skill instead. That fast path covers most repositories.\n\nTo find skills in nested and curated directories that the default scan does not reach, pass `--full-depth`:\n\n```shell\ndnx skills add owner/curated-skills --full-depth\n```\n\nThe install reports the same `Installation Summary` and `Installed N skill(s)` panels shown under [How skills reach each agent](#how-skills-reach-each-agent); only the set of discovered skills differs.\n\n`--full-depth` widens _discovery_: it scans nested directories and curated locations (such as `skills/.curated`) so the CLI finds skills the default scan would skip. It does not change clone depth. Clones are always shallow regardless of this flag.\n\n# Install from a private repository\n\nThe CLI never manages or prompts for credentials. It shells out to `git`, which uses your own setup: SSH agent keys, a git credential helper, `gh` authentication, or `~/.netrc`. To avoid hanging on a missing credential, it sets `GIT_TERMINAL_PROMPT=0`, so an unauthenticated clone fails fast with a clear error instead of waiting at a prompt.\n\nTo install from a private repository, make sure your normal git auth already works, then run `add` as usual:\n\n```shell\ndnx skills add owner/private-skills --agent claude-code\n```\n\nThis prints the same `Installation Summary` and `Installed N skill(s)` panels shown under [How skills reach each agent](#how-skills-reach-each-agent), once the clone authenticates.\n\nBefore you install, verify your access with one of:\n\n```shell\nssh -T git@github.com   # confirm your SSH key reaches GitHub\ngh auth login           # or authenticate the GitHub CLI\n```\n\nA working SSH key prints the well-known success line (GitHub closes the connection because it does not provide shell access):\n\n```text\nHi <user>! You've successfully authenticated, but GitHub does not provide shell access.\n```\n\nIf a clone fails with an authentication error, the CLI prints guidance pointing you back to your git credentials. See [Troubleshooting](./troubleshooting.md) for the full list of clone and auth failures.\n\n# Keep skills up to date\n\n`dnx skills update` checks your installed skills for newer versions. It has the aliases `upgrade` and `check`.\n\n```shell\ndnx skills update -g\n```\n\n```text\nChecking for skill updates...\n\nChecking global skill 1/1: my-skill\nFound 1 global update(s)\n\nUpdate available: my-skill\n  Run: skills add owner/repo/skills/my-skill -g -y\n\nUpdates available for 1 skill(s); no updates were applied.\n```\n\n**`update` only reports; it never applies changes.** It prints the exact `skills add ... -y` command to run for each skill that has an update (prefix it with `dnx` when you run through `dnx`). Copy that command and run it yourself to apply the update. The output is explicit: `no updates were applied.`\n\nScope the check the same way you scope an install:\n\n- `-g` (or `--global`) checks global skills only.\n- `-p` (or `--project`) checks project skills only.\n- Pass both, or name specific skills, to check both scopes.\n- With no scope flag in an interactive shell, the CLI prompts you to choose. Non-interactively (for example with `-y`), it checks both scopes.\n\nWhen there is nothing to update, you get a clean report:\n\n```text\nChecking for skill updates...\n\nChecking global skill 1/1: my-skill\nAll global skills are up to date\n```\n\nThe update check calls the GitHub API. If you hit a rate limit, set a `GITHUB_TOKEN` or `GH_TOKEN` environment variable (or sign in with `gh auth login`) and the CLI uses it for the check. See [Troubleshooting](./troubleshooting.md) for rate-limit and timeout details.\n\n# Remove skills\n\n`dnx skills remove` uninstalls skills. It unlinks each agent's copy and removes the canonical store entry once no remaining agent references it, then updates the lock file.\n\nTo remove specific skills by name, list them:\n\n```shell\ndnx skills remove alpha --yes\n```\n\n```text\nSuccessfully removed 1 skill(s)\n```\n\nTo remove everything, pass `--all`:\n\n```shell\ndnx skills remove --all\n```\n\n```text\nSuccessfully removed 1 skill(s)\n```\n\nTo limit removal to specific agents, add `--agent`. To target your user-level skills, add `--global`.\n\nRun `dnx skills remove` with no names to remove interactively: the CLI shows a multi-select prompt, then a confirmation that defaults to **no**. Declining cancels and removes nothing:\n\n```text\n$ dnx skills remove\n\nRemoval cancelled\n```\n\nIf a named skill is not installed, the CLI tells you and exits cleanly without changing anything:\n\n```text\nNo matching skills found for: nope\n```\n\n# Next steps\n\n- [Authoring Skills](./authoring-skills.md): write and publish your own `SKILL.md` with `dnx skills init`.\n- [Reference](./reference.md): every command, flag, the full list of 55+ agents, and per-agent install directories.\n- [Troubleshooting](./troubleshooting.md): clone failures, authentication errors, rate limits, and symlink fallbacks.\n\n<!-- File: website/content/docs/skills/reference.md (Tokens: ~5596 | Category: anthropic-skill) -->\n---\ntitle: \"Reference\"\ndescription: \"Complete `skills` CLI reference covering every command and flag, JSON output, exit codes, environment variables, file locations, and supported agents.\"\n---\n\nThis page is the complete, precise reference for the `skills` command surface, JSON output, exit codes, environment variables, file locations, and supported agents. It is meant for lookup, not for learning. To learn by doing, start at [Installing Skills](./installing-skills.md) and [Authoring Skills](./authoring-skills.md).\n\nEvery command prints the same per-command help at the terminal. Run `dnx skills <command> --help` to see the synopsis, arguments, and options for that command.\n\n```shell\ndnx skills add --help\n```\n\n```text\nDescription:\n  Add a skill from a source\n\nUsage:\n  skills add [<source>] [options]\n\nArguments:\n  <source>  Source to fetch skills from (e.g., owner/repo, URL, local path)\n\nOptions:\n  -g, --global    Install globally\n  -a, --agent     Target agent(s)\n  -s, --skill     Skill name filter(s)\n  -y, --yes       Skip prompts (non-interactive)\n  --all           Install all skills to all agents\n  --copy          Copy instead of symlinking\n  --full-depth    Scan nested directories for skills\n  -l, --list      List available skills without installing\n  -?, -h, --help  Show help and usage information\n```\n\n> The binary on your PATH is `skills`. Install it with `#!shell dotnet tool install -g skills`, or run it without installing via `dnx skills <command>` (requires the .NET 10 SDK or later). Both forms accept the same commands, arguments, and options documented below.\n\n# Commands\n\n`skills` has five commands: `add`, `remove`, `list`, `update`, and `init`. Each command's options are independent. There are no shared global options beyond `--help` and `--version` (see [Global flags](#global-flags)).\n\n## skills add &lt;source&gt;\n\nAdd skills from a source. Skills are discovered at the source, then materialized into a canonical store and linked into each target agent's skills directory.\n\n```text\ndnx skills add <source> [options]\n```\n\n### Arguments\n\n| Argument | Arity | Required | Description                                                                                                                                                        |\n| -------- | ----- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `source` | one   | yes      | Source to fetch skills from (for example `owner/repo`, a full git URL, or a local path). If omitted, the command exits 1 with `Missing required argument: source`. |\n\n### Options\n\n| Option         | Alias  | Type                | Default         | Description                                                                                                                                                                                         |\n| -------------- | ------ | ------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--global`     | `-g`   | bool                | `false`         | Install to the global scope (your home directory) instead of the current project.                                                                                                                   |\n| `--agent`      | `-a`   | string (repeatable) | (auto-detected) | Target agent(s). Repeatable and space-separated (`--agent claude-code cursor` or `--agent claude-code --agent cursor`). `--agent *` targets every agent. See [Supported agents](#supported-agents). |\n| `--skill`      | `-s`   | string (repeatable) | (all)           | Install only skills whose name matches the given filter(s). Repeatable.                                                                                                                             |\n| `--yes`        | `-y`   | bool                | `false`         | Skip all prompts and run non-interactively.                                                                                                                                                         |\n| `--all`        | (none) | bool                | `false`         | Install all skills to all agents. Implies `--skill *`, `--agent *`, and `--yes`.                                                                                                                    |\n| `--copy`       | (none) | bool                | `false`         | Copy skill files into each agent directory instead of symlinking. Use for agents that do not follow symlinks.                                                                                       |\n| `--full-depth` | (none) | bool                | `false`         | Widen discovery to scan nested directories in the source, not only the source root. This does not change the git clone (clones are always shallow).                                                 |\n| `--list`       | `-l`   | bool                | `false`         | List the available skills at the source without installing anything, then exit.                                                                                                                     |\n\nThe default install mode is symlink: the CLI materializes each skill once into a canonical store and creates a relative symlink from each agent directory back to it. Pass `--copy` to copy instead. When every selected agent shares one skills directory, copy is used automatically.\n\nFor sources, scopes, and install mechanics, see [Installing Skills](./installing-skills.md). For agent targeting, see [Supported agents](#supported-agents).\n\n## skills remove [skills...]\n\nRemove installed skills. With no skill names and an interactive terminal, the CLI prompts you to select which skills to remove.\n\n```text\ndnx skills remove [skills...] [options]\n```\n\n### Arguments\n\n| Argument | Arity        | Required | Description                                                                                          |\n| -------- | ------------ | -------- | ---------------------------------------------------------------------------------------------------- |\n| `skills` | zero or more | no       | Skill names to remove. Matched case-insensitively. With no names and no `--all`, runs interactively. |\n\n### Options\n\n| Option     | Alias  | Type                | Default | Description                                                  |\n| ---------- | ------ | ------------------- | ------- | ------------------------------------------------------------ |\n| `--global` | `-g`   | bool                | `false` | Remove from the global scope instead of the current project. |\n| `--agent`  | `-a`   | string (repeatable) | (all)   | Limit removal to specific agent(s). Repeatable.              |\n| `--yes`    | `-y`   | bool                | `false` | Skip prompts and run non-interactively.                      |\n| `--all`    | (none) | bool                | `false` | Remove every installed skill.                                |\n\nIn interactive mode, the CLI shows a multiselect prompt followed by a confirmation prompt. The confirmation defaults to no. Declining the confirmation prints `Removal cancelled` and exits with code 130 (see [Exit codes](#exit-codes)).\n\n```text\n$ dnx skills remove alpha\n# exit 130\n\nRemoval cancelled\n```\n\n## skills list\n\nList installed skills. With no options, lists the current project's skills.\n\n```text\ndnx skills list [options]\n```\n\nThis command takes no positional arguments.\n\n### Options\n\n| Option     | Alias  | Type                | Default | Description                                                                           |\n| ---------- | ------ | ------------------- | ------- | ------------------------------------------------------------------------------------- |\n| `--global` | `-g`   | bool                | `false` | List skills in the global scope instead of the current project.                       |\n| `--agent`  | `-a`   | string (repeatable) | (none)  | Filter the listing to specific agent(s). Repeatable.                                  |\n| `--format` | (none) | `text` \\| `json`    | `text`  | Output format. `json` emits a JSON array to stdout (see [JSON output](#json-output)). |\n| `--json`   | (none) | bool                | `false` | Shorthand for `--format json`.                                                        |\n\nJSON output is enabled when either `--json` is present or `--format json` is set (case-insensitive). Enabling JSON suppresses the banner and writes the array to stdout.\n\n## skills update [skills...]\n\nCheck for available updates and print the exact command to apply each one.\n\n```text\ndnx skills update [skills...] [options]\n```\n\n> Aliases: `upgrade` and `check`. `dnx skills upgrade` and `dnx skills check` are identical to `dnx skills update`.\n\n> [!WARNING]\n> **`update` only reports.** It never modifies files or lock files. For each skill that has an update, it prints a `skills add ...` command you can copy and run to apply it (run it as `dnx skills add ...` if you use `dnx`). The command always exits 0, even when updates are available. Its output ends with `no updates were applied.`\n\n### Arguments\n\n| Argument | Arity        | Required | Description                                                                                                        |\n| -------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------ |\n| `skills` | zero or more | no       | Optional skill names to check. Scope is resolved the same way with or without names (see the scope options below). |\n\n### Options\n\n| Option      | Alias | Type | Default | Description                                                                |\n| ----------- | ----- | ---- | ------- | -------------------------------------------------------------------------- |\n| `--global`  | `-g`  | bool | `false` | Check global skills only.                                                  |\n| `--project` | `-p`  | bool | `false` | Check project skills only.                                                 |\n| `--yes`     | `-y`  | bool | `false` | Skip the interactive scope prompt. Non-interactive runs check both scopes. |\n\nWith neither `-g` nor `-p`, an interactive terminal prompts you to choose Project, Global, or Both. Passing both flags, or running non-interactively, checks both scopes.\n\n```text\n$ dnx skills update -g\n\nChecking for skill updates...\n\nChecking global skill 1/1: my-skill\nFound 1 global update(s)\n\nUpdate available: my-skill\n  Run: skills add owner/repo/skills/my-skill -g -y\n\nUpdates available for 1 skill(s); no updates were applied.\n```\n\n## skills init [name]\n\nScaffold a new skill directory containing a `SKILL.md` template. This command has no options.\n\n```text\ndnx skills init [name]\n```\n\n### Arguments\n\n| Argument | Arity       | Required | Description                                                                                                                                                       |\n| -------- | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `name`   | zero or one | no       | Skill name. Creates `<name>/SKILL.md`. The name is sanitized to a slug. With no name, derives the slug from the current directory and writes `SKILL.md` in place. |\n\nIf the target `SKILL.md` already exists, the CLI does not overwrite it. It prints `Skill already exists at <path>` and exits 0.\n\n```text\n$ dnx skills init my-skill\n\nInitialized skill: my-skill\n\nCreated:\n  my-skill/SKILL.md\n\nNext steps:\n  1. Edit my-skill/SKILL.md to define your skill instructions\n  2. Update the name and description in the frontmatter\n\nPublishing:\n  GitHub: Push to a repo, then skills add <owner>/<repo>\n  URL:    Host the file, then skills add https://example.com/my-skill/SKILL.md\n```\n\nSee [Authoring Skills](./authoring-skills.md) for the `SKILL.md` format and publishing workflow.\n\n## Global flags\n\nThese are provided on the root command and on every subcommand.\n\n| Option      | Aliases    | Type | Description                                            |\n| ----------- | ---------- | ---- | ------------------------------------------------------ |\n| `--help`    | `-h`, `-?` | bool | Show help. On a subcommand, shows that command's help. |\n| `--version` | (none)     | bool | Print the installed CLI version and exit 0.            |\n\nRunning `skills` with no arguments shows the banner and exits 0. Running `#!shell dnx skills --help` shows curated top-level help. A bare `--` token is removed before parsing, so `#!shell dnx skills add --agent codex -- owner/repo` parses the same as without it.\n\n# JSON output\n\n`#!shell dnx skills list --json` (equivalently `#!shell dnx skills list --format json`) prints a JSON array to stdout. Each element describes one installed skill.\n\n```shell\ndnx skills list --json\n```\n\n```json\n[\n  {\n    \"name\": \"alpha\",\n    \"path\": \"/home/you/project/.agents/skills/alpha\",\n    \"scope\": \"project\",\n    \"agents\": [\"Claude Code\", \"Windsurf\"]\n  }\n]\n```\n\n| Field    | Type     | Description                                                                                                                |\n| -------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |\n| `name`   | string   | The skill's sanitized name (its on-disk directory name).                                                                   |\n| `path`   | string   | Absolute path to the skill in the canonical store.                                                                         |\n| `scope`  | string   | `\"project\"` or `\"global\"`. `\"global\"` when listed with `-g`, otherwise `\"project\"`.                                        |\n| `agents` | string[] | Display names of agents linked to this skill (for example `Claude Code`). Empty when the skill is not linked to any agent. |\n\nThe array is written to stdout, so you can pipe it to a tool such as `jq`. Banner and progress output are suppressed in JSON mode.\n\n# Exit codes\n\n`skills` uses exactly three exit codes.\n\n| Code  | Name      | Meaning                                                                                                                                        |\n| ----- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| `0`   | Success   | The command completed. Note that `update` exits 0 even when updates are available, and `remove` exits 0 when there is nothing to remove.       |\n| `1`   | Failure   | The command failed (for example an invalid agent name, no valid skills found, or a file system error). The error message is written to stderr. |\n| `130` | Cancelled | The operation was cancelled, either by declining an interactive confirmation or by pressing Ctrl+C.                                            |\n\n# Environment variables\n\n| Variable                  | Default          | Effect                                                                                                                                                            |\n| ------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `SKILLS_CLONE_TIMEOUT_MS` | `300000`         | Git clone timeout in milliseconds (5 minutes). Must parse to a positive integer, otherwise the default is used. Raise it for large repositories or slow networks. |\n| `GITHUB_TOKEN`            | (unset)          | A GitHub API token. Used only by `update` to raise GitHub API rate limits when checking for updates. Not used for cloning.                                        |\n| `GH_TOKEN`                | (unset)          | Fallback GitHub API token. Consulted by `update` after `GITHUB_TOKEN`. Same effect.                                                                               |\n| `INSTALL_INTERNAL_SKILLS` | (unset)          | Set to `1` or `true` to include skills their authors marked as internal in discovery. By default such skills are hidden.                                          |\n| `CLAUDE_CONFIG_DIR`       | `~/.claude`      | Overrides the Claude Code configuration directory used for detection and global installs.                                                                         |\n| `CODEX_HOME`              | `~/.codex`       | Overrides the Codex configuration directory used for detection and global installs.                                                                               |\n| `VIBE_HOME`               | `~/.vibe`        | Overrides the Mistral Vibe configuration directory used for detection and global installs.                                                                        |\n| `XDG_DATA_HOME`           | `~/.local/share` | Root for the global lock location. The global lock lives at `$XDG_DATA_HOME/skills/.skill-lock.json`.                                                             |\n\n`XDG_CONFIG_HOME` (default `~/.config`) and `XDG_STATE_HOME` (default `~/.local/state`) affect where the CLI keeps its own configuration and logs, and where several agents resolve their global directories.\n\nFor private repositories, the CLI shells out to `git` and uses your existing git credentials (SSH agent, credential helper, `gh` auth). See [Troubleshooting](./troubleshooting.md) for authentication and rate-limit guidance.\n\n# File locations\n\nThe CLI writes a lock file per scope and materializes skills into a canonical store. Project scope is the current working directory; global scope is your home directory.\n\n| Scope   | Lock file                                                                              | Canonical skills store |\n| ------- | -------------------------------------------------------------------------------------- | ---------------------- |\n| Project | `skills-lock.json` (in the current working directory)                                  | `./.agents/skills`     |\n| Global  | `~/.local/share/skills/.skill-lock.json` (or `$XDG_DATA_HOME/skills/.skill-lock.json`) | `~/.agents/skills`     |\n\nNon-universal agents receive a symlink from their own directory (for example `.claude/skills/<name>`) back into the canonical store. Universal agents use the canonical store directly. See [Supported agents](#supported-agents) for per-agent directories.\n\n# Supported agents\n\nThe `skills` CLI supports 55+ agents. It detects which agents are installed on your machine by probing each agent's configuration directory, and it detects which agent it is running inside by reading environment variables that agent hosts set. When run inside a detected agent, `add` runs non-interactively and targets that agent plus the universal agents.\n\nAgent identifiers are case-sensitive (the identifier is `github-copilot`, not `copilot`). The `--agent` option is repeatable and accepts multiple values per token. `--agent *` targets all agents. \"Universal\" agents share the `.agents/skills` store, so installing a skill for one universal agent makes it visible to all of them.\n\nIn the table below, project directories are relative to the working directory and global directories are absolute (`~` is your home directory, `<config>` is `$XDG_CONFIG_HOME` or `~/.config`). Agents marked \"universal\" use the shared `.agents/skills` store at project scope.\n\n| Identifier       | Display name       | Project directory            | Global directory                             |\n| ---------------- | ------------------ | ---------------------------- | -------------------------------------------- |\n| `adal`           | AdaL               | `.adal/skills`               | `~/.adal/skills`                             |\n| `aider-desk`     | AiderDesk          | `.aider-desk/skills`         | `~/.aider-desk/skills`                       |\n| `amp`            | Amp                | `.agents/skills` (universal) | `<config>/agents/skills`                     |\n| `antigravity`    | Antigravity        | `.agents/skills` (universal) | `~/.gemini/antigravity/skills`               |\n| `augment`        | Augment            | `.augment/skills`            | `~/.augment/skills`                          |\n| `bob`            | IBM Bob            | `.bob/skills`                | `~/.bob/skills`                              |\n| `claude-code`    | Claude Code        | `.claude/skills`             | `~/.claude/skills` (via `CLAUDE_CONFIG_DIR`) |\n| `cline`          | Cline              | `.agents/skills` (universal) | `~/.agents/skills`                           |\n| `codearts-agent` | CodeArts Agent     | `.codeartsdoer/skills`       | `~/.codeartsdoer/skills`                     |\n| `codebuddy`      | CodeBuddy          | `.codebuddy/skills`          | `~/.codebuddy/skills`                        |\n| `codemaker`      | Codemaker          | `.codemaker/skills`          | `~/.codemaker/skills`                        |\n| `codestudio`     | Code Studio        | `.codestudio/skills`         | `~/.codestudio/skills`                       |\n| `codex`          | Codex              | `.agents/skills` (universal) | `~/.codex/skills` (via `CODEX_HOME`)         |\n| `command-code`   | Command Code       | `.commandcode/skills`        | `~/.commandcode/skills`                      |\n| `continue`       | Continue           | `.continue/skills`           | `~/.continue/skills`                         |\n| `cortex`         | Cortex Code        | `.cortex/skills`             | `~/.snowflake/cortex/skills`                 |\n| `crush`          | Crush              | `.crush/skills`              | `~/.config/crush/skills`                     |\n| `cursor`         | Cursor             | `.agents/skills` (universal) | `~/.cursor/skills`                           |\n| `deepagents`     | Deep Agents        | `.agents/skills` (universal) | `~/.deepagents/agent/skills`                 |\n| `devin`          | Devin for Terminal | `.devin/skills`              | `<config>/devin/skills`                      |\n| `dexto`          | Dexto              | `.agents/skills` (universal) | `~/.agents/skills`                           |\n| `droid`          | Droid              | `.factory/skills`            | `~/.factory/skills`                          |\n| `firebender`     | Firebender         | `.agents/skills` (universal) | `~/.firebender/skills`                       |\n| `forgecode`      | ForgeCode          | `.forge/skills`              | `~/.forge/skills`                            |\n| `gemini-cli`     | Gemini CLI         | `.agents/skills` (universal) | `~/.gemini/skills`                           |\n| `github-copilot` | GitHub Copilot     | `.agents/skills` (universal) | `~/.copilot/skills`                          |\n| `goose`          | Goose              | `.goose/skills`              | `<config>/goose/skills`                      |\n| `hermes-agent`   | Hermes Agent       | `.hermes/skills`             | `~/.hermes/skills`                           |\n| `iflow-cli`      | iFlow CLI          | `.iflow/skills`              | `~/.iflow/skills`                            |\n| `junie`          | Junie              | `.junie/skills`              | `~/.junie/skills`                            |\n| `kilo`           | Kilo Code          | `.kilocode/skills`           | `~/.kilocode/skills`                         |\n| `kimi-cli`       | Kimi Code CLI      | `.agents/skills` (universal) | `~/.config/agents/skills`                    |\n| `kiro-cli`       | Kiro CLI           | `.kiro/skills`               | `~/.kiro/skills`                             |\n| `kode`           | Kode               | `.kode/skills`               | `~/.kode/skills`                             |\n| `mcpjam`         | MCPJam             | `.mcpjam/skills`             | `~/.mcpjam/skills`                           |\n| `mistral-vibe`   | Mistral Vibe       | `.vibe/skills`               | `~/.vibe/skills` (via `VIBE_HOME`)           |\n| `mux`            | Mux                | `.mux/skills`                | `~/.mux/skills`                              |\n| `neovate`        | Neovate            | `.neovate/skills`            | `~/.neovate/skills`                          |\n| `openclaw`       | OpenClaw           | `skills`                     | `~/.openclaw/skills`                         |\n| `opencode`       | OpenCode           | `.agents/skills` (universal) | `<config>/opencode/skills`                   |\n| `openhands`      | OpenHands          | `.openhands/skills`          | `~/.openhands/skills`                        |\n| `pi`             | Pi                 | `.pi/skills`                 | `~/.pi/agent/skills`                         |\n| `pochi`          | Pochi              | `.pochi/skills`              | `~/.pochi/skills`                            |\n| `qoder`          | Qoder              | `.qoder/skills`              | `~/.qoder/skills`                            |\n| `qwen-code`      | Qwen Code          | `.qwen/skills`               | `~/.qwen/skills`                             |\n| `replit`         | Replit             | `.agents/skills` (universal) | `<config>/agents/skills`                     |\n| `roo`            | Roo Code           | `.roo/skills`                | `~/.roo/skills`                              |\n| `rovodev`        | Rovo Dev           | `.rovodev/skills`            | `~/.rovodev/skills`                          |\n| `tabnine-cli`    | Tabnine CLI        | `.tabnine/agent/skills`      | `~/.tabnine/agent/skills`                    |\n| `trae`           | Trae               | `.trae/skills`               | `~/.trae/skills`                             |\n| `trae-cn`        | Trae CN            | `.trae/skills`               | `~/.trae-cn/skills`                          |\n| `universal`      | Universal          | `.agents/skills` (universal) | `<config>/agents/skills`                     |\n| `warp`           | Warp               | `.agents/skills` (universal) | `~/.agents/skills`                           |\n| `windsurf`       | Windsurf           | `.windsurf/skills`           | `~/.codeium/windsurf/skills`                 |\n| `zencoder`       | Zencoder           | `.zencoder/skills`           | `~/.zencoder/skills`                         |\n\nPassing an unknown identifier exits 1 and prints the full list of valid identifiers:\n\n```text\n$ dnx skills add ./local-path --yes --agent bogus\n# exit 1\n\nInvalid agents: bogus\n```\n\n# See also\n\n- [Installing Skills](./installing-skills.md): sources, scopes, and the install workflow in depth.\n- [Authoring Skills](./authoring-skills.md): the `SKILL.md` format, `dnx skills init`, and publishing.\n- [Troubleshooting](./troubleshooting.md): authentication, rate limits, timeouts, and common errors.\n\n<!-- File: website/content/docs/skills/structure.yaml (Tokens: ~85 | Category: anthropic-skill) -->\ntitle: Skills\nitems:\n  - path: index\n    title: Introduction\n  - path: getting-started\n    title: Getting Started\n  - path: installing-skills\n    title: Installing Skills\n  - path: authoring-skills\n    title: Authoring Skills\n  - path: reference\n    title: Reference\n  - path: troubleshooting\n    title: Troubleshooting\n\n<!-- File: website/content/docs/skills/troubleshooting.md (Tokens: ~3527 | Category: anthropic-skill) -->\n---\ntitle: \"Troubleshooting\"\ndescription: \"Troubleshoot `skills` CLI errors: each section maps the exact message the CLI prints to its cause and a copy-pasteable fix for installing and updating skills.\"\n---\n\nThis page maps the errors and surprises you hit when running `skills` to their cause and fix. Each section starts with the exact message the CLI prints (where one exists), explains why it happens, and gives you a copy-pasteable way out.\n\nIf you are new to `skills`, start with [Getting Started](./getting-started.md). For the full command and flag surface, see the [Reference](./reference.md). For what each agent identifier means and where skills land, see [Installing Skills](./installing-skills.md).\n\n# \"No valid skills found. Skills require a SKILL.md with name and description.\"\n\nYou ran `dnx skills add <source>` and the CLI reached the source but found nothing to install:\n\n```text\n$ dnx skills add ./my-skills --yes --agent claude-code\n# exit 1\n\nSource: /home/you/my-skills\nNo valid skills found. Skills require a SKILL.md with name and description.\n```\n\nCause: a skill is a directory that contains a `SKILL.md` file with both `name` and `description` in its YAML frontmatter. The CLI silently skips any folder that is missing the file, missing either field, or whose `name`/`description` collapses to empty. By default, it only looks at the source root (or the subpath you pointed it at), so a `SKILL.md` buried in a nested directory is not discovered.\n\nTo see exactly what the CLI finds without installing anything, run `--list`:\n\n```shell\ndnx skills add owner/repo --list\n```\n\n```text\nSource: https://github.com/owner/repo.git\nFound 2 skill(s)\n\nAvailable Skills\n  alpha\n    the alpha skill\n  beta\n    the beta skill\n\nUse --skill <name> to install specific skills\n```\n\nIf `--list` reports `Found 0 skill(s)`, work through these in order:\n\n| Check                                                     | Fix                                                                                                                            |\n| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| Is your path or subpath pointing at the right folder?     | Point at the directory that contains `SKILL.md`, or add the repo subpath: `#!shell dnx skills add owner/repo/skills/my-skill`. |\n| Does the `SKILL.md` have both `name:` and `description:`? | Add the missing field. Both must be non-empty. See [Authoring Skills](./authoring-skills.md).                                  |\n| Are the skills in nested directories?                     | Add `--full-depth` to scan nested directories: `#!shell dnx skills add owner/repo --full-depth --list`.                        |\n\n> `--full-depth` widens discovery so the CLI scans nested directories for skills. It does not change how much of the repository is cloned. Clones are always shallow regardless of this flag.\n\n# \"Invalid agents: &lt;name&gt;\"\n\nYou passed an `--agent` value that the CLI does not recognize:\n\n```text\n$ dnx skills add ./my-skills --yes --agent bogus\n# exit 1\n\nSource: /home/you/my-skills\nFound 1 skill(s)\n\n┌─Invalid agents───────────────────────────────────────────────────────────────┐\n│ Invalid agents: bogus                                                        │\n│                                                                              │\n│ Valid agents: adal, aider-desk, amp, antigravity, augment, bob, claude-code, │\n│ cline, codearts-agent, codebuddy, codemaker, codestudio, codex,              │\n│ command-code, continue, cortex, crush, cursor, deepagents, devin, dexto,     │\n│ droid, firebender, forgecode, gemini-cli, github-copilot, goose,             │\n│ hermes-agent, iflow-cli, junie, kilo, kimi-cli, kiro-cli, kode, mcpjam,      │\n│ mistral-vibe, mux, neovate, openclaw, opencode, openhands, pi, pochi, qoder, │\n│ qwen-code, replit, roo, rovodev, tabnine-cli, trae, trae-cn, universal,      │\n│ warp, windsurf, zencoder                                                     │\n└──────────────────────────────────────────────────────────────────────────────┘\n```\n\nCause: the value is misspelled or uses the wrong case. Agent identifiers are case-sensitive, and several differ from the product's marketing name. The most common mistakes:\n\n| You typed                   | Use instead      |\n| --------------------------- | ---------------- |\n| `copilot`, `github_copilot` | `github-copilot` |\n| `Claude-Code`, `claude`     | `claude-code`    |\n| `gemini`                    | `gemini-cli`     |\n| `roo-code`                  | `roo`            |\n\nThe error panel always prints every valid identifier, so copy the correct one from the list. The same `Invalid agents: <name>` message appears (without the panel) from `dnx skills list` and `dnx skills remove`. For the full table of identifiers and where each one installs skills, see [Installing Skills](./installing-skills.md) and the [Reference](./reference.md).\n\n# Cloning a private repository fails with \"Authentication failed\"\n\n`dnx skills add` reports an authentication error and stops before installing.\n\nCause: the CLI never prompts for credentials. It shells out to your own `git`, which uses your existing setup (SSH agent keys, a git credential helper, `gh` auth, or `~/.netrc`). When git cannot authenticate, the CLI surfaces the failure instead of hanging. Any credentials embedded in a URL are redacted from the output, so secrets never appear in errors or in the lock file.\n\nTo fix it, confirm your machine can reach the repository, then retry the same `dnx skills add` command.\n\nFor SSH sources (`git@github.com:owner/repo.git`):\n\n```shell\nssh -T git@github.com\n# Hi <you>! You've successfully authenticated, but GitHub does not provide shell access.\n```\n\nFor HTTPS sources, authenticate with the GitHub CLI or configure a git credential helper. These are one-time setup commands whose output varies by environment:\n\n```shell\ngh auth login                         # uses the gh credential helper\n# or\ngit config --global credential.helper store\n```\n\nAfter `gh auth login` completes, it confirms the authenticated account.\n\nOnce `git clone <repo>` succeeds on its own, `dnx skills add <repo>` will succeed too.\n\n# The clone times out\n\nA large repository can exceed the default clone budget and cause the CLI to abort the fetch.\n\nCause: the CLI caps each clone at 5 minutes (300000 ms). The clone is always shallow (latest commit only), but a very large repository or a slow connection can still run past the limit.\n\nTo raise the timeout, set `SKILLS_CLONE_TIMEOUT_MS` in milliseconds before running the command:\n\n```shell\nSKILLS_CLONE_TIMEOUT_MS=600000 dnx skills add owner/big-repo --agent claude-code   # 10 minutes\n```\n\nWith the longer budget the clone finishes and the install completes with the usual `Installed 1 skill(s)` panel.\n\nAlternatively, clone the repository yourself and point `skills` at the local copy. This skips the network step entirely:\n\n```shell\ngit clone --depth 1 https://github.com/owner/big-repo.git\ndnx skills add ./big-repo --agent claude-code\n```\n\nPointing `skills` at the local clone installs the skill without touching the network and prints the same `Installed 1 skill(s)` panel.\n\n# A skill does not appear for one agent\n\n`dnx skills add` reports success, the skill shows up in `dnx skills list`, but one of your agents does not see it.\n\nCause: agents that keep skills in their own directory (for example `.claude/skills` for Claude Code or `.windsurf/skills` for Windsurf) only get a link when that agent's directory already exists in your project. The CLI will not create a config directory for an agent you do not use. When the directory is missing, it skips the link for that agent but still materializes the skill in the shared `.agents/skills` store, so the skill is installed; it is only the per-agent link that is missing.\n\nPick whichever fix matches your intent:\n\n| Goal                                                           | Fix                                                                                                                                   |\n| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |\n| You do use that agent in this project                          | Create its directory, then re-run the install: `#!shell mkdir -p .claude && dnx skills add owner/repo --agent claude-code`.           |\n| You want a self-contained copy regardless of agent directories | Add `--copy` to write the skill straight into each agent's directory: `#!shell dnx skills add owner/repo --agent claude-code --copy`. |\n| You meant a different agent                                    | Re-run with the correct `--agent` value. See [Installing Skills](./installing-skills.md).                                             |\n\nAfter the directory exists, re-running the install links the skill into `.claude/skills`. The Installation Summary then lists `Symlinked:  Claude Code` instead of skipping that agent.\n\nAgents that share the universal `.agents/skills` store (Cursor, Codex, GitHub Copilot, Gemini CLI, and others) always see the skill because their directory is the canonical store.\n\n# Symlinks are not created (Windows)\n\nOn Windows, `skills` copies skills into agent directories instead of linking them.\n\nCause: creating a symlink on Windows requires either an elevated process or Developer Mode. When the CLI cannot create the link, it automatically falls back to copying the skill so the install still succeeds. The skill works either way; the only difference is that copies do not share a single editable source of truth the way symlinks do.\n\nTo get symlinks instead of copies, choose one:\n\n- Enable Developer Mode (Settings, \"For developers\", \"Developer Mode\"), then re-run the command.\n- Run your terminal elevated (\"Run as administrator\") and re-run the command.\n\nIf you prefer copies and want the CLI to copy without attempting a symlink first, pass `--copy` explicitly:\n\n```shell\ndnx skills add owner/repo --agent claude-code --copy\n```\n\nThe output shows the skill was copied rather than linked: the Installation Summary lists `Copied:  Claude Code`, and the skill is written directly into `.claude/skills`.\n\n# \"skills update\" cannot check a skill or hits a rate limit\n\n`dnx skills update` reports that one or more skills could not be checked:\n\n```text\n$ dnx skills update -g\n\nChecking for skill updates...\n\n\n1 skill(s) cannot be checked automatically:\n  * legacy (Private or deleted repo)\n    To update: skills add https://github.com/owner/repo -g -y\n```\n\nCause: `update` checks for newer versions by calling the GitHub API, and unauthenticated calls are rate-limited. It also cannot diff every kind of source. Skills installed from a local path, a generic git URL, a well-known HTTP source, or a private or deleted repository have no checkable remote tree, so they are reported as \"cannot be checked automatically\" with a manual refresh hint.\n\nTo raise the rate limit, give `skills` a GitHub token and re-run. The CLI reads `GITHUB_TOKEN`, then `GH_TOKEN`, then falls back to `gh auth token`:\n\n```shell\nexport GITHUB_TOKEN=ghp_...   # or: gh auth login\ndnx skills update\n```\n\nWith the token in place the rate limit clears and the check completes:\n\n```text\nChecking for skill updates...\n\nAll skills are up to date.\n```\n\nFor sources that can never be checked automatically, re-install with `dnx skills add` to refresh them. The `update` output prints the exact command to run for each one:\n\n```shell\ndnx skills add owner/repo/skills/my-skill -y\n```\n\nThe refresh re-installs the skill from its source and prints the usual `Installed 1 skill(s)` panel.\n\n> `dnx skills update` only checks for and reports available updates. It never applies them. Whatever it finds, it prints the precise `skills add ...` command for you to run (prefix it with `dnx` when you use `dnx`). The aliases `dnx skills upgrade` and `dnx skills check` behave identically. See the [Reference](./reference.md).\n\n# \"... is newer than this skills supports\"\n\nA command refuses to write to a lock file and reports that the on-disk version is newer than this version of `skills` supports.\n\nCause: the lock file (`skills-lock.json` in your project, or the global `.skill-lock.json`) was written by a newer version of `skills` than the one you are running. The CLI reads newer lock files but refuses to modify them, so it does not corrupt state written by a version it does not understand.\n\nTo fix it, update `skills` to the latest release:\n\n```shell\ndotnet tool update -g skills\n```\n\nA successful upgrade reports the version change:\n\n```text\nTool 'skills' was successfully updated from version 0.1.0 to version 0.3.0.\n```\n\nIf you no longer need the existing lock state and want to start fresh, delete the lock file and re-install your skills. The project lock lives at `skills-lock.json` in your working directory; the global lock lives at `~/.local/share/skills/.skill-lock.json` (or under `$XDG_DATA_HOME/skills` if that variable is set).\n\n> [!WARNING]\n> **Deleting a lock file discards update tracking.** The CLI uses the lock file to know what is installed and to check for updates. After deleting it, run `dnx skills add` again for each skill so the CLI can rebuild the lock. The installed skill folders themselves are not removed by deleting the lock.\n\n# Bundled binary assets are missing from a skill\n\nA skill installs, but a binary file it ships (an image, a model, a compiled tool) is a tiny placeholder or absent.\n\nCause: the CLI disables Git LFS while cloning, so only LFS pointer files are fetched, not the large binaries they track. This keeps clones fast and shallow, but it means LFS-tracked assets do not arrive with the skill.\n\nTo fix it, change how the skill stores its assets:\n\n- Store skill assets without Git LFS so they travel as ordinary files in the repository.\n- Vendor the assets directly into the skill folder (commit the real files alongside `SKILL.md`).\n\nIf you author the skill yourself, see [Authoring Skills](./authoring-skills.md) for how to lay out bundled resources.\n\n# \"Failed to remove\" a skill\n\n`dnx skills remove` reports that it could not remove a skill:\n\n```text\n$ dnx skills remove \"My Skill\" --yes\n# exit 1\n\nFailed to remove 1 skill(s)\n  My Skill: ...\n```\n\nCause: the CLI removes a skill by the sanitized, lowercase, hyphenated name it uses on disk (for example `my-skill`). A folder created outside `skills` whose name does not match that sanitized form is not something the CLI will delete automatically, so it reports the failure rather than falsely claiming success. The CLI also refuses to delete a real non-empty directory or file it did not create, which protects your own data.\n\nTo fix it, delete the folder yourself from the skills directory. For a project install that is `./.agents/skills/<folder>`; for the corresponding agent directory it is, for example, `./.claude/skills/<folder>`. For a global install the canonical store is `~/.agents/skills/<folder>`.\n\n```shell\nrm -rf \"./.agents/skills/My Skill\"\n```\n\nRun `dnx skills list` afterward to confirm the skill is gone. The listing no longer shows the removed skill:\n\n```text\n$ dnx skills list\n\nNo project skills found.\nTry listing global skills with -g\n```\n\n# Next steps\n\n- [Reference](./reference.md): every command, flag, exit code, and environment variable in one place.\n- [Installing Skills](./installing-skills.md): sources, scopes, agent targeting, and the symlink versus copy model.\n- Still stuck? Ask in the [ChilliCream Slack](https://slack.chillicream.com/).\n\n<!-- File: src/HotChocolate/CostAnalysis/tools/oracle/README.md (Tokens: ~1559 | Category: plugin-manifest) -->\n# Cost differential oracle\n\nRegenerates the vendored ExactCase cost corpus\n(`../../test/CostAnalysis.Core.Conformance.Tests/__resources__/rust-corpus/`)\nfrom the MIT-licensed\n[`graphql-static-analysis-rs`](https://github.com/duckki/graphql-static-analysis-rs)\ncrate, the differential oracle for this cost analysis implementation.\n\n## Prerequisites\n\nCorpus regeneration and live differential runs require rustup with stable\nRust >= 1.90 (the pinned commit's `rust-version`) and a C++ compiler. The\ncrate's `fuzz` package links `libfuzzer-sys` 0.4 unconditionally, including\nfor a plain `cargo build` or `cargo run`. Install Rust with:\n\n```bash\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal\n. \"$HOME/.cargo/env\" && rustup toolchain install stable\n```\n\nThe scripts install nothing. `clone-oracle.sh` and `run-nightly.sh` print the\ninstall line when `cargo` is missing, and `run-nightly.sh` also rejects Rust\nversions below 1.90 and missing C++ compilers. Pull-request CI does not run\nRust. The scheduled workflow provisions stable Rust and uses the compiler on\n`ubuntu-26.04`.\n\n## Files\n\n- `clone-oracle.sh`: clones `graphql-static-analysis-rs` at the pinned commit\n  into the gitignored `.oracle/` next to this file, applies `oracle.patch`,\n  and copies `dump_corpus.rs` into the checkout's `fuzz/examples/`.\n- `oracle.patch`: a small patch against the pinned commit. `SCHEMA` and\n  `variable_values` in the crate's `fuzz/src/tree_summary/operation.rs` are\n  `pub(super)` (private to the fuzz package's own targets); the patch adds\n  `pub fn schema()` and `pub fn variables_json(variable_case: u8)` accessors\n  and registers `dump_corpus` as a `[[example]]` in `fuzz/Cargo.toml`.\n- `dump_corpus.rs`: the dump program itself (see below).\n- `oracle.rs`: a Rust example that coerces generated variables, builds a\n  `CostModel`, and evaluates each case with `ExactCase` and its declared\n  default list size.\n- `Fuzz/`: the deterministic .NET generator and comparison command. It emits\n  real `AddCostAnalyzer` interceptor schemas and synthetic annotated schemas.\n- `run-nightly.sh`: generates cases, runs the live oracle, compares raw f64\n  bits, and writes a standalone fixture for the first disagreement.\n- `LICENSE-graphql-static-analysis-rs.md`: the crate's MIT license text and\n  attribution for the vendored commit.\n\n## Running the live oracle\n\n```bash\nbash src/HotChocolate/CostAnalysis/tools/oracle/run-nightly.sh \\\n    --seed 1 --cases 200\n```\n\nEvery case stores its seed and uses the same finite `DefaultListSize` on both\nimplementations. Generated operations are query-only and reject introspection\nmeta-fields, `@defer`, and `@stream` before emission. Variables are valid for\nthe generated operation and are coerced by `apollo_compiler` before the Rust\nestimator runs.\n\nReal schemas are printed from servers configured with `AddCostAnalyzer`,\ncursor and offset paging, filtering, sorting, and list-of-scalar fields. The\nprinted SDL therefore carries explicit resolver, filter, sort, paging, and\nlist-of-scalar annotations. Synthetic schemas cover signed weights,\n`@listSize`, input defaults, interfaces, unions, and directive argument\nweights. Operations cover named fragments, Boolean directives, aliases, and\nduplicate response names.\n\n`slicingArgumentDefaultValue` is a ChilliCream extension. When a generated\noperation supplies none of a field's slicing arguments, the generator adds\nthe declared default literal to the oracle copy of that operation only. It\ndoes not rewrite the schema, and it adds nothing when any slicing argument is\nalready supplied.\n\nComparison uses the hexadecimal IEEE-754 bit patterns for `typeCost` and\n`fieldCost`. A mismatch exits nonzero and writes one isolated\n`source: \"fuzz-found\"` fixture under the conformance resources. Add this\nfixture to the conformance suite to run it without Rust.\n\n## Regenerating the corpus\n\n```bash\ncd src/HotChocolate/CostAnalysis/tools/oracle\n./clone-oracle.sh\ncargo run --manifest-path .oracle/fuzz/Cargo.toml --example dump_corpus -- \\\n    ../../test/CostAnalysis.Core.Conformance.Tests/__resources__/rust-corpus\n```\n\nThis overwrites `exact-case.json` and `manifest.json` in that directory.\nThe same pinned commit produces byte-identical output.\n\n## What the dump does\n\nThe corpus contains the ExactCase IBM-cost cases from the crate's 15,840-case\nmatrix. There are 1,980 candidates before invalid-variable exclusions and\ndeduplication.\n\nFor each row:\n\n- Rows with variables that fail GraphQL coercion are excluded and counted\n  in the manifest's `excludedInvalidVariables`.\n- Duplicate `(operation, variables, defaultListSize)` rows are excluded and\n  counted in `deduplicated`. Missing variables and an empty variables object\n  are equivalent.\n- The remaining rows are costed with the crate's own `CostEstimator` in\n  `ExactCase` mode, with `default_list_size` set to the row's `list_size`\n  (0..4 for the legacy-family rows; the structural rows fix it at 2). The\n  emitted `typeCost`/`fieldCost` are the raw `f64` values `CostEstimator`\n  returns, never the crate's `cost:T,F` display format.\n- `emitted + excludedInvalidVariables + deduplicated == exactCostRows` always\n  holds (asserted by the dump itself); the manifest records all four numbers\n  plus the pinned commit.\n\nThe emitted schema excludes the crate's `@tag` definition. None of the\nemitted operations uses that directive.\n\n## Rust-free validation\n\nThe generator can build and emit cases without cloning or running the oracle:\n\n```bash\ndotnet run --project src/HotChocolate/CostAnalysis/tools/oracle/Fuzz \\\n    --framework net11.0 -- --seed 1 --cases 20 \\\n    --emit-only /tmp/fuzz-cases.json\n```\n\nReviewers without Rust installed can still validate the committed artifact\nshape:\n\n```bash\npython3 -c \"\nimport json\nd = json.load(open('../../test/CostAnalysis.Core.Conformance.Tests/__resources__/rust-corpus/exact-case.json'))\nm = json.load(open('../../test/CostAnalysis.Core.Conformance.Tests/__resources__/rust-corpus/manifest.json'))\nassert m['matrixSize'] == 15840 and m['exactCostRows'] == 1980\nassert len(d) == m['emitted'] == 1980 - m['excludedInvalidVariables'] - m['deduplicated'], m\nassert all(r['backend'] == 'exact-case' and 'directive @tag' not in r['sdl'] for r in d)\nprint('ok', len(d))\n\"\n```\n\nThis does not re-run the estimator, so it cannot catch a wrong `typeCost` or\n`fieldCost`; it only checks the corpus's shape and bookkeeping.\n\n<!-- File: .vscode/mcp.json (Tokens: ~188 | Category: mcp-config) -->\n{\n  \"servers\": {\n    \"microsoft.docs.mcp\": {\n      \"type\": \"http\",\n      \"url\": \"https://learn.microsoft.com/api/mcp\"\n    },\n    \"nuget\": {\n      \"type\": \"stdio\",\n      \"command\": \"dotnet\",\n      \"args\": [\n        \"dnx\",\n        \"NuGet.Mcp.Server\",\n        \"--source\",\n        \"https://api.nuget.org/v3/index.json\",\n        \"--yes\"\n      ]\n    },\n    \"lighthouse\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@danielsogl/lighthouse-mcp@latest\"]\n    },\n    \"playwright\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@playwright/mcp@latest\"]\n    },\n  }\n}\n\n<!-- File: src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/ReplyMailCommandTests.Reply_Should_ThreadUnderOriginalMessage_AndInheritRootSubject_When_JsonOutputIsRequested.md (Tokens: ~300 | Category: command-prompt) -->\n# Command: /replymailcommandtests.reply_should_threadunderoriginalmessage_andinheritrootsubject_when_jsonoutputisrequested\n\nPath: `src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/ReplyMailCommandTests.Reply_Should_ThreadUnderOriginalMessage_AndInheritRootSubject_When_JsonOutputIsRequested.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/ReplyMailCommandTests.Reply_Should_ThreadUnderOriginalMessage_AndInheritRootSubject_When_JsonOutputIsRequested.md)\n\n<!-- File: src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/SendMailCommandTests.Send_Should_ReturnSendResult_When_JsonOutputIsRequested.md (Tokens: ~300 | Category: command-prompt) -->\n# Command: /sendmailcommandtests.send_should_returnsendresult_when_jsonoutputisrequested\n\nPath: `src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/SendMailCommandTests.Send_Should_ReturnSendResult_When_JsonOutputIsRequested.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Mail/__snapshots__/SendMailCommandTests.Send_Should_ReturnSendResult_When_JsonOutputIsRequested.md)\n\n<!-- File: src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Tasks/__snapshots__/TaskStoreTests.ReleaseAssigneeAsync_Should_ReleaseInProgressTasksAndAppearInReady.md (Tokens: ~300 | Category: command-prompt) -->\n# Command: /taskstoretests.releaseassigneeasync_should_releaseinprogresstasksandappearinready\n\nPath: `src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Tasks/__snapshots__/TaskStoreTests.ReleaseAssigneeAsync_Should_ReleaseInProgressTasksAndAppearInReady.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/ChilliCream/graphql-platform/HEAD/src/Nitro/CommandLine/test/CommandLine.Tests/Commands/Agent/Tasks/__snapshots__/TaskStoreTests.ReleaseAssigneeAsync_Should_ReleaseInProgressTasksAndAppearInReady.md)\n</yakaai_skills>"}