From 8552ebce6a85480dfd8df7685efa4f2ce0daabe8 Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Fri, 27 Feb 2026 20:12:18 +0000 Subject: [PATCH 1/2] feat(agent-loading): add dynamic plugin discovery and loading plugin MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New plugin that acts as a smart router for the marketplace — discovers available plugins, matches user intent against the catalog, and automatically installs/activates the right plugin on demand. Includes GitHub MCP integration for issue search/creation when no plugin matches. Co-Authored-By: Claude --- .claude-plugin/marketplace.json | 18 ++ .../agent-loading/.claude-plugin/plugin.json | 21 ++ plugins/agent-loading/.mcp.json | 12 + plugins/agent-loading/README.md | 225 ++++++++++++++++++ .../agent-loading/commands/browse-plugins.md | 20 ++ .../skills/agent-loading/SKILL.md | 113 +++++++++ .../agent-loading/references/contributing.md | 80 +++++++ .../references/install-commands.md | 51 ++++ .../references/matching-logic.md | 57 +++++ 9 files changed, 597 insertions(+) create mode 100644 plugins/agent-loading/.claude-plugin/plugin.json create mode 100644 plugins/agent-loading/.mcp.json create mode 100644 plugins/agent-loading/README.md create mode 100644 plugins/agent-loading/commands/browse-plugins.md create mode 100644 plugins/agent-loading/skills/agent-loading/SKILL.md create mode 100644 plugins/agent-loading/skills/agent-loading/references/contributing.md create mode 100644 plugins/agent-loading/skills/agent-loading/references/install-commands.md create mode 100644 plugins/agent-loading/skills/agent-loading/references/matching-logic.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 82cd106..a15d881 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -47,6 +47,24 @@ "source": "./plugins/amazon-location-service", "tags": ["aws", "location", "maps", "geospatial"], "version": "1.0.0" + }, + { + "category": "discovery", + "description": "Dynamically discover, recommend, and load plugins from the marketplace based on user intent. Routes requests to the right plugin automatically.", + "keywords": [ + "plugin", + "discovery", + "loader", + "marketplace", + "routing", + "install", + "catalog", + "recommend" + ], + "name": "agent-loading", + "source": "./plugins/agent-loading", + "tags": ["aws", "plugin", "discovery", "marketplace"], + "version": "0.1.0" } ] } diff --git a/plugins/agent-loading/.claude-plugin/plugin.json b/plugins/agent-loading/.claude-plugin/plugin.json new file mode 100644 index 0000000..04ae117 --- /dev/null +++ b/plugins/agent-loading/.claude-plugin/plugin.json @@ -0,0 +1,21 @@ +{ + "author": { + "name": "Amazon Web Services" + }, + "description": "Dynamically discover, recommend, and load plugins from the marketplace based on user intent. Routes requests to the right plugin automatically.", + "homepage": "https://github.com/awslabs/agent-plugins", + "keywords": [ + "aws", + "plugin", + "marketplace", + "discovery", + "loader", + "routing", + "install", + "catalog" + ], + "license": "Apache-2.0", + "name": "agent-loading", + "repository": "https://github.com/awslabs/agent-plugins", + "version": "0.1.0" +} diff --git a/plugins/agent-loading/.mcp.json b/plugins/agent-loading/.mcp.json new file mode 100644 index 0000000..4300ea2 --- /dev/null +++ b/plugins/agent-loading/.mcp.json @@ -0,0 +1,12 @@ +{ + "mcpServers": { + "github": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}" + } + } + } +} diff --git a/plugins/agent-loading/README.md b/plugins/agent-loading/README.md new file mode 100644 index 0000000..bc6d900 --- /dev/null +++ b/plugins/agent-loading/README.md @@ -0,0 +1,225 @@ +# Agent Loading + +Dynamically discover, recommend, and load plugins from the [Agent Plugins for AWS](https://github.com/awslabs/agent-plugins) marketplace based on user intent. + +## Overview + +The **agent-loading** plugin acts as a smart router for the plugin marketplace. Instead of requiring users to know which plugin to install, it automatically matches their intent to the best available plugin, installs it if needed, and hands off execution. + +### The Problem + +Users have a task ("deploy my app to AWS", "add a map to my site") but don't know which plugin handles it. They'd need to browse the catalog, read descriptions, and manually install — friction that slows adoption. + +### The Solution + +Agent-loading intercepts broad user intent, scores it against the full plugin catalog, and either activates an already-installed plugin or installs the right one on the fly. + +## How It Works + +### Agent Perspective + +``` +User says: "I want to host my Flask app on AWS" + ↓ +agent-loading skill auto-triggers (matches "host", "AWS") + ↓ +Reads marketplace.json → scores plugins by keyword/description/tag match + ↓ +Best match: deploy-on-aws (score: 9 — "aws", "deploy", "host" all match) + ↓ +Check: is deploy-on-aws installed? + ├─ YES → "Using the deploy-on-aws plugin." → proceed + └─ NO → /plugin install deploy-on-aws@agent-plugins-for-aws → proceed +``` + +### User Perspective + +#### Scenario 1: Plugin exists and is installed + +> User: "Add a map with geocoding to my React app" +> +> Agent: "Using the **amazon-location-service** plugin. It handles maps, geocoding, routing, and geospatial features with Amazon Location Service." +> +> _(proceeds with location service skill)_ + +#### Scenario 2: Plugin exists but not installed + +> User: "Deploy this to AWS" +> +> Agent: "The **deploy-on-aws** plugin handles AWS deployment with architecture recommendations, cost estimates, and IaC generation. Installing it now..." +> +> _(installs plugin, then proceeds with deploy skill)_ + +#### Scenario 3: No matching plugin + +> User: "Set up monitoring for my application" +> +> Agent: "No plugin currently matches this request. Here's the full catalog:" +> +> | Plugin | Description | Tags | +> | ----------------------- | ----------------------------- | --------------------------- | +> | deploy-on-aws | Deploy applications to AWS... | aws, deploy, infrastructure | +> | amazon-location-service | Maps, geocoding, routing... | aws, location, maps | +> +> "You can request this capability by opening an issue at https://github.com/awslabs/agent-plugins/issues, or contribute a plugin yourself." + +#### Scenario 4: Browsing the catalog + +> User: "/agent-loading:browse-plugins" +> +> Agent: _(displays full catalog table with installation status)_ + +## Components + +### Skill: agent-loading + +The core auto-triggering skill. Activates when the user asks about available plugins, needs help choosing which plugin to use, or has a request that doesn't clearly match any installed plugin. + +**Auto-triggers on:** "what plugins are available", "find a plugin", "browse plugins", "which plugin should I use", "install a plugin", "recommend a plugin", "plugin catalog". + +**Workflow:** + +1. Parse user intent (action, technologies, domain keywords) +2. Load marketplace registry +3. Score plugins against intent using keyword/description/tag matching +4. Check installation status +5. Install if needed, or use existing +6. Hand off to the matched plugin's skill +7. If no match: show catalog, suggest issue, suggest contributing + +### Command: browse-plugins + +User-invocable slash command (`/agent-loading:browse-plugins`) to explicitly browse the full marketplace catalog without a specific intent. + +Displays a table of all plugins with descriptions, tags, and installation status. + +### MCP Server: GitHub + +Integrates the official [GitHub MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/github) for: + +- **Issue search** — find existing feature requests before creating duplicates +- **Issue creation** — file new plugin requests (with user confirmation) +- **File fetching** — retrieve the latest marketplace.json from the repository + +## Installation + +### Prerequisites + +1. Add the marketplace (one-time): + + ``` + /plugin marketplace add awslabs/agent-plugins + ``` + +2. Set a GitHub personal access token (for GitHub MCP features): + + ```bash + export GITHUB_PERSONAL_ACCESS_TOKEN= + ``` + + The token needs `repo` scope for issue search and creation. GitHub MCP features are optional — the plugin works without them using the local registry only. + +### Install + +``` +/plugin install agent-loading@agent-plugins-for-aws +``` + +### Test Locally + +```bash +claude --plugin-dir ./plugins/agent-loading +``` + +## Configuration + +No additional configuration required. The plugin reads the marketplace registry that was added via `/plugin marketplace add`. + +### Optional: GitHub MCP + +Set `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable to enable: + +- Searching existing GitHub issues before suggesting new ones +- Creating feature request issues on behalf of the user +- Fetching the latest marketplace registry from GitHub + +Without this token, the plugin falls back to the local marketplace registry and skips issue-related features. + +## Plugin Catalog + +The plugin routes to all plugins registered in the `agent-plugins-for-aws` marketplace: + +| Plugin | Category | Description | +| ----------------------- | ---------- | ------------------------------------------------------------------------------------- | +| deploy-on-aws | deployment | Deploy applications to AWS with architecture recommendations, cost estimates, and IaC | +| amazon-location-service | location | Maps, geocoding, routing, and geospatial features with Amazon Location Service | + +As new plugins are added to the marketplace, agent-loading automatically discovers and routes to them — no updates to this plugin are needed. + +## Architecture + +``` +plugins/agent-loading/ +├── .claude-plugin/ +│ └── plugin.json # Plugin manifest +├── .mcp.json # GitHub MCP server configuration +├── commands/ +│ └── browse-plugins.md # /browse-plugins slash command +├── skills/ +│ └── agent-loading/ +│ ├── SKILL.md # Core routing skill (auto-triggers) +│ └── references/ +│ ├── matching-logic.md # Intent scoring algorithm +│ ├── install-commands.md # Plugin install reference +│ └── contributing.md # Issue/contribution guidance +└── README.md # This file +``` + +## Examples + +### Trigger Phrases + +The skill auto-triggers on a wide range of user intents: + +- "Deploy my app to AWS" +- "Host this on AWS" +- "Add a map to my application" +- "I need geocoding for addresses" +- "What plugins are available?" +- "Find a plugin for..." +- "Estimate AWS costs" +- "Set up CDK infrastructure" +- "Add location features" +- "Route between two points" + +### Testing the Skill + +```bash +# Test with deploy intent +claude --plugin-dir ./plugins/agent-loading +> "Deploy my Flask app to AWS" +# Expected: matches deploy-on-aws, installs if needed, proceeds + +# Test with location intent +> "Add a map with places search" +# Expected: matches amazon-location-service + +# Test with no match +> "Set up a CI/CD pipeline" +# Expected: no match, shows catalog, suggests issue + +# Test browse command +> /agent-loading:browse-plugins +# Expected: full catalog table +``` + +## Contributing + +To add a new plugin that agent-loading can route to: + +1. Create the plugin in `plugins/{plugin-name}/` +2. Add it to `.claude-plugin/marketplace.json` +3. Include descriptive `keywords` and `tags` for accurate matching +4. Submit a pull request + +See [DESIGN_GUIDELINES.md](../../docs/DESIGN_GUIDELINES.md) and [DEVELOPMENT_GUIDE.md](../../docs/DEVELOPMENT_GUIDE.md) for detailed guidance. diff --git a/plugins/agent-loading/commands/browse-plugins.md b/plugins/agent-loading/commands/browse-plugins.md new file mode 100644 index 0000000..e932d7b --- /dev/null +++ b/plugins/agent-loading/commands/browse-plugins.md @@ -0,0 +1,20 @@ +--- +name: browse-plugins +description: "Browse the full Agent Plugins for AWS marketplace catalog. Lists all available plugins with descriptions, keywords, and installation status." +allowed-tools: "Read Bash" +--- + +# Browse Plugins + +Display the full plugin catalog from the Agent Plugins for AWS marketplace. + +## Instructions + +1. Read the marketplace registry at `.claude-plugin/marketplace.json` in the marketplace root +1. For each plugin in the registry, present a summary table with columns: Plugin, Description, Tags, Installed? +1. Check `.claude/settings.json` in the current project for `enabledPlugins` to determine installation status +1. Mark each plugin as "Installed" or "Not installed" +1. After displaying the table, inform the user: + - To install a plugin: `/plugin install {name}@agent-plugins-for-aws` + - To request a new plugin: open an issue at `https://github.com/awslabs/agent-plugins/issues` + - To contribute a plugin: see `https://github.com/awslabs/agent-plugins` contributing guide diff --git a/plugins/agent-loading/skills/agent-loading/SKILL.md b/plugins/agent-loading/skills/agent-loading/SKILL.md new file mode 100644 index 0000000..d991431 --- /dev/null +++ b/plugins/agent-loading/skills/agent-loading/SKILL.md @@ -0,0 +1,113 @@ +--- +name: agent-loading +description: "This skill should be used when the user asks about available plugins, wants to find or browse the plugin catalog, needs help choosing which plugin to use, or has a request that does not clearly match any installed plugin. Triggers on phrases like: what plugins are available, find a plugin, browse plugins, use a plugin, install a plugin, which plugin should I use, plugin marketplace, plugin catalog, recommend a plugin, list plugins." +--- + +# Agent Loading + +Dynamically discover and load plugins from the Agent Plugins for AWS marketplace based on user intent. Act as a router: match what the user needs to the best available plugin, then install or activate it. + +## Marketplace Source + +The canonical marketplace registry is the `awslabs/agent-plugins` GitHub repository: + +- **Repository**: `https://github.com/awslabs/agent-plugins` +- **Registry file**: `.claude-plugin/marketplace.json` +- **Marketplace name**: `agent-plugins-for-aws` + +## Workflow + +### Step 1: Identify User Intent + +Parse the user's request to extract: + +- Primary action (deploy, add maps, estimate cost, etc.) +- Technologies mentioned (AWS, CDK, MapLibre, etc.) +- Domain keywords (infrastructure, geospatial, location, etc.) + +### Step 2: Load Marketplace Registry + +Read the marketplace registry to get the current plugin catalog. The registry is at `.claude-plugin/marketplace.json` in the marketplace root. + +For each plugin entry, extract: + +- `name` — plugin identifier +- `description` — what the plugin does +- `keywords` — searchable terms +- `tags` — category labels +- `source` — plugin location + +See [matching-logic.md](references/matching-logic.md) for detailed intent-to-plugin matching rules. + +### Step 3: Match Intent to Plugin + +Compare user intent against each plugin's description, keywords, and tags. Rank matches by relevance. Select the best match or present ranked options if multiple plugins apply. + +REQUIRED: Explain the match rationale in one sentence. Example: "The `deploy-on-aws` plugin matches because it handles AWS deployment with architecture recommendations and IaC generation." + +### Step 4: Check Installation Status + +Determine whether the matched plugin is already installed: + +- If installed → proceed directly, inform user: "Using the **{plugin-name}** plugin." +- If not installed → proceed to Step 5 + +### Step 5: Install and Activate + +If the plugin is not installed, install it automatically. See [install-commands.md](references/install-commands.md) for the install command reference. + +After installation, confirm activation and proceed with the user's original request. + +### Step 6: Handle No Match + +If no plugin matches the user's intent: + +1. Inform the user: "No plugin currently matches this request." +2. Present the full plugin catalog as a table for browsing (name, description, tags). +3. Suggest filing a feature request: "Consider opening a GitHub issue at https://github.com/awslabs/agent-plugins/issues to request this capability." +4. Suggest contributing: "Alternatively, contributions are welcome — see the repository's contributing guide for how to create a new plugin." + +Use the GitHub MCP server to search existing issues before suggesting a new one. If a similar issue exists, link to it instead. + +## GitHub MCP Integration + +The bundled GitHub MCP server enables: + +- **Search issues** — check for existing feature requests before suggesting duplicates +- **Create issues** — file new plugin requests on behalf of the user (with confirmation) +- **Fetch files** — retrieve the latest `marketplace.json` from the repository + +REQUIRED: Always confirm with the user before creating a GitHub issue. + +## Defaults + +- Default marketplace: `agent-plugins-for-aws` +- Default source repository: `https://github.com/awslabs/agent-plugins` +- REQUIRED: When multiple plugins match, present a ranked list and let the user choose +- When a single plugin clearly matches, install and activate it automatically +- REQUIRED: When no installed plugin matches but a marketplace plugin does, install it before proceeding + +## Error Scenarios + +### Marketplace Registry Not Found + +- Inform user: "Marketplace registry not found. The marketplace may not be added yet." +- Suggest: "Run `/plugin marketplace add awslabs/agent-plugins` to add the marketplace." + +### Plugin Installation Fails + +- Report the error to the user +- Suggest manual installation: "Try `/plugin install {plugin-name}@{marketplace-name}` manually." +- Check if a newer version is available on GitHub + +### GitHub MCP Unavailable + +- Continue without GitHub features (issue search/creation, remote registry fetch) +- Inform user: "GitHub integration unavailable. Issue search and creation are disabled." +- Fall back to local marketplace registry only + +## References + +- [Intent matching logic](references/matching-logic.md) +- [Install command reference](references/install-commands.md) +- [Contributing and issue guidance](references/contributing.md) diff --git a/plugins/agent-loading/skills/agent-loading/references/contributing.md b/plugins/agent-loading/skills/agent-loading/references/contributing.md new file mode 100644 index 0000000..f83663d --- /dev/null +++ b/plugins/agent-loading/skills/agent-loading/references/contributing.md @@ -0,0 +1,80 @@ +# Contributing and Issue Guidance + +## Filing a Feature Request + +When no plugin matches the user's intent, suggest filing a GitHub issue. + +### Before Creating an Issue + +REQUIRED: Search existing issues first using the GitHub MCP server. + +Search query: the user's intent keywords + "plugin" in the `awslabs/agent-plugins` repository. + +If a matching issue exists: + +- Link to the existing issue +- Suggest the user add a thumbs-up reaction to signal demand +- Do NOT create a duplicate + +### Issue Template + +If no existing issue matches, create a new one (with user confirmation): + +**Title**: `Plugin request: {brief description of capability}` + +**Body**: + +```markdown +## Requested Capability + +{Description of what the user wants to do} + +## Use Case + +{Why this plugin would be valuable} + +## Suggested Keywords + +{Keywords that would trigger this plugin} + +--- + +Filed via the agent-loading plugin. +``` + +**Labels**: `enhancement`, `plugin-request` + +### Repository Link + +Direct users to: `https://github.com/awslabs/agent-plugins/issues` + +## Contributing a New Plugin + +For users interested in building the plugin themselves: + +1. Fork the repository: `https://github.com/awslabs/agent-plugins` +2. Follow the development guide: `docs/DEVELOPMENT_GUIDE.md` +3. Review design guidelines: `docs/DESIGN_GUIDELINES.md` +4. Use existing plugins as templates (`deploy-on-aws`, `amazon-location-service`) +5. Submit a pull request + +### Plugin Structure Quick Reference + +``` +plugins/{plugin-name}/ +├── .claude-plugin/ +│ └── plugin.json +├── .mcp.json # If MCP servers needed +└── skills/ + └── {skill-name}/ + ├── SKILL.md + └── references/ +``` + +### Quality Requirements + +- `mise run build` must pass +- Plugin manifest validates against schema +- Skill descriptions include specific trigger phrases +- SKILL.md under 300 lines +- Reference files under 100 lines each diff --git a/plugins/agent-loading/skills/agent-loading/references/install-commands.md b/plugins/agent-loading/skills/agent-loading/references/install-commands.md new file mode 100644 index 0000000..d66687b --- /dev/null +++ b/plugins/agent-loading/skills/agent-loading/references/install-commands.md @@ -0,0 +1,51 @@ +# Plugin Install Command Reference + +## Prerequisites + +The marketplace must be added before plugins can be installed: + +``` +/plugin marketplace add awslabs/agent-plugins +``` + +## Install a Plugin + +``` +/plugin install {plugin-name}@{marketplace-name} +``` + +### Examples + +``` +/plugin install deploy-on-aws@agent-plugins-for-aws +/plugin install amazon-location-service@agent-plugins-for-aws +/plugin install agent-loading@agent-plugins-for-aws +``` + +## Check Installed Plugins + +To verify which plugins are currently installed and enabled, check the project's `.claude/settings.json` file for the `enabledPlugins` array. + +## Test a Plugin Locally + +For development or testing without marketplace installation: + +```bash +claude --plugin-dir ./plugins/{plugin-name} +``` + +## Troubleshooting + +### "Marketplace not found" + +Run: `/plugin marketplace add awslabs/agent-plugins` + +### "Plugin not found in marketplace" + +- Verify the plugin name matches exactly (kebab-case) +- Check that the marketplace registry includes the plugin +- The marketplace may need updating — fetch latest from GitHub + +### "Plugin already installed" + +The plugin is ready to use. No action needed — proceed with the user's request. diff --git a/plugins/agent-loading/skills/agent-loading/references/matching-logic.md b/plugins/agent-loading/skills/agent-loading/references/matching-logic.md new file mode 100644 index 0000000..7310b30 --- /dev/null +++ b/plugins/agent-loading/skills/agent-loading/references/matching-logic.md @@ -0,0 +1,57 @@ +# Intent-to-Plugin Matching Logic + +## Matching Strategy + +Match user intent against the plugin catalog using a weighted scoring approach. + +### Signal Sources (by priority) + +1. **Keywords match** (highest weight) — direct match between user terms and plugin `keywords` array +2. **Description match** — semantic overlap between user request and plugin `description` +3. **Tags match** — match against plugin `tags` for broad category alignment +4. **Name match** (lowest weight) — plugin name appears in user request + +### Scoring Rules + +- Exact keyword match: +3 points per keyword +- Description term overlap: +2 points per meaningful term +- Tag match: +1 point per tag +- Name match: +1 point + +Select the plugin with the highest score. If the top two scores are within 2 points of each other, present both as options. + +## Current Plugin Catalog + +NOTE: This is a reference snapshot. Always read `marketplace.json` as the source of truth — the catalog below may be outdated as new plugins are added. + +### deploy-on-aws + +| Field | Values | +| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| Keywords | aws, aws agent skills, amazon, deploy, cdk, cloudformation, infrastructure, pricing | +| Tags | aws, deploy, infrastructure, cdk | +| Triggers | "deploy to AWS", "host on AWS", "run this on AWS", "AWS architecture", "estimate AWS cost", "generate infrastructure", "CDK", "CloudFormation" | + +### amazon-location-service + +| Field | Values | +| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| Keywords | location, maps, geocoding, routing, places, geofencing, tracking, amazon-location, maplibre, address, coordinates | +| Tags | aws, location, maps, geospatial | +| Triggers | "add a map", "geocoding", "routing", "places search", "geofencing", "tracking", "MapLibre", "location service", "address lookup", "coordinates" | + +## Ambiguity Resolution + +When intent is ambiguous: + +- Present top matches as a numbered list with one-sentence rationale each +- Ask user to select: "Which plugin best fits your needs?" +- Do NOT auto-install when ambiguous + +## No-Match Indicators + +A request likely has no match when: + +- No plugin scores above 2 points +- User mentions technologies/services not in any plugin's keywords +- Request is outside the AWS ecosystem entirely From ec270fffec4338d52d492cbccb276ce2776e27c3 Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Fri, 27 Feb 2026 22:31:18 +0000 Subject: [PATCH 2/2] chore: add attribution.commit to project settings Standardize the Co-Authored-By format for all contributors to use "Claude " without exposing the model name. Co-Authored-By: Claude --- .claude/settings.json | 1 + 1 file changed, 1 insertion(+) diff --git a/.claude/settings.json b/.claude/settings.json index eaa3835..a3f4bf3 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -3,6 +3,7 @@ "allow": [] }, "attribution": { + "commit": "Co-Authored-By: Claude ", "pr": "🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\n---\n\nBy submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the [project license](https://github.com/awslabs/agent-plugins/blob/main/LICENSE)." }, "enabledPlugins": {