From 19055100a8afa4c903813862830454d83f530038 Mon Sep 17 00:00:00 2001 From: Saif Shines Date: Tue, 5 May 2026 21:20:28 +0530 Subject: [PATCH 1/5] docs: reorganize agent-auth around canonical docs Shift the agent-auth plugin toward a Tessl-like docs/skills/rules layout so durable AgentKit guidance is separated from Claude-specific runtime files. This makes live metadata the documented source of truth for tools while keeping existing connector notes available as secondary references. Co-authored-by: Cursor --- plugins/agent-auth/.claude-plugin/plugin.json | 6 +- plugins/agent-auth/.env.example | 5 + plugins/agent-auth/README.md | 90 +++++ plugins/agent-auth/commands/test-tool.md | 91 +++++ plugins/agent-auth/docs/byoc.md | 44 +++ plugins/agent-auth/docs/code-samples.md | 47 +++ plugins/agent-auth/docs/connected-accounts.md | 51 +++ plugins/agent-auth/docs/connections.md | 53 +++ plugins/agent-auth/docs/connectors/README.md | 51 +++ plugins/agent-auth/docs/index.md | 38 +++ plugins/agent-auth/docs/tool-discovery.md | 68 ++++ .../references/agent-connectors/README.md | 17 +- plugins/agent-auth/references/byoc.md | 8 +- plugins/agent-auth/references/code-samples.md | 6 +- .../references/connected-accounts.md | 6 +- plugins/agent-auth/references/connections.md | 16 +- plugins/agent-auth/references/providers.md | 50 +-- .../agent-auth/references/tool-discovery.md | 88 +++++ .../agent-auth/rules/live-metadata-first.md | 19 ++ plugins/agent-auth/rules/terminology.md | 18 + plugins/agent-auth/rules/tool-selection.md | 22 ++ plugins/agent-auth/skills/agent-auth/SKILL.md | 322 ++++-------------- .../skills/building-agent-mcp-server/SKILL.md | 17 +- .../discovering-agentkit-tools/SKILL.md | 56 +++ .../production-readiness-scalekit/SKILL.md | 11 +- .../skills/testing-agentkit-tools/SKILL.md | 50 +++ .../testing-agentkit-tools/scripts/connect.py | 250 ++++++++++++++ 27 files changed, 1197 insertions(+), 303 deletions(-) create mode 100644 plugins/agent-auth/.env.example create mode 100644 plugins/agent-auth/README.md create mode 100644 plugins/agent-auth/commands/test-tool.md create mode 100644 plugins/agent-auth/docs/byoc.md create mode 100644 plugins/agent-auth/docs/code-samples.md create mode 100644 plugins/agent-auth/docs/connected-accounts.md create mode 100644 plugins/agent-auth/docs/connections.md create mode 100644 plugins/agent-auth/docs/connectors/README.md create mode 100644 plugins/agent-auth/docs/index.md create mode 100644 plugins/agent-auth/docs/tool-discovery.md create mode 100644 plugins/agent-auth/references/tool-discovery.md create mode 100644 plugins/agent-auth/rules/live-metadata-first.md create mode 100644 plugins/agent-auth/rules/terminology.md create mode 100644 plugins/agent-auth/rules/tool-selection.md create mode 100644 plugins/agent-auth/skills/discovering-agentkit-tools/SKILL.md create mode 100644 plugins/agent-auth/skills/testing-agentkit-tools/SKILL.md create mode 100644 plugins/agent-auth/skills/testing-agentkit-tools/scripts/connect.py diff --git a/plugins/agent-auth/.claude-plugin/plugin.json b/plugins/agent-auth/.claude-plugin/plugin.json index 195d3f3..9475a92 100644 --- a/plugins/agent-auth/.claude-plugin/plugin.json +++ b/plugins/agent-auth/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agent-auth", - "description": "Implements Scalekit Agent Auth so AI agents can act in third-party apps (Gmail, Slack, Calendar, Notion) on behalf of users.", - "version": "1.8.2", + "description": "Sets up Scalekit AgentKit in Claude Code so agents can authorize users, discover tools, and execute authenticated tool calls across connectors.", + "version": "1.9.0", "author": { "name": "Scalekit", "email": "hi@scalekit.com" @@ -9,5 +9,5 @@ "homepage": "https://docs.scalekit.com/dev-kit/build-with-ai/agent-auth/", "repository": "https://github.com/scalekit-inc/claude-code-authstack", "license": "MIT", - "keywords": ["scalekit", "agent-auth", "oauth", "connected-accounts"] + "keywords": ["scalekit", "agentkit", "agent-auth", "connectors", "tools", "connected-accounts"] } diff --git a/plugins/agent-auth/.env.example b/plugins/agent-auth/.env.example new file mode 100644 index 0000000..437d1db --- /dev/null +++ b/plugins/agent-auth/.env.example @@ -0,0 +1,5 @@ +SCALEKIT_ENV_URL=https://your-env.scalekit.dev +SCALEKIT_CLIENT_ID=skc_your_client_id +SCALEKIT_CLIENT_SECRET=your_client_secret +# Optional sample connection name copied exactly from AgentKit -> Connections +GMAIL_CONNECTION_NAME=MY_GMAIL diff --git a/plugins/agent-auth/README.md b/plugins/agent-auth/README.md new file mode 100644 index 0000000..1208999 --- /dev/null +++ b/plugins/agent-auth/README.md @@ -0,0 +1,90 @@ +# AgentKit for Claude Code + +## Purpose +This plugin brings Scalekit AgentKit into Claude Code so an agent can connect users to third-party apps, discover the right tools, and execute authenticated tool calls on their behalf. It is organized as a hybrid structure: a Tessl-like canonical content layer and a Claude-specific adapter layer. + +Canonical content lives in: +- `docs/` for durable AgentKit knowledge +- `skills/` for task-oriented workflows +- `rules/` for cross-cutting guidance + +Claude runtime files remain in place as adapters: +- `.claude-plugin/` +- `.mcp.json` +- `commands/` +- `hooks/` +- `agents/` + +The plugin treats live AgentKit metadata as the source of truth for tool names, `input_schema`, and `output_schema`. Connector notes are curated guidance, not a guaranteed exhaustive catalog. + +## Installation +```sh +claude /plugin install agent-auth@scalekit-auth-stack +``` + +Start with the canonical docs entrypoint at [`docs/index.md`](docs/index.md). + +## Skills Reference +- `/agent-auth:integrating-agent-auth` + Integrates AgentKit into app code or an agent workflow and routes into the core docs. +- `/agent-auth:discovering-agentkit-tools` + Uses live AgentKit metadata to find tools, inspect schemas, and narrow the tool set. +- `/agent-auth:testing-agentkit-tools` + Generates authorization links, fetches live tool metadata, and executes tools from Claude Code. +- `/agent-auth:building-agent-mcp-server` + Exposes AgentKit tools through MCP for MCP-compatible runtimes. +- `/agent-auth:production-readiness-scalekit` + Runs a structured production-readiness checklist for AgentKit integrations. + +Command: +- `/test-tool [generate-link|get-tool|execute-tool ...]` + Runs the live AgentKit playground command. + +## Configuration +Required environment variables: +- `SCALEKIT_ENV_URL` +- `SCALEKIT_CLIENT_ID` +- `SCALEKIT_CLIENT_SECRET` + +Optional sample variable: +- `GMAIL_CONNECTION_NAME` + +Legacy aliases supported by the testing command: +- `TOOL_ENV_URL` +- `TOOL_CLIENT_ID` +- `TOOL_CLIENT_SECRET` + +Example `.mcp.json`: + +```json +{ + "mcpServers": { + "scalekit": { + "type": "http", + "url": "https://mcp.scalekit.com" + } + } +} +``` + +## Usage Examples +Typical flow for a new connector integration: +1. Read [`docs/index.md`](docs/index.md) for the canonical model and [`docs/connections.md`](docs/connections.md) for connection naming. +2. Create the connection in `AgentKit -> Connections`. +3. Use `/agent-auth:integrating-agent-auth` to scaffold connected-account creation and authorization. +4. Use `/agent-auth:discovering-agentkit-tools` or `/test-tool get-tool --provider GMAIL` to inspect the live tool catalog and schema. +5. Use `/test-tool generate-link --connection-name --identifier user_123` if the user still needs to authorize. +6. Use `/test-tool execute-tool --tool-name gmail_fetch_mails --connection-name --identifier user_123 --tool-input '{"query":"is:unread","max_results":5}'` to validate the payload before wiring it into application code. + +## Troubleshooting +1. No tools show up for a connector: + Use live discovery first. The current tool inventory comes from AgentKit metadata, not static connector notes. +2. The connection exists but auth or execution fails: + Verify that `connection_name` matches the exact dashboard value. It is not always the connector slug such as `gmail`. +3. Tool execution fails after a user already connected: + Re-check the connected account status and re-authorize if the account is not `ACTIVE`. + +## Security +This plugin needs AgentKit API credentials for your Scalekit environment. Store them in environment variables or a local secret manager, and never commit them to source control. + +Connected accounts are per-user authorization boundaries. Use the correct identifier, request minimum necessary scopes, and keep the tool set constrained before handing tools to an LLM. diff --git a/plugins/agent-auth/commands/test-tool.md b/plugins/agent-auth/commands/test-tool.md new file mode 100644 index 0000000..638bc06 --- /dev/null +++ b/plugins/agent-auth/commands/test-tool.md @@ -0,0 +1,91 @@ +--- +description: Test live AgentKit discovery and tool execution from Claude Code +argument-hint: "[generate-link|get-tool|execute-tool] [args...]" +allowed-tools: Bash +--- + +# AgentKit Tool Tester + +Test live AgentKit flows using the bundled Python playground script. + +**Arguments:** $ARGUMENTS + +## Operations + +### generate-link +Usage: `generate-link --connection-name --identifier ` + +Creates or fetches the connected account and prints an authorization link if the account is not yet `ACTIVE`. + +### get-tool +Usage: `get-tool [--tool-name ] [--provider ] [--page-size ] [--page-token ]` + +Fetches live tool metadata and prints the raw JSON response. Omitting `--tool-name` returns all matching tools for the filter. + +### execute-tool +Usage: `execute-tool --tool-name --connection-name --identifier --tool-input ''` + +Creates or fetches the connected account, prints an authorization link if needed, and executes the tool. + +## Your task + +Parse `$ARGUMENTS` to determine the operation, then run the bundled script from the plugin root: + +```bash +skills/testing-agentkit-tools/scripts/connect.py +``` + +### Runner selection + +Check which runner is available by running `which uv` once before any Python command: + +- if `uv` exists, use `uv run python` +- otherwise use `python3` +- if `python3` is unavailable, fall back to `python` + +### Credentials + +Before running any operation, check for these environment variables: + +- `SCALEKIT_ENV_URL` +- `SCALEKIT_CLIENT_ID` +- `SCALEKIT_CLIENT_SECRET` + +Also accept legacy aliases: + +- `TOOL_ENV_URL` +- `TOOL_CLIENT_ID` +- `TOOL_CLIENT_SECRET` + +If none of the supported variables are available, ask the user for the missing values before proceeding. Do not write secrets into source-controlled files unless the user explicitly asks you to. + +### Commands to run + +If operation is `generate-link`, run: + +```bash + skills/testing-agentkit-tools/scripts/connect.py --generate-link --connection-name --identifier +``` + +If operation is `get-tool`, run: + +```bash + skills/testing-agentkit-tools/scripts/connect.py --get-tool [--tool-name ] [--provider ] [--page-size ] [--page-token ] +``` + +If operation is `execute-tool`, run: + +```bash + skills/testing-agentkit-tools/scripts/connect.py --execute-tool --tool-name --connection-name --identifier --tool-input '' +``` + +If `tool_input` is missing for `execute-tool`, inspect the live tool metadata first or ask the user for the missing input values. + +### After running + +Show: + +1. the command output +2. the exact command that was run +3. the resolved parameters in a small structured summary +4. for `execute-tool`, the exact JSON payload that was passed to AgentKit diff --git a/plugins/agent-auth/docs/byoc.md b/plugins/agent-auth/docs/byoc.md new file mode 100644 index 0000000..1ff5319 --- /dev/null +++ b/plugins/agent-auth/docs/byoc.md @@ -0,0 +1,44 @@ +# Bring Your Own Credentials + +Bring Your Own Credentials (BYOC) lets you use your own OAuth applications and credentials instead of shared Scalekit defaults. + +## Why teams use BYOC + +Common reasons: + +- your branding appears during consent flows +- you want your own quotas and provider relationship +- you need stricter compliance or audit ownership +- you want a more fully whitelabeled production experience + +## What changes + +With BYOC: + +- the connection is still managed in AgentKit +- connected accounts still authorize users in the same model +- tools are still discovered and executed through AgentKit + +Only the credentials and upstream app ownership change. + +## Operational impact + +Moving to BYOC can require users to re-authorize, because the underlying OAuth application has changed. + +Plan for: + +- re-authentication +- updated consent screens +- different quotas or limits +- provider-specific app verification steps + +## Where it fits in the plugin + +BYOC is a connection-level concern, not a tool-discovery concern. + +Set up the connection correctly first, then discover tools and test execution as usual. + +## Related docs + +- [connections.md](connections.md) +- [connected-accounts.md](connected-accounts.md) diff --git a/plugins/agent-auth/docs/code-samples.md b/plugins/agent-auth/docs/code-samples.md new file mode 100644 index 0000000..b71f29d --- /dev/null +++ b/plugins/agent-auth/docs/code-samples.md @@ -0,0 +1,47 @@ +# Code Samples + +This page is the canonical code-sample entrypoint for the plugin. + +Use it to choose an implementation style before opening a larger sample repository. + +## Common paths + +| Goal | Recommended path | +|---|---| +| Validate one tool quickly | Use `/test-tool` with `testing-agentkit-tools` | +| Integrate AgentKit into app code | Use `integrating-agent-auth` | +| Build an agent with a framework | Use framework-specific examples below | +| Expose tools over MCP | Use `building-agent-mcp-server` | + +## Framework directions + +- LangChain: fetch a narrow tool set and hand only the relevant tools to the agent +- Google ADK: use AgentKit-authenticated tool wrappers for Gemini-based agents +- Direct SDK usage: best for deterministic or single-tool flows +- MCP: best when you want tools exposed to MCP-compatible runtimes + +## Important rule + +Do not treat example code as a fixed tool catalog. + +Examples show patterns, not the current truth of: + +- which tools exist +- what their schemas look like +- which fields are required today + +Use [tool-discovery.md](tool-discovery.md) first when the exact tool surface matters. + +## Suggested sample flow + +1. Set up a connection. +2. Create or fetch the connected account. +3. Discover the exact tool and schema. +4. Test it with the live playground. +5. Move the validated payload into application or agent code. + +## Related docs + +- [tool-discovery.md](tool-discovery.md) +- [connections.md](connections.md) +- [connected-accounts.md](connected-accounts.md) diff --git a/plugins/agent-auth/docs/connected-accounts.md b/plugins/agent-auth/docs/connected-accounts.md new file mode 100644 index 0000000..9a36988 --- /dev/null +++ b/plugins/agent-auth/docs/connected-accounts.md @@ -0,0 +1,51 @@ +# Connected Accounts + +Connected accounts are the per-user authorization records in AgentKit. + +If a connection is the reusable environment configuration, a connected account is the user-specific runtime object that lets the agent act on behalf of a particular user or identifier. + +## What a connected account stores + +A connected account tracks: + +- the linked connection +- the user or tenant identifier +- current authorization status +- granted scopes and token state + +## Lifecycle + +Typical lifecycle: + +1. Create or fetch the connected account for a user. +2. If the account is not `ACTIVE`, generate an authorization link. +3. The user completes the auth flow. +4. The account becomes `ACTIVE`. +5. AgentKit can execute tools on behalf of that user. + +## Operational rules + +- Always use the correct user identifier from your own system. +- Treat the connected account as the per-user boundary for tool execution. +- If tool execution fails unexpectedly, check the connected account status again before debugging deeper. + +## Why this matters for tool execution + +The tool catalog is connector-level, but execution is user-scoped through a connected account. + +That means: + +- tool discovery tells you what is possible +- the connected account determines whether the current user is actually authorized to do it + +## Common failure modes + +- `connection_name` does not match the dashboard value +- user never completed authorization +- account is no longer `ACTIVE` +- scopes are too narrow for the requested tool + +## Related docs + +- [connections.md](connections.md) +- [tool-discovery.md](tool-discovery.md) diff --git a/plugins/agent-auth/docs/connections.md b/plugins/agent-auth/docs/connections.md new file mode 100644 index 0000000..4e7bc17 --- /dev/null +++ b/plugins/agent-auth/docs/connections.md @@ -0,0 +1,53 @@ +# Connections + +Connections are the environment-level AgentKit configurations that tell Scalekit how to authenticate to a connector. + +One connection is created once in the dashboard, then reused across many users through connected accounts. + +## Core idea + +A connection defines: + +- which connector is being used +- which credentials or auth settings back it +- which scopes or permissions are requested +- the exact dashboard `connection_name` used later in SDK calls + +## Important distinction + +Do not confuse: + +- `connection_name`: the exact dashboard value used for authorization and connected-account flows +- connector slug or provider filter: the identifier used to group tools in live metadata + +They are related, but they are not always the same string. + +## Typical setup flow + +1. Go to `AgentKit -> Connections` in the Scalekit Dashboard. +2. Choose the connector you want to expose to the agent. +3. Configure credentials, scopes, and any connector-specific settings. +4. Save the connection with a stable `connection_name`. +5. Reuse that `connection_name` in your SDK code and testing commands. + +## Connection types + +Common patterns include: + +- OAuth 2.0 connectors +- API key connectors +- other connector-specific auth models supported by AgentKit + +Use the connector-specific notes in [connectors/README.md](connectors/README.md) for quirks, but treat live tool metadata as the source of truth for available tools. + +## Practical guidance + +- Use clear environment-specific names such as `MY_GMAIL` or `SALESFORCE_PROD`. +- Keep scopes minimal and workflow-specific. +- Do not assume Gmail is representative of every connector; Gmail is a special-case quickstart in several examples. + +## Related docs + +- [connected-accounts.md](connected-accounts.md) +- [tool-discovery.md](tool-discovery.md) +- [byoc.md](byoc.md) diff --git a/plugins/agent-auth/docs/connectors/README.md b/plugins/agent-auth/docs/connectors/README.md new file mode 100644 index 0000000..2b30396 --- /dev/null +++ b/plugins/agent-auth/docs/connectors/README.md @@ -0,0 +1,51 @@ +# Connector Notes + +This directory is the canonical connector-notes entrypoint for the plugin. + +Connector notes are intentionally curated and lightweight. They should explain: + +- what the connector is useful for +- auth quirks or setup gotchas +- example workflows +- guidance that is not obvious from live metadata + +They should not claim to be the exhaustive current tool catalog. + +## Source of truth + +Use live AgentKit metadata for: + +- tool names +- `input_schema` +- `output_schema` +- current connector coverage + +Use connector notes for: + +- workflow hints +- product context +- authentication caveats +- examples that help users orient quickly + +## Current connector coverage in the plugin + +The plugin already contains curated notes for connectors such as: + +- Gmail +- Google Calendar +- Google Sheets +- Slack +- Salesforce +- GitHub +- Notion +- Zendesk + +and many others in the legacy connector-notes set. + +During this hybrid migration, those existing notes remain available in the plugin as the backing source for connector-specific guidance while `docs/` becomes the canonical entry layer. + +## Related docs + +- [../tool-discovery.md](../tool-discovery.md) +- [../connections.md](../connections.md) +- [../connected-accounts.md](../connected-accounts.md) diff --git a/plugins/agent-auth/docs/index.md b/plugins/agent-auth/docs/index.md new file mode 100644 index 0000000..bd1d633 --- /dev/null +++ b/plugins/agent-auth/docs/index.md @@ -0,0 +1,38 @@ +# AgentKit Docs + +This `docs/` directory is the canonical documentation layer for the `agent-auth` plugin. + +Use it for the durable AgentKit model: + +- connectors +- connections +- connected accounts +- tools +- live tool discovery + +The Claude Code plugin still includes adapter/runtime files such as `.claude-plugin/`, `.mcp.json`, `commands/`, `hooks/`, and `agents/`, but those are secondary to the content model here. + +## How this directory is organized + +- [connections.md](connections.md) explains how AgentKit connections are configured and named. +- [connected-accounts.md](connected-accounts.md) explains the per-user authorization lifecycle. +- [tool-discovery.md](tool-discovery.md) explains how to treat live AgentKit metadata as the source of truth for tools and schemas. +- [byoc.md](byoc.md) explains Bring Your Own Credentials. +- [code-samples.md](code-samples.md) points to implementation patterns and runnable examples. +- [connectors/README.md](connectors/README.md) is the curated connector-notes entrypoint. + +## Source-of-truth rule + +Use live AgentKit metadata as the source of truth for: + +- current connector coverage +- tool names +- `input_schema` +- `output_schema` + +Treat connector notes as curated guidance, not as a guaranteed exhaustive catalog. + +## Relationship to skills and rules + +- `skills/` contains task-oriented workflows that should stay thin and point here for deeper reference. +- `rules/` contains stable cross-cutting guidance such as terminology and tool-selection discipline. diff --git a/plugins/agent-auth/docs/tool-discovery.md b/plugins/agent-auth/docs/tool-discovery.md new file mode 100644 index 0000000..cf35130 --- /dev/null +++ b/plugins/agent-auth/docs/tool-discovery.md @@ -0,0 +1,68 @@ +# Tool Discovery + +Live AgentKit metadata is the source of truth for: + +- current connector coverage +- tool names +- `input_schema` +- `output_schema` + +This is the most important rule in the hybrid structure. + +## What belongs in docs vs live metadata + +Use `docs/` for: + +- stable terminology +- auth and setup guidance +- connector quirks +- example workflows + +Use live metadata for: + +- current tools for a connector +- required input fields +- optional input fields +- output shape + +## Discovery workflow + +1. Start from a connector or exact tool name. +2. Query live AgentKit metadata. +3. Inspect: + - tool name + - description + - connector or provider grouping + - `input_schema.required` + - `input_schema.properties` + - `output_schema.properties` +4. Narrow the tool set to the few tools needed for the workflow. +5. Only execute after the schema is clear and the user has an `ACTIVE` connected account. + +## Important distinction + +Do not confuse: + +- dashboard `connection_name` +- connector or provider slug used for discovery filters + +The first is used for authorization and connected-account operations. +The second is used for catalog discovery. + +## Claude Code workflow + +Use: + +- `discovering-agentkit-tools` when the user needs current tools or schemas +- `testing-agentkit-tools` when the user wants to run a live tool and inspect the exact payload +- `/test-tool get-tool ...` for the runnable playground flow + +## Fallback rule + +If live credentials are unavailable, connector notes are still useful as a directional guide, but they must be treated as non-exhaustive. + +## Related docs + +- [connections.md](connections.md) +- [connected-accounts.md](connected-accounts.md) +- [connectors/README.md](connectors/README.md) diff --git a/plugins/agent-auth/references/agent-connectors/README.md b/plugins/agent-auth/references/agent-connectors/README.md index 807653a..a1d5853 100644 --- a/plugins/agent-auth/references/agent-connectors/README.md +++ b/plugins/agent-auth/references/agent-connectors/README.md @@ -1,6 +1,10 @@ # Agent Connectors Reference -This directory contains documentation for all supported agent connectors in the Scalekit Agent Auth platform. +> Canonical entrypoint: [../../docs/connectors/README.md](../../docs/connectors/README.md) + +This directory contains curated notes for AgentKit connectors in Scalekit. + +Use these files for connector-specific guidance, auth quirks, and example workflows. Do not treat them as the exhaustive source of truth for current tools or schemas; use live AgentKit tool metadata for that. ## Available Connectors @@ -51,17 +55,20 @@ This directory contains documentation for all supported agent connectors in the ## Getting Started -Each connector documentation includes: +Each connector document can include: - Service description and capabilities - Authentication requirements -- Complete API reference for all available tools -- Parameter specifications and examples +- Product and workflow context +- Authentication requirements +- Example tool patterns and usage notes - Usage guidelines and best practices +For the live tool catalog and current `input_schema` / `output_schema`, use [../tool-discovery.md](../tool-discovery.md). + ## Authentication -Connectors support OAuth 2.0, API Key, or Basic Auth authentication through the Agent Auth platform. You'll need to: +Connectors support OAuth 2.0, API Key, or Basic Auth authentication through AgentKit. You'll need to: 1. Create a connection for the desired service 2. Configure OAuth credentials in your connection diff --git a/plugins/agent-auth/references/byoc.md b/plugins/agent-auth/references/byoc.md index b88d0f6..5c43412 100644 --- a/plugins/agent-auth/references/byoc.md +++ b/plugins/agent-auth/references/byoc.md @@ -1,6 +1,8 @@ # Bring Your Own Credentials -Bring Your Own Credentials (BYOC) allows you to use your own OAuth applications and authentication credentials with Agent Auth instead of Scalekit's shared credentials. This provides complete control over the authentication experience and enables full whitelabeling of your application. +> Canonical doc: [../docs/byoc.md](../docs/byoc.md) + +Bring Your Own Credentials (BYOC) allows you to use your own OAuth applications and authentication credentials with AgentKit instead of Scalekit's shared credentials. This provides complete control over the authentication experience and enables full whitelabeling of your application. ## Why bring your own credentials? @@ -33,7 +35,7 @@ With BYOC, authentication flows work as follows: 1. **Scalekit** handles the initial authentication request with your OAuth client-id details 2. **Provider** authenticates the user and returns tokens to Scalekit -3. **Agent Auth** uses your tokens to execute tools on behalf of users +3. **AgentKit** uses your tokens to execute tools on behalf of users ## Setting up BYOC @@ -53,4 +55,4 @@ If you're currently using Scalekit's shared credentials and want to migrate to B > - Rate limits and quotas will change to your application's limits > - Some users may need to re-grant permissions -By implementing BYOC, you gain complete control over your users' authentication experience while maintaining the power and flexibility of Agent Auth's unified API for tool execution. +By implementing BYOC, you gain complete control over your users' authentication experience while maintaining the power and flexibility of AgentKit's unified API for tool execution. diff --git a/plugins/agent-auth/references/code-samples.md b/plugins/agent-auth/references/code-samples.md index 537ca57..19731d9 100644 --- a/plugins/agent-auth/references/code-samples.md +++ b/plugins/agent-auth/references/code-samples.md @@ -1,6 +1,8 @@ # Code Samples -This reference provides implementation examples for integrating Scalekit Agent Auth across different frameworks, languages, and use cases. +> Canonical doc: [../docs/code-samples.md](../docs/code-samples.md) + +This reference provides implementation examples for integrating Scalekit AgentKit across different frameworks, languages, and use cases. ## Quick Start Guide @@ -129,7 +131,7 @@ response = agent_executor.invoke({ ### Repository: [scalekit-inc/google-adk-agent-example](https://github.com/scalekit-inc/google-adk-agent-example.git) -**Overview:** Minimal Gmail-powered agent demonstrating Agent Auth integration with Google's Agent Development Kit. Entire integration fits in one file. +**Overview:** Minimal Gmail-powered agent demonstrating AgentKit integration with Google's Agent Development Kit. Entire integration fits in one file. **Requirements:** - Python >= 3.11 diff --git a/plugins/agent-auth/references/connected-accounts.md b/plugins/agent-auth/references/connected-accounts.md index 141dd65..bce2cb5 100644 --- a/plugins/agent-auth/references/connected-accounts.md +++ b/plugins/agent-auth/references/connected-accounts.md @@ -1,6 +1,8 @@ # Connected accounts -Connected accounts in Agent Auth represent individual user or organization connections to third-party providers. They contain the authentication state, tokens, and permissions needed to execute tools on behalf of a specific identifier (user_id, org_id, or custom identifier). +> Canonical doc: [../docs/connected-accounts.md](../docs/connected-accounts.md) + +Connected accounts in AgentKit represent individual user or organization authorizations for a connection. They contain the auth state, tokens, and permissions needed to execute tools on behalf of a specific identifier (`user_id`, `org_id`, or a custom identifier). ## What are connected accounts? @@ -51,7 +53,7 @@ F -> B ### Using the dashboard -1. Navigate to connected accounts in your Agent Auth dashboard +1. Navigate to connected accounts in your AgentKit dashboard 2. Click create account to start the process 3. Select connection to use for authentication 4. Enter identifier (user_id, email, or custom identifier) diff --git a/plugins/agent-auth/references/connections.md b/plugins/agent-auth/references/connections.md index ea68b33..d121801 100644 --- a/plugins/agent-auth/references/connections.md +++ b/plugins/agent-auth/references/connections.md @@ -1,6 +1,8 @@ # Connections -Connections in Agent Auth are specific configurations that define how your application authenticates and interacts with third-party providers. Each connection contains the necessary credentials, settings, and parameters required to establish secure communication with a provider's API. +> Canonical doc: [../docs/connections.md](../docs/connections.md) + +Connections in AgentKit are configurations that define how your application authenticates to a connector. A connection contains the credentials, scopes, and settings Scalekit needs before any user creates a connected account. ## Table of Contents @@ -18,17 +20,17 @@ Connections in Agent Auth are specific configurations that define how your appli ## What are connections? -Connections serve as the bridge between your Agent Auth setup and third-party providers. They contain: +Connections serve as the bridge between your AgentKit setup and third-party connectors. They contain: - **Authentication credentials** (OAuth client ID/secret, API keys, etc.) - **Configuration settings** (scopes, permissions, endpoints) -- **Tool definitions** and their parameters +- **Access configuration** used before tools are executed - **Rate limiting** and retry policies - **Custom settings** specific to your use case ## Connection types -Agent Auth supports various connection types based on different authentication methods: +AgentKit supports various connection types based on different authentication methods: ### OAuth 2.0 connections @@ -101,8 +103,8 @@ For providers with unique authentication requirements: ### Using the dashboard -1. **Navigate to connections** in your Agent Auth dashboard -2. **Select provider** from the list of available providers +1. **Navigate to connections** in your AgentKit dashboard +2. **Select connector** from the list of available connectors 3. **Choose connection type** based on your authentication method 4. **Configure credentials** by entering your API keys or OAuth settings 5. **Set permissions** and scopes for the connection @@ -111,7 +113,7 @@ For providers with unique authentication requirements: ### Using the API -Create connections programmatically using the Agent Auth API: +Create connections programmatically using the AgentKit API: **cURL:** diff --git a/plugins/agent-auth/references/providers.md b/plugins/agent-auth/references/providers.md index eea7217..8ccb64b 100644 --- a/plugins/agent-auth/references/providers.md +++ b/plugins/agent-auth/references/providers.md @@ -1,19 +1,21 @@ -# Providers +# Connectors Overview -Providers in Agent Auth represent third-party applications that your users can connect to and interact with through Scalekit's unified API. Each provider offers a set of tools and capabilities that can be executed on behalf of connected users. +> Canonical docs: [../docs/index.md](../docs/index.md) and [../docs/connectors/README.md](../docs/connectors/README.md) -## What are providers? +This page is a high-level connector overview for AgentKit. Use it for category-level guidance and terminology, not as the exhaustive source of truth for current tools. The live AgentKit tool metadata is the source of truth for tool names plus `input_schema` and `output_schema`. -Providers are pre-configured integrations with popular third-party applications that enable your users to: +## What are connectors? + +Connectors are pre-configured integrations with popular third-party applications that enable your users to: - **Connect their accounts** using secure authentication methods - **Execute tools and actions** through a unified API interface - **Access data and functionality** from external applications - **Maintain secure connections** with proper authorization scopes -## Supported providers +## Supported connectors -Agent Auth supports a wide range of popular business applications: +AgentKit supports a wide range of popular business applications: | Category | Providers | |---|---| @@ -27,11 +29,12 @@ Agent Auth supports a wide range of popular business applications: | **Data & Analytics** | BigQuery, Snowflake, Fathom | | **Service Management** | ServiceNow | -For per-connector tool specifications, see [agent-connectors/README.md](agent-connectors/README.md). +For curated connector notes, see [agent-connectors/README.md](agent-connectors/README.md). +For live tool discovery, see [tool-discovery.md](tool-discovery.md). -## Provider capabilities +## Connector capabilities -Each provider offers different capabilities based on their API and authentication model. +Each connector offers different capabilities based on its API and authentication model. ### Authentication methods @@ -39,9 +42,9 @@ Each provider offers different capabilities based on their API and authenticatio ### Available tools -Providers expose various tools that can be executed through Agent Auth: +Connectors expose various tools that can be executed through AgentKit: -> **Note:** Tool availability depends on the specific provider and the user's permissions within that application. +> **Note:** Tool availability depends on the specific connector, the current live catalog, and the user's permissions within that application. **Common tool categories:** @@ -59,17 +62,17 @@ Each provider has different rate limits and quotas: - **Data quotas**: Storage or transfer limitations - **Feature restrictions**: Premium features or enterprise-only capabilities -## Provider configuration +## Connector configuration -### Adding a provider +### Adding a connector -1. **Navigate to providers** in your Agent Auth dashboard -2. **Select provider** from the available options +1. **Navigate to connections** in your AgentKit dashboard +2. **Select connector** from the available options 3. **Configure settings** such as scopes and permissions 4. **Set up authentication** — configure OAuth client credentials if using custom OAuth apps 5. **Test connection** to verify provider setup -### Provider settings +### Connector settings Each provider can be configured with: @@ -83,11 +86,11 @@ Each provider can be configured with: - Request throttling settings - Backoff strategies for rate limit errors -## Working with provider APIs +## Working with connector APIs ### API integration -The Scalekit SDK abstracts provider-specific APIs — the workflow (create account → authorize → fetch token → call API) is identical for all providers. Only the downstream API call changes: +The Scalekit SDK abstracts connector-specific APIs. In AgentKit, prefer live tool discovery plus `execute_tool` over hand-coding upstream REST calls when a tool already exists. ```python # Step 3: Fetch token (always call this immediately before the API call) @@ -98,7 +101,7 @@ response = actions.get_connected_account( tokens = response.connected_account.authorization_details["oauth_token"] access_token = tokens["access_token"] -# Step 4: Call the provider API with the token +# Step 4: Call the connector API with the token headers = {"Authorization": f"Bearer {access_token}"} ``` @@ -106,7 +109,7 @@ Scalekit automatically refreshes expired tokens on `get_connected_account` — n ### Error handling -Agent Auth normalizes provider-specific errors into consistent error responses: +AgentKit normalizes connector-specific errors into consistent error responses: ```javascript { @@ -122,7 +125,7 @@ Agent Auth normalizes provider-specific errors into consistent error responses: } ``` -## Provider-specific considerations +## Connector-specific considerations ### Google Workspace @@ -183,7 +186,8 @@ Agent Auth normalizes provider-specific errors into consistent error responses: ## Related documentation -- [connections.md](connections.md) — how to configure authentication credentials for a provider +- [connections.md](connections.md) — how to configure authentication credentials for a connector - [connected-accounts.md](connected-accounts.md) — per-user account lifecycle and token management -- [agent-connectors/README.md](agent-connectors/README.md) — detailed API tools for each provider +- [agent-connectors/README.md](agent-connectors/README.md) — curated connector notes and examples +- [tool-discovery.md](tool-discovery.md) — live discovery model for current tools and schemas - [code-samples.md](code-samples.md) — implementation examples by framework diff --git a/plugins/agent-auth/references/tool-discovery.md b/plugins/agent-auth/references/tool-discovery.md new file mode 100644 index 0000000..9c472e6 --- /dev/null +++ b/plugins/agent-auth/references/tool-discovery.md @@ -0,0 +1,88 @@ +# Tool Discovery + +> Canonical doc: [../docs/tool-discovery.md](../docs/tool-discovery.md) + +## Overview + +In AgentKit, the live tool metadata is the source of truth for: + +- current connector coverage +- tool names +- `input_schema` +- `output_schema` + +The static connector notes in `references/agent-connectors/` are curated guidance. They are useful for auth quirks, example workflows, and product context, but they are not a guaranteed up-to-date catalog of every current tool. + +## Terminology + +- `connector`: the integration, such as Gmail, Slack, Salesforce, or a custom connector +- `connection`: the dashboard configuration created once per environment +- `connected account`: the per-user authorized instance of a connection +- `tool`: the executable action exposed by a connector + +Use `connector` in user-facing explanations. Use `provider` only when the SDK or API filter field literally uses that name. + +## Discovery rules + +1. Prefer live lookup over hand-maintained docs. +2. Narrow the search to a single connector or tool name whenever possible. +3. Summarize required inputs from `input_schema.required`. +4. Summarize optional inputs from `input_schema.properties`. +5. Describe likely results from `output_schema.properties`. +6. Recommend the smallest useful tool set before handing tools to an LLM. + +## What to inspect + +When live metadata is available, capture: + +- tool `name` +- tool `description` +- connector / provider slug +- `input_schema.properties` +- `input_schema.required` +- `output_schema.properties` + +If the metadata contains pagination or large result fields, mention them so the user can limit tool scope or post-process results before sending them back to the model. + +## How to use this in Claude Code + +For interactive discovery, use the live playground command: + +```sh +/test-tool get-tool --provider GMAIL +/test-tool get-tool --tool-name gmail_fetch_mails +``` + +For implementation guidance, use: + +- `discovering-agentkit-tools` when the user needs the current tool list or schema +- `testing-agentkit-tools` when the user wants to execute the tool and inspect the exact payload +- `integrating-agent-auth` when the user wants to wire the result into application code + +## Connection names vs connector names + +Do not confuse: + +- dashboard `connection_name`: exact value from `AgentKit -> Connections` +- connector / provider slug: value used to group live tools in metadata + +The first is for authorization and connected account flows. +The second is for catalog discovery and tool grouping. + +They are related, but they are not always the same string. + +## Example reasoning pattern + +1. User says: "What tools can I use for Google Sheets?" +2. Discover the live tool list for the Google Sheets connector. +3. Inspect the candidate tools and their `input_schema`. +4. Recommend only the few tools needed for the workflow, such as read values, update values, or append rows. +5. If the user wants to validate the flow, generate an auth link if needed and execute one tool with minimal input. + +## Fallback behavior + +If live credentials are not available: + +- use `references/agent-connectors/` as a directional guide +- clearly say the catalog may be stale +- avoid claiming that the listed tools are exhaustive diff --git a/plugins/agent-auth/rules/live-metadata-first.md b/plugins/agent-auth/rules/live-metadata-first.md new file mode 100644 index 0000000..43b6cda --- /dev/null +++ b/plugins/agent-auth/rules/live-metadata-first.md @@ -0,0 +1,19 @@ +# Live Metadata First + +Treat live AgentKit metadata as the source of truth for: + +- tool names +- connector coverage +- `input_schema` +- `output_schema` + +## Implications + +- Static connector notes are not exhaustive. +- Example code is not a catalog. +- Schema discovery should happen before guessing tool inputs. +- When credentials are available, prefer live lookup over prose documentation. + +## Fallback behavior + +If live credentials are unavailable, docs can still guide setup and workflow design, but they must be presented as directional guidance rather than guaranteed current truth. diff --git a/plugins/agent-auth/rules/terminology.md b/plugins/agent-auth/rules/terminology.md new file mode 100644 index 0000000..bc02173 --- /dev/null +++ b/plugins/agent-auth/rules/terminology.md @@ -0,0 +1,18 @@ +# Terminology + +Use these terms consistently in user-facing documentation and skills: + +- `connector`: the integration, such as Gmail, Slack, or Salesforce +- `connection`: the environment-level dashboard configuration +- `connected account`: the per-user authorization record +- `tool`: the executable action exposed by a connector + +## Preferred wording + +- Prefer `connector` in explanations to users. +- Use `provider` only when the SDK or API field literally uses that name. +- Do not imply that `connection_name` is always the same as the connector slug. + +## Why this rule exists + +The old language mixed `provider`, `connector`, and `connection_name` too freely. This rule keeps the AgentKit model stable across skills and docs. diff --git a/plugins/agent-auth/rules/tool-selection.md b/plugins/agent-auth/rules/tool-selection.md new file mode 100644 index 0000000..2b3dcd9 --- /dev/null +++ b/plugins/agent-auth/rules/tool-selection.md @@ -0,0 +1,22 @@ +# Tool Selection + +Keep the tool set as small as possible before handing it to an LLM. + +## Rules + +- Start from the workflow, not the full catalog. +- Discover only the connector or tool family relevant to the task. +- Inspect `input_schema` before execution when required fields are unclear. +- Avoid sending broad connector-wide tool lists to the model unless the task truly needs them. + +## Why this matters + +Too many tools degrade tool selection and parameter filling. Constraining the tool set improves both latency and correctness. + +## Practical pattern + +1. Identify the user goal. +2. Discover a narrow candidate set. +3. Inspect schema. +4. Validate with one live execution if needed. +5. Wire only the proven tools into the agent workflow. diff --git a/plugins/agent-auth/skills/agent-auth/SKILL.md b/plugins/agent-auth/skills/agent-auth/SKILL.md index 66e76c2..56db8af 100644 --- a/plugins/agent-auth/skills/agent-auth/SKILL.md +++ b/plugins/agent-auth/skills/agent-auth/SKILL.md @@ -1,304 +1,124 @@ --- name: integrating-agent-auth -description: Integrates Scalekit Agent Auth into a project to handle OAuth flows, token storage, and automatic refresh for third-party services (Gmail, Slack, Notion, Calendar). Use when a user needs to connect to an external service, authorize OAuth access, fetch access or refresh tokens, or execute API calls on behalf of a user. +description: Integrates Scalekit AgentKit into a project so an agent can create connections, authorize users, discover tools, and execute authenticated tool calls on their behalf. Use when a user needs to set up a connection, create a connected account, generate an authorization link, or wire AgentKit tools into application code or an agent framework. --- -# Agent Auth Integration +# AgentKit Integration -Scalekit handles the full OAuth lifecycle — authorization, token storage, and refresh — so agents can act on behalf of users in Gmail, Slack, Notion, Calendar, and other connectors. +Use this skill as the integration entrypoint for the plugin. It should stay thin and route into the canonical docs in `docs/`. -**Required env vars**: `SCALEKIT_CLIENT_ID`, `SCALEKIT_CLIENT_SECRET`, `SCALEKIT_ENV_URL` -→ Get from [app.scalekit.com](https://app.scalekit.com): Developers → Settings → API Credentials +## Mental model -## Setup +Keep these terms straight: -Install the SDK and initialize the client: +- `connector`: the integration, such as Gmail or Slack +- `connection`: the environment-level dashboard configuration +- `connected account`: the per-user authorization record +- `tool`: the executable action exposed by a connector -> **Important**: Except for Gmail, all connectors must be configured in the Scalekit Dashboard first before creating authorization URLs. -> -> To set up a connector: **Scalekit Dashboard → Agent Auth → Connections → + Create Connection → Select connector → Set Connection Name → Save** +Prefer live tool discovery over hand-maintained catalogs. If the user needs the current tool list or schema, switch to `discovering-agentkit-tools` or `testing-agentkit-tools`. - +## Default workflow -**Python** +1. Confirm `SCALEKIT_ENV_URL`, `SCALEKIT_CLIENT_ID`, and `SCALEKIT_CLIENT_SECRET`. +2. Verify the connection exists in `AgentKit -> Connections`. +3. Create or fetch the connected account for the user. +4. If the account is not `ACTIVE`, generate an authorization link. +5. Discover the exact tool and schema before execution. +6. Execute the tool directly or hand only the needed tools to an agent framework. + +## Quick integration skeleton + +### Python ```bash pip install scalekit-sdk-python ``` + ```python import scalekit.client, os from dotenv import load_dotenv load_dotenv() -scalekit = scalekit.client.ScalekitClient( +client = scalekit.client.ScalekitClient( client_id=os.getenv("SCALEKIT_CLIENT_ID"), client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"), env_url=os.getenv("SCALEKIT_ENV_URL"), ) -actions = scalekit.actions +actions = client.actions +response = actions.get_or_create_connected_account( + connection_name="MY_GMAIL", + identifier="user_123" +) +connected_account = response.connected_account +if connected_account.status != "ACTIVE": + link_response = actions.get_authorization_link( + connection_name="MY_GMAIL", + identifier="user_123" + ) + print("Authorize here:", link_response.link) +result = actions.execute_tool( + tool_name="gmail_fetch_mails", + identifier="user_123", + connected_account_id=connected_account.id, + tool_input={ + "query": "is:unread", + "max_results": 5, + }, +) +print(result) ``` -**Node.js** +### Node.js ```bash npm install @scalekit-sdk/node ``` + ```typescript import { ScalekitClient } from '@scalekit-sdk/node'; import 'dotenv/config'; -const scalekitClient = new ScalekitClient( +const client = new ScalekitClient( process.env.SCALEKIT_ENV_URL!, process.env.SCALEKIT_CLIENT_ID!, process.env.SCALEKIT_CLIENT_SECRET! ); -const { connectedAccounts } = scalekitClient; -``` - - - -## Connector setup - -Before integrating with a connector, follow these steps in the Scalekit Dashboard: - -> **Gmail is the only connector that does not require dashboard setup.** Skip this section for Gmail. - -For all other connectors (Slack, Notion, Google Calendar, etc.): - -1. Go to **Scalekit Dashboard → Agent Auth → Connections** -2. Click **+ Create Connection** -3. Select the connector you want to use -4. Enter a **Connection Name** (e.g., `MY_SLACK`, `MY_NOTION`) -5. Click **Save** - -> **Important**: The **Connection Name** you set in the dashboard is exactly what you use as the `connection_name` parameter in your code. They must match exactly. - -## Integration workflow - -**First, ask the user:** - -> Are you starting fresh and want a quick test with Gmail, or are you integrating directly into your project? - -- If **fresh / quick test**: Use the Gmail example below (Gmail is the only connector that doesn't require dashboard setup) -- If **integrating directly**: Create your connector in the Scalekit Dashboard first, then adapt the workflow below to your connector +const actions = client.actions; -Copy this checklist and check off steps as you complete them: - -``` -Agent Auth Integration Progress: -- [ ] Step 1: SDK installed and client initialized -- [ ] Step 2: Connected account created for the user -- [ ] Step 3: User has authorized the connection (status = ACTIVE) -- [ ] Step 4: Access token fetched successfully -- [ ] Step 5: Downstream API call succeeds with fetched token -``` - -### Step 1 — Create a connected account - -Replace `"user_123"` with the project's actual user ID. Replace `"gmail"` with the target connector. - -**Python** -```python -response = actions.get_or_create_connected_account( - connection_name="gmail", - identifier="user_123" -) -connected_account = response.connected_account -``` - -**Node.js** -```typescript -const response = await connectedAccounts.getOrCreateConnectedAccount({ - connector: 'gmail', +const response = await actions.getOrCreateConnectedAccount({ + connectionName: 'MY_GMAIL', identifier: 'user_123', }); const connectedAccount = response.connectedAccount; -``` - -### Step 2 — Authorize the user -If status is not `ACTIVE`, the user must complete OAuth. In a web app, redirect to `link`. In CLI/dev, print and wait. - -**Python** -```python -if connected_account.status != "ACTIVE": - link_response = actions.get_authorization_link( - connection_name="gmail", - identifier="user_123" - ) - print("Authorize here:", link_response.link) - input("Press Enter after authorizing...") -``` - -**Node.js** -```typescript if (connectedAccount?.status !== 'ACTIVE') { - const linkResponse = await connectedAccounts.getMagicLinkForConnectedAccount({ - connector: 'gmail', + const linkResponse = await actions.getAuthorizationLink({ + connectionName: 'MY_GMAIL', identifier: 'user_123', }); - console.log('Authorize here:', linkResponse.link); - // Web app: redirect user to linkResponse.link + console.log(linkResponse.link); } -``` -### Step 3 — Fetch OAuth tokens - -ALWAYS call `get_connected_account` immediately before any API call — Scalekit auto-refreshes tokens and this guarantees the latest valid token. - -**Python** -```python -response = actions.get_connected_account( - connection_name="gmail", - identifier="user_123" -) -tokens = response.connected_account.authorization_details["oauth_token"] -access_token = tokens["access_token"] -refresh_token = tokens["refresh_token"] -``` - -**Node.js** -```typescript -const accountResponse = await connectedAccounts.getConnectedAccountByIdentifier({ - connector: 'gmail', - identifier: 'user@example.com', +const result = await actions.executeTool({ + toolName: 'gmail_fetch_mails', + connectedAccountId: connectedAccount?.id, + identifier: 'user_123', + toolInput: { query: 'is:unread', max_results: 5 }, }); -const authDetails = accountResponse?.connectedAccount?.authorizationDetails; -const accessToken = authDetails?.details?.case === 'oauthToken' - ? authDetails.details.value?.accessToken : undefined; -const refreshToken = authDetails?.details?.case === 'oauthToken' - ? authDetails.details.value?.refreshToken : undefined; +console.log(result); ``` -### Step 4 — Call the third-party API - -Use `access_token` from Step 3 as a Bearer token. Example: fetch 5 unread Gmail messages. - -**Python** -```python -import requests - -headers = {"Authorization": f"Bearer {access_token}"} -list_url = "https://gmail.googleapis.com/gmail/v1/users/me/messages" - -messages = requests.get( - list_url, headers=headers, params={"q": "is:unread", "maxResults": 5} -).json().get("messages", []) - -for msg in messages: - data = requests.get( - f"{list_url}/{msg['id']}", headers=headers, - params={"format": "metadata", "metadataHeaders": ["From", "Subject", "Date"]} - ).json() - hdrs = data.get("payload", {}).get("headers", []) - print(next((h["value"] for h in hdrs if h["name"] == "Subject"), "No Subject")) - print(next((h["value"] for h in hdrs if h["name"] == "From"), "Unknown")) - print(data.get("snippet", "")) - print("-" * 50) -``` - -**Node.js** -```typescript -const listUrl = 'https://gmail.googleapis.com/gmail/v1/users/me/messages'; -const params = new URLSearchParams({ q: 'is:unread', maxResults: '5' }); - -const { messages = [] } = await fetch(`${listUrl}?${params}`, { - headers: { Authorization: `Bearer ${accessToken}` }, -}).then(r => r.json()); - -for (const msg of messages) { - const msgData = await fetch( - `${listUrl}/${msg.id}?format=metadata&metadataHeaders=From&metadataHeaders=Subject&metadataHeaders=Date`, - { headers: { Authorization: `Bearer ${accessToken}` } } - ).then(r => r.json()); - - const h = msgData.payload?.headers ?? []; - console.log('Subject:', h.find(x => x.name === 'Subject')?.value ?? 'No Subject'); - console.log('From:', h.find(x => x.name === 'From')?.value ?? 'Unknown'); - console.log('Snippet:', msgData.snippet ?? ''); - console.log('-'.repeat(50)); -} -``` - -## Adapting to other connectors - -Replace `"gmail"` with any supported connector name: `slack`, `notion`, `calendar`, etc. -The SDK workflow (Steps 1–3) is identical for all connectors. Only the downstream API call (Step 4) changes. - -For connector-specific API details, see [agent-connectors/README.md](../../references/agent-connectors/README.md). - -## Building agents - -Use Scalekit tools with AI frameworks to build agents that can execute actions on behalf of users. - -### LangChain agents - -Create conversational agents with LangChain that can autonomously call Scalekit tools based on user intent. - -**Python** -```python -from langchain_openai import ChatOpenAI -from langchain.agents import AgentExecutor, create_openai_tools_agent -from langchain_core.prompts import ChatPromptTemplate - -# Fetch tools from Scalekit in LangChain format -tools = actions.langchain.get_tools( - identifier="user_123", - providers=["GMAIL"], - page_size=100 -) - -# Define the agent prompt -prompt = ChatPromptTemplate.from_messages([ - ("system", "You are a helpful assistant with access to external tools."), - ("placeholder", "{chat_history}"), - ("human", "{input}"), - ("placeholder", "{agent_scratchpad}"), -]) - -# Create and run the agent -llm = ChatOpenAI(model="gpt-4o") -agent = create_openai_tools_agent(llm, tools, prompt) -executor = AgentExecutor(agent=agent, tools=tools, verbose=True) -result = executor.invoke({"input": "fetch my last 5 unread emails and summarize them"}) -``` - -### Google ADK agents - -Build agents using Google's Agent Development Kit with native Gemini integration. - -**Python** -```python -from google.adk.agents import Agent - -# Fetch tools from Scalekit in Google ADK format -gmail_tools = actions.google.get_tools( - providers=["GMAIL"], - identifier="user_123", - page_size=100 -) - -# Create the agent -agent = Agent( - name="gmail_assistant", - model="gemini-2.5-flash", - description="Gmail assistant that can read and manage emails", - instruction="You are a helpful Gmail assistant that can read, send, and organize emails.", - tools=gmail_tools -) - -# Run the agent -response = agent.process_request("fetch my last 5 unread emails and summarize them") -``` - -For more examples and framework-specific patterns, see [code-samples.md](../../references/code-samples.md). - ## Deep reference -For comprehensive documentation on connected accounts lifecycle, states, and API usage, see [connected-accounts.md](../../references/connected-accounts.md). - -For code samples and implementation examples by framework, see [code-samples.md](../../references/code-samples.md). - -For an overview of supported providers and their capabilities, see [providers.md](../../references/providers.md). +- Core docs: [../../docs/index.md](../../docs/index.md) +- Connections: [../../docs/connections.md](../../docs/connections.md) +- Connected accounts: [../../docs/connected-accounts.md](../../docs/connected-accounts.md) +- Tool discovery: [../../docs/tool-discovery.md](../../docs/tool-discovery.md) +- Code-sample entrypoint: [../../docs/code-samples.md](../../docs/code-samples.md) +- BYOC: [../../docs/byoc.md](../../docs/byoc.md) +- Connector notes: [../../docs/connectors/README.md](../../docs/connectors/README.md) -For token refresh behavior and operational guidance, see [connected-accounts.md](../../references/connected-accounts.md). +## When to switch skills -For configuring your own OAuth credentials per connector (whitelabeling, dedicated quotas), see [byoc.md](../../references/byoc.md). +- Use `discovering-agentkit-tools` when the user needs the current tool catalog or schema. +- Use `testing-agentkit-tools` when the user wants to validate a tool call in Claude Code. +- Use `building-agent-mcp-server` when the user wants AgentKit tools exposed over MCP. diff --git a/plugins/agent-auth/skills/building-agent-mcp-server/SKILL.md b/plugins/agent-auth/skills/building-agent-mcp-server/SKILL.md index b8e85b7..c3bd41b 100644 --- a/plugins/agent-auth/skills/building-agent-mcp-server/SKILL.md +++ b/plugins/agent-auth/skills/building-agent-mcp-server/SKILL.md @@ -1,15 +1,15 @@ --- name: building-agent-mcp-server -description: Guides developers through creating a Scalekit MCP server with authenticated tool access. Use when building an MCP server, exposing Scalekit tools over MCP, or connecting AI agents via LangChain/LangGraph MCP adapters. +description: Guides developers through creating a Scalekit AgentKit MCP server with authenticated tool access. Use when building an MCP server, exposing AgentKit tools over MCP, or connecting AI agents via LangChain or LangGraph MCP adapters. --- # Building an Agent MCP Server Scalekit lets you build MCP servers that manage authentication, create personalized access URLs for users, and define which tools are accessible. You can also bundle several toolkits (e.g., Gmail + Google Calendar) within a single server. -[Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) is an open-source standard that enables AI systems to interface with external tools and data sources. Where the `integrating-agent-auth` skill uses the SDK directly, this workflow exposes Scalekit tools over the MCP protocol so any compliant client — LangChain, Claude Desktop, MCP Inspector — can consume them. +[Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro) is an open-source standard that enables AI systems to interface with external tools and data sources. Where the `integrating-agent-auth` skill uses the SDK directly, this workflow exposes AgentKit tools over the MCP protocol so any compliant client — LangChain, Claude Desktop, MCP Inspector — can consume them. -> **Note:** Agent Auth MCP servers only support Streamable HTTP transport. +> **Note:** AgentKit MCP servers only support Streamable HTTP transport. ## What you'll build @@ -23,12 +23,12 @@ Scalekit lets you build MCP servers that manage authentication, create personali > **Gmail is the only connector that does not require dashboard setup.** All other connectors (including Google Calendar) must be created in the Scalekit Dashboard before use: > -> Go to **Scalekit Dashboard → Agent Auth → Connections → + Create Connection → Select connector** → Set `Connection Name` → Save +> Go to **Scalekit Dashboard → AgentKit → Connections → + Create Connection → Select connector** → Set `Connection Name` → Save > **Important**: The **Connection Name** you set in the dashboard is exactly what you use as the `connection_name` parameter in your code. They must match exactly. For this example, create the Google Calendar connector: -- [ ] **Google Calendar connector**: Scalekit Dashboard → Agent Auth → Connections → Create Connection → Google Calendar → `Connection Name = MY_CALENDAR` → Save +- [ ] **Google Calendar connector**: Scalekit Dashboard → AgentKit → Connections → Create Connection → Google Calendar → `Connection Name = MY_CALENDAR` → Save ## Step 1 — Set up your environment @@ -156,3 +156,10 @@ asyncio.run(main()) > **Note — MCP client compatibility:** You can test this MCP server with popular clients like MCP Inspector, Claude Desktop, and other spec-compliant implementations. Note that ChatGPT's beta connector feature may not work properly as it's still in beta and doesn't fully adhere to the MCP specification yet. Full working example: [github.com/scalekit-inc/python-connect-demos/tree/main/mcp](https://github.com/scalekit-inc/python-connect-demos/tree/main/mcp) + +## Deep reference + +- Canonical docs entrypoint: [../../docs/index.md](../../docs/index.md) +- Connections: [../../docs/connections.md](../../docs/connections.md) +- Connected accounts: [../../docs/connected-accounts.md](../../docs/connected-accounts.md) +- Tool discovery: [../../docs/tool-discovery.md](../../docs/tool-discovery.md) diff --git a/plugins/agent-auth/skills/discovering-agentkit-tools/SKILL.md b/plugins/agent-auth/skills/discovering-agentkit-tools/SKILL.md new file mode 100644 index 0000000..3a29c71 --- /dev/null +++ b/plugins/agent-auth/skills/discovering-agentkit-tools/SKILL.md @@ -0,0 +1,56 @@ +--- +name: discovering-agentkit-tools +description: Discovers live Scalekit AgentKit tools for a connector and explains their input and output schemas. Use when a user asks what tools are available for Gmail, Slack, Salesforce, or another connector, wants to inspect `input_schema` or `output_schema`, or needs help narrowing the tool set for an agent. +--- + +# Discovering AgentKit Tools + +Use live AgentKit metadata as the source of truth for tool names, required inputs, and output schemas. + +Do not rely on the static connector notes as a complete catalog. Those files are curated reference material and may lag the live platform. + +## When to use this skill + +Use this skill when the user asks: + +- what tools exist for a connector +- which tool should the agent use +- what inputs a tool requires +- what output shape a tool returns +- how to reduce the tool set before giving tools to an LLM + +## Discovery workflow + +1. Identify the target connector or exact tool name. +2. Prefer live lookup through the built-in testing workflow or SDK metadata. +3. Summarize: + - tool name + - connector + - what the tool does + - required fields from `input_schema.required` + - optional fields from `input_schema.properties` + - important fields from `output_schema.properties` +4. Recommend the smallest useful tool set for the workflow. +5. If live credentials are unavailable, use the connector notes only as a fallback and say they may be stale. + +## Terminology + +- `connector`: Gmail, Slack, Salesforce, Notion, or a custom connector +- `connection`: the exact dashboard configuration name used for authorization +- `connected account`: the per-user authorized record +- `tool`: the executable action exposed by a connector + +Use `connector` in explanations. Only use `provider` when the SDK or API filter field literally expects that name. + +## What to emphasize + +- `connection_name` is the exact dashboard value and may not equal the connector slug. +- Tool metadata is the durable way to determine current inputs and outputs. +- Restrict the tool set before handing it to an LLM. Fewer relevant tools improve tool selection and parameter filling. + +## Deep reference + +- Canonical docs entrypoint: [../../docs/index.md](../../docs/index.md) +- Live discovery model: [../../docs/tool-discovery.md](../../docs/tool-discovery.md) +- Curated connector notes: [../../docs/connectors/README.md](../../docs/connectors/README.md) +- Broader implementation examples: [../../docs/code-samples.md](../../docs/code-samples.md) diff --git a/plugins/agent-auth/skills/production-readiness-scalekit/SKILL.md b/plugins/agent-auth/skills/production-readiness-scalekit/SKILL.md index 152ffd3..a79fcbe 100644 --- a/plugins/agent-auth/skills/production-readiness-scalekit/SKILL.md +++ b/plugins/agent-auth/skills/production-readiness-scalekit/SKILL.md @@ -1,9 +1,9 @@ --- name: production-readiness-scalekit -description: Walks through a structured production readiness checklist for Scalekit agent authentication implementations. Use when the user says they are going live, launching to production, doing a pre-launch review, or wants to verify their agent OAuth implementation is production-ready. +description: Walks through a structured production readiness checklist for Scalekit AgentKit implementations. Use when the user says they are going live, launching to production, doing a pre-launch review, or wants to verify their AgentKit authorization and tool-calling setup is production-ready. --- -# Scalekit Agent Auth Production Readiness +# Scalekit AgentKit Production Readiness Work through each section in order — earlier sections are blockers for later ones. @@ -60,3 +60,10 @@ Work through each section in order — earlier sections are blockers for later o - OAuth authorization completion rate (initiated vs completed) - Per-service API error rates (distinguish auth errors from service errors) - Token expiry distribution (are tokens being refreshed proactively?) + +## Deep reference + +- Canonical docs entrypoint: [../../docs/index.md](../../docs/index.md) +- Connections: [../../docs/connections.md](../../docs/connections.md) +- Connected accounts: [../../docs/connected-accounts.md](../../docs/connected-accounts.md) +- BYOC: [../../docs/byoc.md](../../docs/byoc.md) diff --git a/plugins/agent-auth/skills/testing-agentkit-tools/SKILL.md b/plugins/agent-auth/skills/testing-agentkit-tools/SKILL.md new file mode 100644 index 0000000..e989cff --- /dev/null +++ b/plugins/agent-auth/skills/testing-agentkit-tools/SKILL.md @@ -0,0 +1,50 @@ +--- +name: testing-agentkit-tools +description: Tests live Scalekit AgentKit flows from Claude Code by generating authorization links, fetching tool metadata, and executing a tool for a connected account. Use when a user wants to validate a connector, inspect the exact payload for `execute_tool`, or build a workflow step by step in the editor. +--- + +# Testing AgentKit Tools + +This skill is the live playground layer for AgentKit inside Claude Code. + +Use it to: + +- generate an authorization link for a connection +- fetch live tool metadata for a connector or tool name +- execute a tool with real inputs +- inspect the exact JSON payload sent to AgentKit + +## Default workflow + +1. Confirm the environment variables are available: + - `SCALEKIT_ENV_URL` + - `SCALEKIT_CLIENT_ID` + - `SCALEKIT_CLIENT_SECRET` + - legacy `TOOL_*` aliases are accepted for backward compatibility +2. Discover the tool first when the schema is unknown. +3. Generate an authorization link if the connected account is not `ACTIVE`. +4. Execute the tool with the smallest valid `tool_input`. +5. Show the exact command and payload used so the user can translate it into app code. + +## Command surface + +Use `/test-tool` for the runnable playground: + +- `/test-tool get-tool --provider GMAIL` +- `/test-tool get-tool --tool-name gmail_fetch_mails` +- `/test-tool generate-link --connection-name MY_GMAIL --identifier user_123` +- `/test-tool execute-tool --tool-name gmail_fetch_mails --connection-name MY_GMAIL --identifier user_123 --tool-input '{"query":"is:unread","max_results":5}'` + +## Guardrails + +- Treat live metadata as the source of truth for `input_schema` and `output_schema`. +- Do not assume the dashboard `connection_name` matches the connector slug. +- Ask for missing credentials instead of inventing placeholder values. +- Keep the tool set constrained to the current workflow. + +## Deep reference + +- Playground command: [../../commands/test-tool.md](../../commands/test-tool.md) +- Canonical docs entrypoint: [../../docs/index.md](../../docs/index.md) +- Live discovery model: [../../docs/tool-discovery.md](../../docs/tool-discovery.md) +- Integration workflow: [../agent-auth/SKILL.md](../agent-auth/SKILL.md) diff --git a/plugins/agent-auth/skills/testing-agentkit-tools/scripts/connect.py b/plugins/agent-auth/skills/testing-agentkit-tools/scripts/connect.py new file mode 100644 index 0000000..e628a4d --- /dev/null +++ b/plugins/agent-auth/skills/testing-agentkit-tools/scripts/connect.py @@ -0,0 +1,250 @@ +#!/usr/bin/env python3 +""" +AgentKit playground for Claude Code. + +Supports: +- generate-link +- get-tool +- execute-tool +""" + +import argparse +import json +import os +import sys + +try: + from dotenv import load_dotenv + load_dotenv() +except ImportError: + pass + +try: + from google.protobuf.json_format import MessageToDict +except ImportError: + MessageToDict = None + +import scalekit.client as scalekit_sdk + + +BOLD = "\033[1m" +GREEN = "\033[92m" +RED = "\033[91m" +YELLOW = "\033[93m" +BLUE = "\033[94m" +RESET = "\033[0m" + + +def env_value(primary: str, legacy: str) -> str: + return os.getenv(primary) or os.getenv(legacy) or "" + + +SCALEKIT_ENV_URL = env_value("SCALEKIT_ENV_URL", "TOOL_ENV_URL") +SCALEKIT_CLIENT_ID = env_value("SCALEKIT_CLIENT_ID", "TOOL_CLIENT_ID") +SCALEKIT_CLIENT_SECRET = env_value("SCALEKIT_CLIENT_SECRET", "TOOL_CLIENT_SECRET") + + +def require_env() -> None: + missing = [] + if not SCALEKIT_ENV_URL: + missing.append("SCALEKIT_ENV_URL") + if not SCALEKIT_CLIENT_ID: + missing.append("SCALEKIT_CLIENT_ID") + if not SCALEKIT_CLIENT_SECRET: + missing.append("SCALEKIT_CLIENT_SECRET") + if missing: + print(f"{RED}Missing required environment variables: {', '.join(missing)}{RESET}") + print("Legacy TOOL_* aliases are also supported.") + sys.exit(1) + + +def get_scalekit_client(): + require_env() + return scalekit_sdk.ScalekitClient( + SCALEKIT_ENV_URL, + SCALEKIT_CLIENT_ID, + SCALEKIT_CLIENT_SECRET, + ) + + +def get_connect_client(): + client = get_scalekit_client() + return client.actions if hasattr(client, "actions") else client.connect + + +def to_jsonable(value): + if MessageToDict is not None and hasattr(value, "DESCRIPTOR"): + return MessageToDict(value, preserving_proto_field_name=True) + if isinstance(value, (dict, list, str, int, float, bool)) or value is None: + return value + if isinstance(value, bytes): + return value.decode("utf-8", errors="replace") + if hasattr(value, "__dict__"): + return {key: to_jsonable(val) for key, val in vars(value).items() if not key.startswith("_")} + return str(value) + + +def print_json(value) -> None: + print(json.dumps(to_jsonable(value), indent=2)) + + +def get_or_create_account(connection_name: str, identifier: str): + connect = get_connect_client() + response = connect.get_or_create_connected_account( + connection_name=connection_name, + identifier=identifier, + ) + return response.connected_account + + +def generate_link(connection_name: str, identifier: str) -> None: + connect = get_connect_client() + + print(f" Connection: {connection_name}") + print(f" Identifier: {identifier}") + print() + + try: + connected_account = get_or_create_account(connection_name, identifier) + print(f" Connected Account ID: {connected_account.id}") + print(f" Status: {connected_account.status}") + + if connected_account.status != "ACTIVE": + link_response = connect.get_authorization_link( + connection_name=connection_name, + identifier=identifier, + ) + print(f"\n{YELLOW}⚠ Connected account is not ACTIVE yet.{RESET}") + print(f"\n🔗 Click the link to authorize {connection_name}:") + print(f" {BLUE}{link_response.link}{RESET}") + else: + print(f"\n{GREEN}✅ {connection_name} is already connected and active.{RESET}") + + except Exception as exc: + print(f"\n{RED}❌ Error: {exc}{RESET}") + sys.exit(1) + + +def execute_tool(tool_name: str, connection_name: str, identifier: str, tool_input: dict) -> None: + connect = get_connect_client() + + print(f" Tool: {tool_name}") + print(f" Connection: {connection_name}") + print(f" Identifier: {identifier}") + print(f" Input: {json.dumps(tool_input, indent=2)}") + print() + + try: + connected_account = get_or_create_account(connection_name, identifier) + print(f" Connected Account ID: {connected_account.id}") + print(f" Status: {connected_account.status}") + + if connected_account.status != "ACTIVE": + link_response = connect.get_authorization_link( + connection_name=connection_name, + identifier=identifier, + ) + print(f"\n{YELLOW}⚠ Connected account is not ACTIVE yet.{RESET}") + print(f"\n🔗 Authorize {connection_name} here:") + print(f" {BLUE}{link_response.link}{RESET}") + print(f"\n{YELLOW}Re-run this command after the user completes authorization.{RESET}") + sys.exit(0) + + print(f"\n🔧 Executing tool: {BOLD}{tool_name}{RESET}") + result = connect.execute_tool( + tool_name=tool_name, + identifier=identifier, + connected_account_id=connected_account.id, + tool_input=tool_input, + ) + + print(f"\n{GREEN}✅ Result:{RESET}") + print_json(result) + + except Exception as exc: + print(f"\n{RED}❌ Error: {exc}{RESET}") + sys.exit(1) + + +def get_tool(tool_name: str = None, provider: str = None, page_size: int = None, page_token: str = None) -> None: + client = get_scalekit_client() + + try: + from scalekit.v1.tools.tools_pb2 import Filter + + filter_kwargs = {} + if tool_name: + filter_kwargs["tool_name"] = [tool_name] + if provider: + filter_kwargs["provider"] = provider + + list_kwargs = {} + if filter_kwargs: + list_kwargs["filter"] = Filter(**filter_kwargs) + if page_size is not None: + list_kwargs["page_size"] = page_size + if page_token: + list_kwargs["page_token"] = page_token + + response, _ = client.tools.list_tools(**list_kwargs) + print_json(response) + + except Exception as exc: + print(f"\n{RED}❌ Error: {exc}{RESET}") + sys.exit(1) + + +def main() -> None: + parser = argparse.ArgumentParser( + description="AgentKit playground - generate auth links, fetch tool metadata, and execute tools", + ) + + group = parser.add_mutually_exclusive_group(required=True) + group.add_argument("--generate-link", action="store_true", help="Generate authorization link if needed") + group.add_argument("--get-tool", action="store_true", help="Fetch live tool metadata") + group.add_argument("--execute-tool", action="store_true", help="Execute a live tool") + + parser.add_argument("--connection-name", help="Exact dashboard connection name") + parser.add_argument("--identifier", help="User or account identifier") + parser.add_argument("--tool-name", help="Tool name to fetch or execute") + parser.add_argument("--tool-input", help="JSON string passed to the tool") + parser.add_argument("--provider", help="Provider filter for live tool discovery") + parser.add_argument("--page-size", type=int, help="Page size for tool listing") + parser.add_argument("--page-token", help="Pagination token for tool listing") + + args = parser.parse_args() + + if args.generate_link: + if not args.connection_name or not args.identifier: + parser.error("--connection-name and --identifier are required for --generate-link") + generate_link(args.connection_name, args.identifier) + return + + if args.get_tool: + get_tool( + tool_name=args.tool_name, + provider=args.provider, + page_size=args.page_size, + page_token=args.page_token, + ) + return + + if not args.connection_name or not args.identifier or not args.tool_name or not args.tool_input: + parser.error("--connection-name, --identifier, --tool-name, and --tool-input are required for --execute-tool") + + try: + tool_input = json.loads(args.tool_input) + except json.JSONDecodeError as exc: + print(f"{RED}❌ Invalid JSON for --tool-input: {exc}{RESET}") + sys.exit(1) + + execute_tool( + tool_name=args.tool_name, + connection_name=args.connection_name, + identifier=args.identifier, + tool_input=tool_input, + ) + + +if __name__ == "__main__": + main() From 93e21f5572fa6a09435fad6febb8e4e367c69d32 Mon Sep 17 00:00:00 2001 From: Saif Shines Date: Tue, 5 May 2026 21:21:29 +0530 Subject: [PATCH 2/5] chore: bump agent-auth plugin to v2 Raise the agent-auth plugin manifest to 2.0.0 so the hybrid AgentKit reorganization can ship as a major update and users can pick up the new version cleanly. Co-authored-by: Cursor --- plugins/agent-auth/.claude-plugin/plugin.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/agent-auth/.claude-plugin/plugin.json b/plugins/agent-auth/.claude-plugin/plugin.json index 9475a92..f3aeedf 100644 --- a/plugins/agent-auth/.claude-plugin/plugin.json +++ b/plugins/agent-auth/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agent-auth", "description": "Sets up Scalekit AgentKit in Claude Code so agents can authorize users, discover tools, and execute authenticated tool calls across connectors.", - "version": "1.9.0", + "version": "2.0.0", "author": { "name": "Scalekit", "email": "hi@scalekit.com" From 6c8d28a8417a0e4400c42ad3b9a36d2e04cf6f58 Mon Sep 17 00:00:00 2001 From: Saif Shines Date: Tue, 5 May 2026 21:25:49 +0530 Subject: [PATCH 3/5] docs: add Claude installer and AgentKit doc links Add a one-line Claude Code installer that adds the marketplace, installs the agent-auth plugin, and points users to enable auto-update. Also thread official docs.scalekit.com AgentKit links through the new canonical docs so the plugin can point back to the published product documentation. Co-authored-by: Cursor --- README.md | 22 ++++++++++-- install.sh | 35 +++++++++++++++++++ plugins/agent-auth/README.md | 6 ++++ plugins/agent-auth/docs/byoc.md | 4 +++ plugins/agent-auth/docs/code-samples.md | 7 ++++ plugins/agent-auth/docs/connected-accounts.md | 5 +++ plugins/agent-auth/docs/connections.md | 5 +++ plugins/agent-auth/docs/connectors/README.md | 4 +++ plugins/agent-auth/docs/index.md | 9 +++++ plugins/agent-auth/docs/tool-discovery.md | 6 ++++ scripts/install_claude_marketplace.sh | 31 ++++++++++++++++ 11 files changed, 132 insertions(+), 2 deletions(-) create mode 100755 install.sh create mode 100755 scripts/install_claude_marketplace.sh diff --git a/README.md b/README.md index 8ed1764..76723f9 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,13 @@ This plugin adds the complete Scalekit auth stack to your projects — whether t ### Installation +```sh +# One-line installer +curl -fsSL https://raw.githubusercontent.com/scalekit-inc/claude-code-authstack/main/install.sh | bash +``` + +Or install manually inside Claude Code: + ```sh # Start Claude REPL claude @@ -31,10 +38,20 @@ claude # Add Scalekit Auth Stack marketplace /plugin marketplace add scalekit-inc/claude-code-authstack -# Run the plugins wizard +# Install AgentKit for AI agents +/plugin install agent-auth@scalekit-auth-stack + +# Open the plugins wizard /plugins ``` +After installation, enable auto-update: + +1. Open `/plugins` +2. Go to `Marketplaces` +3. Select `scalekit-auth-stack` +4. Enable `auto-update` + --- ### Available Plugins @@ -130,7 +147,8 @@ Use this to add login, callback handling, sessions, and logout flows to web apps - [MCP Auth guide](https://docs.scalekit.com/authenticate/mcp/quickstart/) — Secure MCP servers - [Full-stack auth guide](https://docs.scalekit.com/authenticate/fsa/quickstart/) — Add login, callback, and session management - [SCIM directory sync guide](https://docs.scalekit.com/directory/scim/quickstart/) — Provision and deprovision users -- [Agent Auth Guide](https://docs.scalekit.com/agent-auth/quickstart/) — Authentication for AI agents +- [AgentKit overview](https://docs.scalekit.com/agentkit/overview.md) — Connect agents to authenticated tools through connectors, connections, and connected accounts +- [AgentKit quickstart](https://docs.scalekit.com/agentkit/quickstart.md) — Build an agent that makes authenticated tool calls on behalf of users #### Resources diff --git a/install.sh b/install.sh new file mode 100755 index 0000000..07f9907 --- /dev/null +++ b/install.sh @@ -0,0 +1,35 @@ +#!/usr/bin/env bash + +set -euo pipefail + +REPO_SLUG="${CLAUDE_CODE_AUTHSTACK_REPO:-scalekit-inc/claude-code-authstack}" +REPO_REF="${CLAUDE_CODE_AUTHSTACK_REF:-main}" +SOURCE_DIR="${CLAUDE_CODE_AUTHSTACK_SOURCE_DIR:-}" + +if [[ -n "$SOURCE_DIR" ]]; then + exec "${SOURCE_DIR%/}/scripts/install_claude_marketplace.sh" +fi + +TMP_DIR="$(mktemp -d)" +cleanup() { + rm -rf "$TMP_DIR" +} +trap cleanup EXIT + +ARCHIVE_URL="https://github.com/${REPO_SLUG}/archive/refs/heads/${REPO_REF}.tar.gz" +ARCHIVE_PATH="$TMP_DIR/claude-code-authstack.tar.gz" + +echo "Downloading Scalekit Auth Stack for Claude Code from:" +echo " $ARCHIVE_URL" + +curl -fsSL "$ARCHIVE_URL" -o "$ARCHIVE_PATH" +tar -xzf "$ARCHIVE_PATH" -C "$TMP_DIR" + +EXTRACTED_DIR="$(find "$TMP_DIR" -mindepth 1 -maxdepth 1 -type d | head -n 1)" + +if [[ -z "$EXTRACTED_DIR" ]] || [[ ! -x "$EXTRACTED_DIR/scripts/install_claude_marketplace.sh" ]]; then + echo "Failed to find installer in downloaded archive." >&2 + exit 1 +fi + +exec "$EXTRACTED_DIR/scripts/install_claude_marketplace.sh" diff --git a/plugins/agent-auth/README.md b/plugins/agent-auth/README.md index 1208999..47ccf84 100644 --- a/plugins/agent-auth/README.md +++ b/plugins/agent-auth/README.md @@ -24,6 +24,12 @@ claude /plugin install agent-auth@scalekit-auth-stack Start with the canonical docs entrypoint at [`docs/index.md`](docs/index.md). +Official Scalekit docs: +- [AgentKit overview](https://docs.scalekit.com/agentkit/overview.md) +- [AgentKit quickstart](https://docs.scalekit.com/agentkit/quickstart.md) +- [AgentKit connectors](https://docs.scalekit.com/agentkit/connectors.md) +- [AgentKit examples](https://docs.scalekit.com/agentkit/examples.md) + ## Skills Reference - `/agent-auth:integrating-agent-auth` Integrates AgentKit into app code or an agent workflow and routes into the core docs. diff --git a/plugins/agent-auth/docs/byoc.md b/plugins/agent-auth/docs/byoc.md index 1ff5319..b4963ff 100644 --- a/plugins/agent-auth/docs/byoc.md +++ b/plugins/agent-auth/docs/byoc.md @@ -11,6 +11,10 @@ Common reasons: - you need stricter compliance or audit ownership - you want a more fully whitelabeled production experience +## Official Scalekit docs + +- [Bring your own credentials](https://docs.scalekit.com/agentkit/advanced/bring-your-own-oauth.md) + ## What changes With BYOC: diff --git a/plugins/agent-auth/docs/code-samples.md b/plugins/agent-auth/docs/code-samples.md index b71f29d..3379b77 100644 --- a/plugins/agent-auth/docs/code-samples.md +++ b/plugins/agent-auth/docs/code-samples.md @@ -20,6 +20,13 @@ Use it to choose an implementation style before opening a larger sample reposito - Direct SDK usage: best for deterministic or single-tool flows - MCP: best when you want tools exposed to MCP-compatible runtimes +## Official Scalekit docs + +- [AgentKit examples](https://docs.scalekit.com/agentkit/examples.md) +- [Code samples](https://docs.scalekit.com/agentkit/code-samples.md) +- [LangChain example](https://docs.scalekit.com/agentkit/examples/langchain.md) +- [Google ADK example](https://docs.scalekit.com/agentkit/examples/google-adk.md) + ## Important rule Do not treat example code as a fixed tool catalog. diff --git a/plugins/agent-auth/docs/connected-accounts.md b/plugins/agent-auth/docs/connected-accounts.md index 9a36988..5d1f52f 100644 --- a/plugins/agent-auth/docs/connected-accounts.md +++ b/plugins/agent-auth/docs/connected-accounts.md @@ -23,6 +23,11 @@ Typical lifecycle: 4. The account becomes `ACTIVE`. 5. AgentKit can execute tools on behalf of that user. +## Official Scalekit docs + +- [Manage connected accounts](https://docs.scalekit.com/agentkit/connected-accounts.md) +- [Authorize a user](https://docs.scalekit.com/agentkit/tools/authorize.md) + ## Operational rules - Always use the correct user identifier from your own system. diff --git a/plugins/agent-auth/docs/connections.md b/plugins/agent-auth/docs/connections.md index 4e7bc17..8b437fd 100644 --- a/plugins/agent-auth/docs/connections.md +++ b/plugins/agent-auth/docs/connections.md @@ -22,6 +22,11 @@ Do not confuse: They are related, but they are not always the same string. +## Official Scalekit docs + +- [Configure a connection](https://docs.scalekit.com/agentkit/connections.md) +- [Scopes and permissions](https://docs.scalekit.com/agentkit/authentication/scopes-permissions.md) + ## Typical setup flow 1. Go to `AgentKit -> Connections` in the Scalekit Dashboard. diff --git a/plugins/agent-auth/docs/connectors/README.md b/plugins/agent-auth/docs/connectors/README.md index 2b30396..ac98d20 100644 --- a/plugins/agent-auth/docs/connectors/README.md +++ b/plugins/agent-auth/docs/connectors/README.md @@ -11,6 +11,10 @@ Connector notes are intentionally curated and lightweight. They should explain: They should not claim to be the exhaustive current tool catalog. +## Official Scalekit docs + +- [Agent connectors](https://docs.scalekit.com/agentkit/connectors.md) + ## Source of truth Use live AgentKit metadata for: diff --git a/plugins/agent-auth/docs/index.md b/plugins/agent-auth/docs/index.md index bd1d633..d584cbf 100644 --- a/plugins/agent-auth/docs/index.md +++ b/plugins/agent-auth/docs/index.md @@ -12,6 +12,15 @@ Use it for the durable AgentKit model: The Claude Code plugin still includes adapter/runtime files such as `.claude-plugin/`, `.mcp.json`, `commands/`, `hooks/`, and `agents/`, but those are secondary to the content model here. +## Official Scalekit docs + +These pages are the best external entrypoints for the material in this directory: + +- [AgentKit overview](https://docs.scalekit.com/agentkit/overview.md) +- [AgentKit quickstart](https://docs.scalekit.com/agentkit/quickstart.md) +- [AgentKit connectors](https://docs.scalekit.com/agentkit/connectors.md) +- [AgentKit examples](https://docs.scalekit.com/agentkit/examples.md) + ## How this directory is organized - [connections.md](connections.md) explains how AgentKit connections are configured and named. diff --git a/plugins/agent-auth/docs/tool-discovery.md b/plugins/agent-auth/docs/tool-discovery.md index cf35130..49643e5 100644 --- a/plugins/agent-auth/docs/tool-discovery.md +++ b/plugins/agent-auth/docs/tool-discovery.md @@ -25,6 +25,12 @@ Use live metadata for: - optional input fields - output shape +## Official Scalekit docs + +- [Tools overview](https://docs.scalekit.com/agentkit/tools/overview.md) +- [Scalekit optimized built-in tools](https://docs.scalekit.com/agentkit/tools/scalekit-optimized-tools.md) +- [AgentKit connectors](https://docs.scalekit.com/agentkit/connectors.md) + ## Discovery workflow 1. Start from a connector or exact tool name. diff --git a/scripts/install_claude_marketplace.sh b/scripts/install_claude_marketplace.sh new file mode 100755 index 0000000..ce1c53f --- /dev/null +++ b/scripts/install_claude_marketplace.sh @@ -0,0 +1,31 @@ +#!/usr/bin/env bash + +set -euo pipefail + +if ! command -v claude >/dev/null 2>&1; then + echo "Claude Code CLI is not installed or not on PATH." >&2 + echo "Install Claude Code first, then re-run this installer." >&2 + exit 1 +fi + +MARKETPLACE_SLUG="${CLAUDE_CODE_AUTHSTACK_MARKETPLACE:-scalekit-inc/claude-code-authstack}" +PLUGIN_SOURCE="${CLAUDE_CODE_AUTHSTACK_PLUGIN_SOURCE:-agent-auth@scalekit-auth-stack}" + +echo "Installing Scalekit Auth Stack for Claude Code" +echo "Marketplace: $MARKETPLACE_SLUG" +echo "Plugin: $PLUGIN_SOURCE" +echo + +claude plugin marketplace add "$MARKETPLACE_SLUG" +claude plugin install "$PLUGIN_SOURCE" + +cat < Date: Tue, 5 May 2026 21:28:49 +0530 Subject: [PATCH 4/5] docs: add llms and sitemap doc entrypoints Add the stable llms.txt and sitemap-0.xml links to the main Claude Code auth stack docs and the canonical agent-auth docs entrypoints so users and agents have clear fallback indexes into published Scalekit documentation. Co-authored-by: Cursor --- README.md | 2 ++ plugins/agent-auth/README.md | 2 ++ plugins/agent-auth/docs/index.md | 2 ++ 3 files changed, 6 insertions(+) diff --git a/README.md b/README.md index 76723f9..b759034 100644 --- a/README.md +++ b/README.md @@ -142,6 +142,8 @@ Use this to add login, callback handling, sessions, and logout flows to web apps #### Documentation - [Scalekit Documentation](https://docs.scalekit.com) — Complete guides and API reference +- [LLM docs map](https://docs.scalekit.com/llms.txt) — High-level index of published Scalekit documentation sets +- [Docs sitemap](https://docs.scalekit.com/sitemap-0.xml) — Stable sitemap for discovering published docs pages - [Build with AI overview](https://docs.scalekit.com/dev-kit/build-with-ai/) — Claude, Codex, Copilot CLI, Cursor setup flows - [Modular SSO guide](https://docs.scalekit.com/authenticate/sso/add-modular-sso/) — Implement enterprise SSO - [MCP Auth guide](https://docs.scalekit.com/authenticate/mcp/quickstart/) — Secure MCP servers diff --git a/plugins/agent-auth/README.md b/plugins/agent-auth/README.md index 47ccf84..785173f 100644 --- a/plugins/agent-auth/README.md +++ b/plugins/agent-auth/README.md @@ -25,6 +25,8 @@ claude /plugin install agent-auth@scalekit-auth-stack Start with the canonical docs entrypoint at [`docs/index.md`](docs/index.md). Official Scalekit docs: +- [LLM docs map](https://docs.scalekit.com/llms.txt) +- [Docs sitemap](https://docs.scalekit.com/sitemap-0.xml) - [AgentKit overview](https://docs.scalekit.com/agentkit/overview.md) - [AgentKit quickstart](https://docs.scalekit.com/agentkit/quickstart.md) - [AgentKit connectors](https://docs.scalekit.com/agentkit/connectors.md) diff --git a/plugins/agent-auth/docs/index.md b/plugins/agent-auth/docs/index.md index d584cbf..891c359 100644 --- a/plugins/agent-auth/docs/index.md +++ b/plugins/agent-auth/docs/index.md @@ -16,6 +16,8 @@ The Claude Code plugin still includes adapter/runtime files such as `.claude-plu These pages are the best external entrypoints for the material in this directory: +- [LLM docs map](https://docs.scalekit.com/llms.txt) +- [Docs sitemap](https://docs.scalekit.com/sitemap-0.xml) - [AgentKit overview](https://docs.scalekit.com/agentkit/overview.md) - [AgentKit quickstart](https://docs.scalekit.com/agentkit/quickstart.md) - [AgentKit connectors](https://docs.scalekit.com/agentkit/connectors.md) From 23e43b1dd3d2802a9d080cd15e2bbeae763341eb Mon Sep 17 00:00:00 2001 From: Saif Shines Date: Tue, 5 May 2026 21:51:54 +0530 Subject: [PATCH 5/5] docs: make testing skill the canonical playground Move the live AgentKit discovery and execution workflow into the testing skill so the plugin follows the modern skills-first structure. Keep `/test-tool` only as a legacy compatibility alias to preserve older usage without making `commands/` the source of truth. Co-authored-by: Cursor --- plugins/agent-auth/README.md | 14 +-- plugins/agent-auth/commands/test-tool.md | 87 +++------------ plugins/agent-auth/docs/code-samples.md | 2 +- plugins/agent-auth/docs/tool-discovery.md | 3 +- .../agent-auth/references/tool-discovery.md | 8 +- .../discovering-agentkit-tools/SKILL.md | 11 +- .../skills/testing-agentkit-tools/SKILL.md | 103 ++++++++++++++++-- 7 files changed, 132 insertions(+), 96 deletions(-) diff --git a/plugins/agent-auth/README.md b/plugins/agent-auth/README.md index 785173f..2509297 100644 --- a/plugins/agent-auth/README.md +++ b/plugins/agent-auth/README.md @@ -11,7 +11,7 @@ Canonical content lives in: Claude runtime files remain in place as adapters: - `.claude-plugin/` - `.mcp.json` -- `commands/` +- `commands/` for legacy slash-command aliases and compatibility shims - `hooks/` - `agents/` @@ -38,15 +38,15 @@ Official Scalekit docs: - `/agent-auth:discovering-agentkit-tools` Uses live AgentKit metadata to find tools, inspect schemas, and narrow the tool set. - `/agent-auth:testing-agentkit-tools` - Generates authorization links, fetches live tool metadata, and executes tools from Claude Code. + Generates authorization links, fetches live tool metadata, and executes tools from Claude Code. This is the preferred runnable playground surface. - `/agent-auth:building-agent-mcp-server` Exposes AgentKit tools through MCP for MCP-compatible runtimes. - `/agent-auth:production-readiness-scalekit` Runs a structured production-readiness checklist for AgentKit integrations. -Command: +Legacy command alias: - `/test-tool [generate-link|get-tool|execute-tool ...]` - Runs the live AgentKit playground command. + Compatibility wrapper for older usage. Prefer `/agent-auth:testing-agentkit-tools ...`. ## Configuration Required environment variables: @@ -80,9 +80,9 @@ Typical flow for a new connector integration: 1. Read [`docs/index.md`](docs/index.md) for the canonical model and [`docs/connections.md`](docs/connections.md) for connection naming. 2. Create the connection in `AgentKit -> Connections`. 3. Use `/agent-auth:integrating-agent-auth` to scaffold connected-account creation and authorization. -4. Use `/agent-auth:discovering-agentkit-tools` or `/test-tool get-tool --provider GMAIL` to inspect the live tool catalog and schema. -5. Use `/test-tool generate-link --connection-name --identifier user_123` if the user still needs to authorize. -6. Use `/test-tool execute-tool --tool-name gmail_fetch_mails --connection-name --identifier user_123 --tool-input '{"query":"is:unread","max_results":5}'` to validate the payload before wiring it into application code. +4. Use `/agent-auth:discovering-agentkit-tools` or `/agent-auth:testing-agentkit-tools get-tool --provider GMAIL` to inspect the live tool catalog and schema. +5. Use `/agent-auth:testing-agentkit-tools generate-link --connection-name --identifier user_123` if the user still needs to authorize. +6. Use `/agent-auth:testing-agentkit-tools execute-tool --tool-name gmail_fetch_mails --connection-name --identifier user_123 --tool-input '{"query":"is:unread","max_results":5}'` to validate the payload before wiring it into application code. ## Troubleshooting 1. No tools show up for a connector: diff --git a/plugins/agent-auth/commands/test-tool.md b/plugins/agent-auth/commands/test-tool.md index 638bc06..36bac22 100644 --- a/plugins/agent-auth/commands/test-tool.md +++ b/plugins/agent-auth/commands/test-tool.md @@ -1,91 +1,34 @@ --- -description: Test live AgentKit discovery and tool execution from Claude Code +description: Legacy compatibility alias for the AgentKit testing skill argument-hint: "[generate-link|get-tool|execute-tool] [args...]" allowed-tools: Bash --- -# AgentKit Tool Tester +# Legacy AgentKit Tool Tester -Test live AgentKit flows using the bundled Python playground script. +This command is a legacy compatibility alias for `/agent-auth:testing-agentkit-tools`. -**Arguments:** $ARGUMENTS - -## Operations - -### generate-link -Usage: `generate-link --connection-name --identifier ` - -Creates or fetches the connected account and prints an authorization link if the account is not yet `ACTIVE`. +Prefer invoking the skill directly: -### get-tool -Usage: `get-tool [--tool-name ] [--provider ] [--page-size ] [--page-token ]` - -Fetches live tool metadata and prints the raw JSON response. Omitting `--tool-name` returns all matching tools for the filter. - -### execute-tool -Usage: `execute-tool --tool-name --connection-name --identifier --tool-input ''` +```text +/agent-auth:testing-agentkit-tools $ARGUMENTS +``` -Creates or fetches the connected account, prints an authorization link if needed, and executes the tool. +**Arguments:** $ARGUMENTS ## Your task -Parse `$ARGUMENTS` to determine the operation, then run the bundled script from the plugin root: +Parse `$ARGUMENTS` exactly as the testing skill would and run the same bundled script from the plugin root: ```bash skills/testing-agentkit-tools/scripts/connect.py ``` -### Runner selection - -Check which runner is available by running `which uv` once before any Python command: - -- if `uv` exists, use `uv run python` -- otherwise use `python3` -- if `python3` is unavailable, fall back to `python` - -### Credentials - -Before running any operation, check for these environment variables: - -- `SCALEKIT_ENV_URL` -- `SCALEKIT_CLIENT_ID` -- `SCALEKIT_CLIENT_SECRET` - -Also accept legacy aliases: - -- `TOOL_ENV_URL` -- `TOOL_CLIENT_ID` -- `TOOL_CLIENT_SECRET` - -If none of the supported variables are available, ask the user for the missing values before proceeding. Do not write secrets into source-controlled files unless the user explicitly asks you to. - -### Commands to run - -If operation is `generate-link`, run: - -```bash - skills/testing-agentkit-tools/scripts/connect.py --generate-link --connection-name --identifier -``` - -If operation is `get-tool`, run: - -```bash - skills/testing-agentkit-tools/scripts/connect.py --get-tool [--tool-name ] [--provider ] [--page-size ] [--page-token ] -``` - -If operation is `execute-tool`, run: - -```bash - skills/testing-agentkit-tools/scripts/connect.py --execute-tool --tool-name --connection-name --identifier --tool-input '' -``` - -If `tool_input` is missing for `execute-tool`, inspect the live tool metadata first or ask the user for the missing input values. - -### After running +Keep this command behavior aligned with the skill: -Show: +- use `uv run python` when `uv` exists, otherwise `python3`, otherwise `python` +- accept both `SCALEKIT_*` and legacy `TOOL_*` credential variables +- inspect live metadata before guessing `tool_input` +- show the command output, exact command, resolved parameters, and exact payload for `execute-tool` -1. the command output -2. the exact command that was run -3. the resolved parameters in a small structured summary -4. for `execute-tool`, the exact JSON payload that was passed to AgentKit +Do not maintain separate workflow rules here. The testing skill is the source of truth. diff --git a/plugins/agent-auth/docs/code-samples.md b/plugins/agent-auth/docs/code-samples.md index 3379b77..c65d62a 100644 --- a/plugins/agent-auth/docs/code-samples.md +++ b/plugins/agent-auth/docs/code-samples.md @@ -8,7 +8,7 @@ Use it to choose an implementation style before opening a larger sample reposito | Goal | Recommended path | |---|---| -| Validate one tool quickly | Use `/test-tool` with `testing-agentkit-tools` | +| Validate one tool quickly | Use `/agent-auth:testing-agentkit-tools` | | Integrate AgentKit into app code | Use `integrating-agent-auth` | | Build an agent with a framework | Use framework-specific examples below | | Expose tools over MCP | Use `building-agent-mcp-server` | diff --git a/plugins/agent-auth/docs/tool-discovery.md b/plugins/agent-auth/docs/tool-discovery.md index 49643e5..97a4f09 100644 --- a/plugins/agent-auth/docs/tool-discovery.md +++ b/plugins/agent-auth/docs/tool-discovery.md @@ -61,7 +61,8 @@ Use: - `discovering-agentkit-tools` when the user needs current tools or schemas - `testing-agentkit-tools` when the user wants to run a live tool and inspect the exact payload -- `/test-tool get-tool ...` for the runnable playground flow +- `/agent-auth:testing-agentkit-tools get-tool ...` for the preferred runnable playground flow +- `/test-tool get-tool ...` only as a legacy compatibility alias ## Fallback rule diff --git a/plugins/agent-auth/references/tool-discovery.md b/plugins/agent-auth/references/tool-discovery.md index 9c472e6..872d5e5 100644 --- a/plugins/agent-auth/references/tool-discovery.md +++ b/plugins/agent-auth/references/tool-discovery.md @@ -46,13 +46,15 @@ If the metadata contains pagination or large result fields, mention them so the ## How to use this in Claude Code -For interactive discovery, use the live playground command: +For interactive discovery, prefer the testing skill: ```sh -/test-tool get-tool --provider GMAIL -/test-tool get-tool --tool-name gmail_fetch_mails +/agent-auth:testing-agentkit-tools get-tool --provider GMAIL +/agent-auth:testing-agentkit-tools get-tool --tool-name gmail_fetch_mails ``` +The legacy `/test-tool ...` alias still works for compatibility, but it is no longer the canonical path. + For implementation guidance, use: - `discovering-agentkit-tools` when the user needs the current tool list or schema diff --git a/plugins/agent-auth/skills/discovering-agentkit-tools/SKILL.md b/plugins/agent-auth/skills/discovering-agentkit-tools/SKILL.md index 3a29c71..7710348 100644 --- a/plugins/agent-auth/skills/discovering-agentkit-tools/SKILL.md +++ b/plugins/agent-auth/skills/discovering-agentkit-tools/SKILL.md @@ -22,16 +22,17 @@ Use this skill when the user asks: ## Discovery workflow 1. Identify the target connector or exact tool name. -2. Prefer live lookup through the built-in testing workflow or SDK metadata. -3. Summarize: +2. Prefer live lookup through `/agent-auth:testing-agentkit-tools get-tool --provider ` or `/agent-auth:testing-agentkit-tools get-tool --tool-name `. +3. If older docs or muscle memory mention `/test-tool`, treat it as a legacy compatibility alias for the testing skill rather than the canonical workflow. +4. Summarize: - tool name - connector - what the tool does - required fields from `input_schema.required` - optional fields from `input_schema.properties` - important fields from `output_schema.properties` -4. Recommend the smallest useful tool set for the workflow. -5. If live credentials are unavailable, use the connector notes only as a fallback and say they may be stale. +5. Recommend the smallest useful tool set for the workflow. +6. If live credentials are unavailable, use the connector notes only as a fallback and say they may be stale. ## Terminology @@ -46,11 +47,13 @@ Use `connector` in explanations. Only use `provider` when the SDK or API filter - `connection_name` is the exact dashboard value and may not equal the connector slug. - Tool metadata is the durable way to determine current inputs and outputs. +- The preferred runnable surface is the testing skill in `skills/testing-agentkit-tools/`, not the legacy `commands/` alias. - Restrict the tool set before handing it to an LLM. Fewer relevant tools improve tool selection and parameter filling. ## Deep reference - Canonical docs entrypoint: [../../docs/index.md](../../docs/index.md) - Live discovery model: [../../docs/tool-discovery.md](../../docs/tool-discovery.md) +- Runnable testing workflow: [../testing-agentkit-tools/SKILL.md](../testing-agentkit-tools/SKILL.md) - Curated connector notes: [../../docs/connectors/README.md](../../docs/connectors/README.md) - Broader implementation examples: [../../docs/code-samples.md](../../docs/code-samples.md) diff --git a/plugins/agent-auth/skills/testing-agentkit-tools/SKILL.md b/plugins/agent-auth/skills/testing-agentkit-tools/SKILL.md index e989cff..ea25ef2 100644 --- a/plugins/agent-auth/skills/testing-agentkit-tools/SKILL.md +++ b/plugins/agent-auth/skills/testing-agentkit-tools/SKILL.md @@ -1,11 +1,16 @@ --- name: testing-agentkit-tools description: Tests live Scalekit AgentKit flows from Claude Code by generating authorization links, fetching tool metadata, and executing a tool for a connected account. Use when a user wants to validate a connector, inspect the exact payload for `execute_tool`, or build a workflow step by step in the editor. +argument-hint: "[generate-link|get-tool|execute-tool] [args...]" +disable-model-invocation: true +allowed-tools: Bash --- # Testing AgentKit Tools -This skill is the live playground layer for AgentKit inside Claude Code. +This skill is the canonical live playground layer for AgentKit inside Claude Code. + +**Arguments:** $ARGUMENTS Use it to: @@ -26,14 +31,96 @@ Use it to: 4. Execute the tool with the smallest valid `tool_input`. 5. Show the exact command and payload used so the user can translate it into app code. -## Command surface +## Preferred invocation + +Invoke this skill directly for the runnable playground: + +- `/agent-auth:testing-agentkit-tools get-tool --provider GMAIL` +- `/agent-auth:testing-agentkit-tools get-tool --tool-name gmail_fetch_mails` +- `/agent-auth:testing-agentkit-tools generate-link --connection-name MY_GMAIL --identifier user_123` +- `/agent-auth:testing-agentkit-tools execute-tool --tool-name gmail_fetch_mails --connection-name MY_GMAIL --identifier user_123 --tool-input '{"query":"is:unread","max_results":5}'` + +`/test-tool` remains available only as a legacy compatibility alias. + +## Operations + +### generate-link +Usage: `generate-link --connection-name --identifier ` + +Creates or fetches the connected account and prints an authorization link if the account is not yet `ACTIVE`. + +### get-tool +Usage: `get-tool [--tool-name ] [--provider ] [--page-size ] [--page-token ]` + +Fetches live tool metadata and prints the raw JSON response. Omitting `--tool-name` returns all matching tools for the filter. + +### execute-tool +Usage: `execute-tool --tool-name --connection-name --identifier --tool-input ''` + +Creates or fetches the connected account, prints an authorization link if needed, and executes the tool. + +## Your task + +Parse `$ARGUMENTS` to determine the operation, then run the bundled script from this skill directory: + +```bash +${CLAUDE_SKILL_DIR}/scripts/connect.py +``` + +### Runner selection + +Check which runner is available by running `which uv` once before any Python command: + +- if `uv` exists, use `uv run python` +- otherwise use `python3` +- if `python3` is unavailable, fall back to `python` + +### Credentials + +Before running any operation, check for these environment variables: + +- `SCALEKIT_ENV_URL` +- `SCALEKIT_CLIENT_ID` +- `SCALEKIT_CLIENT_SECRET` + +Also accept legacy aliases: + +- `TOOL_ENV_URL` +- `TOOL_CLIENT_ID` +- `TOOL_CLIENT_SECRET` + +If none of the supported variables are available, ask the user for the missing values before proceeding. Do not write secrets into source-controlled files unless the user explicitly asks you to. + +### Commands to run + +If operation is `generate-link`, run: + +```bash + "${CLAUDE_SKILL_DIR}/scripts/connect.py" --generate-link --connection-name --identifier +``` + +If operation is `get-tool`, run: + +```bash + "${CLAUDE_SKILL_DIR}/scripts/connect.py" --get-tool [--tool-name ] [--provider ] [--page-size ] [--page-token ] +``` + +If operation is `execute-tool`, run: + +```bash + "${CLAUDE_SKILL_DIR}/scripts/connect.py" --execute-tool --tool-name --connection-name --identifier --tool-input '' +``` + +If `tool_input` is missing for `execute-tool`, inspect the live tool metadata first or ask the user for the missing input values. + +### After running -Use `/test-tool` for the runnable playground: +Show: -- `/test-tool get-tool --provider GMAIL` -- `/test-tool get-tool --tool-name gmail_fetch_mails` -- `/test-tool generate-link --connection-name MY_GMAIL --identifier user_123` -- `/test-tool execute-tool --tool-name gmail_fetch_mails --connection-name MY_GMAIL --identifier user_123 --tool-input '{"query":"is:unread","max_results":5}'` +1. the command output +2. the exact command that was run +3. the resolved parameters in a small structured summary +4. for `execute-tool`, the exact JSON payload that was passed to AgentKit ## Guardrails @@ -44,7 +131,7 @@ Use `/test-tool` for the runnable playground: ## Deep reference -- Playground command: [../../commands/test-tool.md](../../commands/test-tool.md) +- Legacy alias: [../../commands/test-tool.md](../../commands/test-tool.md) - Canonical docs entrypoint: [../../docs/index.md](../../docs/index.md) - Live discovery model: [../../docs/tool-discovery.md](../../docs/tool-discovery.md) - Integration workflow: [../agent-auth/SKILL.md](../agent-auth/SKILL.md)