Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 68 additions & 0 deletions .github/workflows/agent-skills.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
name: OSS skill downloads

on:
pull_request:
paths:
- 'skills/**'
- 'static/downloads/agent-skills/**'
- 'static/.well-known/agent-skills/**'
- 'scripts/package-agent-skills.py'
- 'scripts/refresh-agent-skill-metadata.py'
- 'scripts/check-skill-*.py'
- 'scripts/tests/test_agent_skills.py'
- 'LICENSE'
- '.github/workflows/agent-skills.yml'
workflow_dispatch:
inputs:
run_clients:
description: 'Run authenticated, read-only Claude/Codex acceptance checks on the trusted agent-skills runner'
type: boolean
default: false

permissions:
contents: read

jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
- uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
with:
node-version: 'lts/*'
- name: Check current downloads against skill source
run: |
python3 scripts/refresh-agent-skill-metadata.py --check
python3 scripts/package-agent-skills.py --check
- name: Verify helper behavior and installed manifests
run: python3 -B -m unittest discover -s scripts/tests -v
- name: Exercise installer lifecycle in temporary projects
run: python3 scripts/check-skill-install.py
- uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7
if: always()
with:
name: skill-install-evidence
path: out/skill-install-check.json

clients:
if: github.event_name == 'workflow_dispatch' && inputs.run_clients
needs: check
runs-on: [self-hosted, agent-skills]
timeout-minutes: 25
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
- uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
with:
node-version: 'lts/*'
- name: Claude Code discovery and constrained behavior
run: python3 scripts/check-skill-client.py --client claude --output out/client-claude
- name: Codex discovery and constrained behavior
if: success() || failure()
run: python3 scripts/check-skill-client.py --client codex --output out/client-codex
- uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7
if: always()
with:
name: skill-client-evidence
path: |
out/client-claude
out/client-codex
192 changes: 192 additions & 0 deletions assets/agw-docs/pages/agentgateway/ai-assistant.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,192 @@
Let your AI coding assistant set up agentgateway for you. Unlike the other getting-started guides, this guide does not route traffic through agentgateway to an AI backend. Instead, you install a skill: a packaged set of instructions that teaches your assistant, such as Claude Code or Codex, how to install, configure, and troubleshoot agentgateway for your edition and deployment mode.

After you install the skill, your assistant reads the current public documentation, inspects your actual runtime, and verifies the behavior that you request.

{{% conditional-text include-if="standalone" %}}
**Target: OSS standalone configuration.** Run agentgateway on your selected reachable host, VM, server, or container environment. A laptop is one possible target. Standalone Helm hosting also uses this configuration model. For Gateway API and controller-managed resources, use the [Kubernetes skill guide](/docs/kubernetes/latest/documentation/quickstart/ai-assistant/).
{{% /conditional-text %}}
{{% conditional-text include-if="kubernetes" %}}
**Target: OSS Kubernetes controller and Gateway API.** Work in the selected cluster through its existing Helm or GitOps owner. For host/container deployment or standalone configuration hosted with Helm, use the [standalone skill guide](/docs/standalone/latest/documentation/quickstart/ai-assistant/).
{{% /conditional-text %}}

> [!NOTE]
> These skills are a preview. Review generated changes and verify them in your environment. To set up agentgateway yourself instead, follow the other [getting-started guides]({{< link-hextra path="/documentation/quickstart/" >}}).

## Why use a skill?

The skill gives your assistant a repeatable workflow: identify the deployment, retrieve applicable documentation, make the requested change, and check the result. It separates configuration generation from a running deployment and keeps OSS and Enterprise capabilities explicit.

It has no fixed gateway release requirement or expiry date. Your assistant discovers the actual runtime and selects the corresponding documentation and schemas. A new gateway release does not require a new skill release. Public documentation and workshops provide the source material; no Solo account or internal support tools are needed. Public [Solo documentation search](https://search.solo.io/) is optional.

Installing a skill adds instructions to your assistant. Gateway changes happen when you request them, through the assistant's existing tools and permissions.

## Before you begin

Use Claude Code, Codex, or another assistant that can load a complete `SKILL.md` folder. Setup needs file/shell access to the selected environment and access to public HTTPS documentation. Choose your provider and credential source; keep secret values out of prompts.

{{% conditional-text include-if="standalone" %}}
Identify the target host or container environment, how your assistant can access it, the existing configuration owner, and the network from which clients and your browser connect. API and UI addresses must be reachable from that network. An administrative UI may use a protected hostname or an authorized tunnel; it does not need to be exposed publicly.
{{% /conditional-text %}}
{{% conditional-text include-if="kubernetes" %}}
Identify the cluster context, gateway and controller namespaces, and existing Helm/GitOps owner. Have the necessary cluster access, `kubectl`, and Helm available. Provider credentials must work inside the proxy workload; credentials on the operator's workstation are separate.
{{% /conditional-text %}}

## Install and load the skill

From your project directory, use a current Node.js LTS to install the selected skill from agentgateway.dev. Review the installer's proposed changes. The commands follow the website's current skill content; there is no skill or gateway version to bump. You can also install from [the source repository](https://github.com/agentgateway/website/tree/main/skills) when working on the skill itself.

{{< tabs >}}
{{< tab name="Claude Code" >}}
```sh
npx skills add https://agentgateway.dev --skill {{< param skillName >}} --agent claude-code
```
{{< /tab >}}
{{< tab name="Codex CLI" >}}
```sh
npx skills add https://agentgateway.dev --skill {{< param skillName >}} --agent codex
```
{{< /tab >}}
{{< tab name="Other assistants" >}}
Use your client's identifier from the [skills installer](https://github.com/vercel-labs/skills), or install the complete ZIP in its documented skill directory. A client must load relative references as well as `SKILL.md`.
{{< /tab >}}
{{< /tabs >}}

These commands install into the current project. Add `-g` only for a personal installation across projects. Codex uses `.agents/skills`, which other compatible assistants can also discover.

### ZIP alternative

Download the [current {{< param skillName >}} package]({{< param skillDownload >}}). [Checksums and content fingerprints](/downloads/agent-skills/current/manifest.json) identify the exact contents without dates or release numbers. Extract the whole folder, including `references/`, `scripts/`, and `package.json`.

{{< tabs >}}
{{< tab name="Claude Code" >}}
```sh
mkdir -p .claude/skills
unzip -n "$HOME/Downloads/{{< param skillName >}}.zip" -d .claude/skills
```
{{< /tab >}}
{{< tab name="Codex CLI" >}}
```sh
mkdir -p .agents/skills
unzip -n "$HOME/Downloads/{{< param skillName >}}.zip" -d .agents/skills
```
{{< /tab >}}
{{< tab name="Other assistants" >}}
Copy the complete `{{< param skillName >}}` directory into your client's documented project skill location. Manual extraction needs no Node.js.
{{< /tab >}}
{{< /tabs >}}

For an existing installation, use the update instructions below instead of merging files into an older folder.

### Load and check the skill

Open your assistant in the project and enter the following at its prompt:

{{< tabs >}}
{{< tab name="Claude Code" >}}
```text
/{{< param skillName >}} Identify your edition, deployment mode, content fingerprint, and documentation sources. Do not change the deployment yet.
```
{{< /tab >}}
{{< tab name="Codex CLI" >}}
```text
${{< param skillName >}} Identify your edition, deployment mode, content fingerprint, and documentation sources. Do not change the deployment yet.
```
{{< /tab >}}
{{< tab name="Other assistants" >}}
Select `{{< param skillName >}}` through your client's skill mechanism and ask it to identify the same information.
{{< /tab >}}
{{< /tabs >}}

If discovery fails, check that the skill directory directly contains `SKILL.md` and start a new session in that project.

## Set up your first provider

Choose the provider you use. The assistant should resolve missing target/provider inputs, preserve existing configuration, run one bounded request, and return the verified API endpoint and protected UI access path. A test request can incur normal provider charges.

**OpenAI**

```text
Set up agentgateway in my selected deployment environment for OpenAI.
Use my chosen model and existing provider secret source; ask for either if missing.
Preserve the configuration owner. Verify a request through the gateway and show
me the reachable API endpoint, protected UI access path, and rollback commands.
```

**Gemini through Vertex AI**

```text
Connect Gemini through Google Cloud Vertex AI in my selected deployment environment.
Confirm the Google Cloud project, region/location, model, and workload identity or ADC.
Use Vertex AI authentication, rather than a Gemini Developer API key.
Verify a request from the actual gateway workload and show API and UI access details.
```

**Amazon Bedrock**

```text
Connect my Bedrock models in the selected deployment environment.
Confirm AWS region, model or inference-profile IDs, and the gateway's IAM identity.
Verify a request through the gateway and return the reachable API endpoint,
protected UI access path, and stop or rollback commands for these changes.
```

For preparation only, begin with “Prepare the files without deploying or starting anything.” If access or credentials are missing, the assistant should finish independent preparation and identify the checks it could not perform.

## Check versions and behavior

Ask the assistant to inspect the actual gateway version before validating configuration. In controller mode it also checks the deployed controller, proxy images, and CRDs. The skill has no maintained release allowlist. It uses the discovered runtime to choose documentation and validation methods, preserving your existing deployment version.

The optional bundled helpers need Python 3.10+. They inspect package integrity/runtime evidence, classify captured MCP tool responses, and check controlled masking examples. Results distinguish a passed check, failure, and an inconclusive result. Neither a version observation nor valid YAML proves a working deployment.

## Continue with your own tasks

**Independent identities and budgets**

```text
Give five agents separate identities and a $10 budget each per fixed 24-hour window.
Check what my edition and deployment mode can enforce. Verify independent accounting,
model prices, persistence, and a bounded enforcement test. Keep credentials out of chat.
If the requested dollar enforcement is unavailable, explain the gap before choosing an alternative.
```

Standalone and controller cost-control surfaces can differ. A token quota is not an exact dollar allowance, and post-response charging/concurrent requests can overshoot a threshold. Consult the current budget documentation for your deployment before relying on enforcement.

**JWT identity and MCP code mode**

```text
I want budgets tied to authenticated JWT identities and MCP code mode.
Check native OSS support for each requirement in this deployment. Distinguish
claim-keyed token limits from dollar enforcement. Keep implementation OSS and
explain any relevant Enterprise capability with a public source.
```

A relevant Enterprise availability note is informational. It does not change editions or install licensed components. The skill checks capabilities separately rather than treating all JWT or MCP features as Enterprise-only.

**Troubleshooting**

```text
Requests through my gateway fail. Inspect the actual runtime and configuration,
identify the failed layer, make the smallest authorized correction, and verify it.
Preserve unrelated settings and report any remaining unrun checks.
```

## Update, remove, or share

For repository installations, inspect installed packages and update the selected skill:

```sh
npx skills list --json
npx skills update {{< param skillName >}} --project
```

Back up local customizations outside skill directories first: updates can replace them. Start a new assistant session afterward. Use `--global` instead of `--project` for an intentional personal installation.

For manual ZIP installations, download the current ZIP and replace the complete folder after backing it up. Keep its content fingerprint with any bug report. Sharing that ZIP gives another person the same reviewed instructions without requiring a repository commit.

```sh
npx skills remove {{< param skillName >}}
```

This removes the selected skill across project clients. Client-specific removal can leave `.agents/skills` present because several clients share it. Removing a skill does not stop a gateway or remove its configuration, credentials, resources, or accounting data.

For feedback, [open a website issue](https://github.com/agentgateway/website/issues/new) with the content fingerprint, assistant/runtime information, deployment mode, sanitized request, and observed result. Keep credentials and customer data out of the report.
4 changes: 4 additions & 0 deletions assets/agw-docs/snippets/ai-assistant-quickstart.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{{% upstream %}}
> [!TIP]
> Want your AI coding assistant to set up agentgateway for you? Install the [skill for AI assistants]({{< link-hextra path="/documentation/quickstart/ai-assistant/" >}}), which teaches Claude Code, Codex, and other assistants how to install, configure, and verify agentgateway.
{{% /upstream %}}
3 changes: 3 additions & 0 deletions content/docs/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,9 @@ test: skip
disableCards: true
---

> [!TIP]
> Want an AI coding assistant to set up agentgateway? <a href="/docs/standalone/latest/documentation/quickstart/ai-assistant/">Install the standalone skill</a> for standalone configuration, including a standalone process hosted in Kubernetes, or <a href="/docs/kubernetes/latest/documentation/quickstart/ai-assistant/">the Kubernetes skill</a> for the controller and Gateway API. Agents can discover both skills at <a href="https://agentgateway.dev/.well-known/agent-skills/index.json">the skill index</a>.

Agentgateway can be deployed in two ways. Choose your deployment type to view the relevant documentation.

<div class="toggle-dark">
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ description: Install and run agentgateway, or route traffic to MCP, LLM, or HTTP
Get started with agentgateway on Kubernetes. Install the control plane, or jump to a quick start that routes traffic to the backend you need.


{{< reuse "agw-docs/snippets/ai-assistant-quickstart.md" >}}

## Before you begin

These guides assume you have a Kubernetes cluster, `kubectl`, and `helm`. For quick testing, you can use [Kind](https://kind.sigs.k8s.io/).
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
title: Skill for AI assistants
linkTitle: Skill for AI assistants
weight: 5
description: Install a skill that teaches your AI coding assistant, such as Claude Code or Codex, to set up, configure, and verify the agentgateway Kubernetes controller and Gateway API for you.
skillName: agentgateway-oss-kubernetes
skillDownload: /downloads/agent-skills/current/agentgateway-oss-kubernetes.zip
---

{{< reuse "agw-docs/pages/agentgateway/ai-assistant.md" >}}
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,6 @@ weight: 10
description: Install the agentgateway control plane in your Kubernetes cluster.
---

{{< reuse "agw-docs/snippets/ai-assistant-quickstart.md" >}}

{{< reuse "agw-docs/pages/agentgateway/quickstart/install.md" >}}
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ description: Install and run agentgateway, or route traffic to MCP, LLM, or HTTP
Get started with agentgateway on Kubernetes. Install the control plane, or jump to a quick start that routes traffic to the backend you need.


{{< reuse "agw-docs/snippets/ai-assistant-quickstart.md" >}}

## Before you begin

These guides assume you have a Kubernetes cluster, `kubectl`, and `helm`. For quick testing, you can use [Kind](https://kind.sigs.k8s.io/).
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
title: Skill for AI assistants
linkTitle: Skill for AI assistants
weight: 5
description: Install a skill that teaches your AI coding assistant, such as Claude Code or Codex, to set up, configure, and verify the agentgateway Kubernetes controller and Gateway API for you.
skillName: agentgateway-oss-kubernetes
skillDownload: /downloads/agent-skills/current/agentgateway-oss-kubernetes.zip
---

{{< reuse "agw-docs/pages/agentgateway/ai-assistant.md" >}}
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,6 @@ weight: 10
description: Install the agentgateway control plane in your Kubernetes cluster.
---

{{< reuse "agw-docs/snippets/ai-assistant-quickstart.md" >}}

{{< reuse "agw-docs/pages/agentgateway/quickstart/install.md" >}}
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,5 @@ description: Get started with the agentgateway binary.
---

{{< reuse "agw-docs/standalone/quickstart/get-started.md" >}}

{{< reuse "agw-docs/snippets/ai-assistant-quickstart.md" >}}
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
title: Skill for AI assistants
linkTitle: Skill for AI assistants
weight: 5
description: Install a skill that teaches your AI coding assistant, such as Claude Code or Codex, to set up, configure, and verify standalone agentgateway for you.
skillName: agentgateway-oss-standalone
skillDownload: /downloads/agent-skills/current/agentgateway-oss-standalone.zip
---

{{< reuse "agw-docs/pages/agentgateway/ai-assistant.md" >}}
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,6 @@ weight: 10
description: Install agentgateway as a binary, a Docker container, or a Kubernetes Deployment with Helm.
---

{{< reuse "agw-docs/snippets/ai-assistant-quickstart.md" >}}

{{< reuse "agw-docs/standalone/setup/install-overview.md" >}}
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,6 @@ aliases:
- ../../../deployment/binary/
---

{{< reuse "agw-docs/snippets/ai-assistant-quickstart.md" >}}

{{< reuse "agw-docs/standalone/setup/binary.md" >}}
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,6 @@ aliases:
- ../../../integrations/platforms/docker/
---

{{< reuse "agw-docs/snippets/ai-assistant-quickstart.md" >}}

{{< reuse "agw-docs/standalone/setup/docker.md" >}}
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,6 @@ aliases:
- ../../../deployment/helm/install/
---

{{< reuse "agw-docs/snippets/ai-assistant-quickstart.md" >}}

{{< reuse "agw-docs/standalone/setup/helm.md" >}}
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,5 @@ description: Get started with the agentgateway binary.
---

{{< reuse "agw-docs/standalone/quickstart/get-started.md" >}}

{{< reuse "agw-docs/snippets/ai-assistant-quickstart.md" >}}
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
title: Skill for AI assistants
linkTitle: Skill for AI assistants
weight: 5
description: Install a skill that teaches your AI coding assistant, such as Claude Code or Codex, to set up, configure, and verify standalone agentgateway for you.
skillName: agentgateway-oss-standalone
skillDownload: /downloads/agent-skills/current/agentgateway-oss-standalone.zip
---

{{< reuse "agw-docs/pages/agentgateway/ai-assistant.md" >}}
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,6 @@ weight: 10
description: Install agentgateway as a binary, a Docker container, or a Kubernetes Deployment with Helm.
---

{{< reuse "agw-docs/snippets/ai-assistant-quickstart.md" >}}

{{< reuse "agw-docs/standalone/setup/install-overview.md" >}}
Loading