RFC: Plugin Granularity and Organization for awslabs/agent-plugins

[krokoko]

Is this related to an existing feature request or issue?

No response

Summary

We want to agree on how plugins should be organized and their granularity. This will impact the design guidelines and criteria to approve new plugins in the repository.

Currently, the repository is positioned around a workflow-oriented interpretation of the Claude Code “plugin” concept: a marketplace catalog (.claude-plugin/marketplace.json) points to a plugin directory (plugins/deploy-on-aws) containing a plugin manifest (.claude-plugin/plugin.json), MCP server config (.mcp.json), and an intent-triggered skill with progressive-disclosure references (skills/deploy/...).

The existing deploy-on-aws skill encodes a deterministic five-stage workflow (Analyze → Recommend → Estimate → Generate → Deploy), and hard-bakes guardrails like “show cost before proceeding” and “deploy only with user confirmation,” illustrating the repository’s bias toward structured operational playbooks rather than “raw API wrappers.”

Given Claude Code’s packaging and distribution mechanics (plugins are copied into a local cache, cannot traverse outside their plugin root after install, and are enabled/disabled at plugin scope (not per-skill)), plugin boundaries function as the real-world boundary for discoverability, enterprise governance, dependency isolation, and (most importantly for AWS) credential/permission scoping.

Two Claude Code mechanics materially constrain repository organization choices:

• Caching & path isolation: Marketplace-installed plugins are copied into ~/.claude/plugins/cache; plugins cannot reliably reference ../ paths outside their root after installation, and shared code must be vendored or linked in (symlinks are explicitly supported as a workaround).
• Installation scopes as governance primitives: plugins can be installed in user, project, local, or managed scopes, affecting whether a plugin is personal, shared in-repo, gitignored, or centrally controlled.

Use case

How plugins are added/organized in the repository

The outcome of this RFC:

• Update to the design guidelines
• Automated tooling to enforce guidelines for contributions
• Updates to existing plugins to add any useful information as per findings of this RFC

Proposal

Adopt a Domain Workflow / Intent model as the main organizational strategy, where each plugin corresponds to a coherent “job-to-be-done” (deployment, identity management, storage governance, CI/CD), and each plugin contains multiple narrowly-scoped skills (single responsibility per skill) with explicit triggers and strong guardrails. This aligns with the repository’s current design guidance (“keep plugins focused,” “single responsibility per skill,” progressive disclosure) and the existing deploy-on-aws implementation style.

This leverages how Claude Code actually discovers and triggers skills: the description frontmatter drives auto-triggering, and the repository explicitly stresses determinism via concise, unambiguous instructions and progressive disclosure into reference files.

Why this should be the default for agent-plugins-for-aws

• It matches the repository’s “MVP” reality: deploy-on-aws is already a workflow plugin with curated defaults, a strong staged process, and built-in guardrails.
• It aligns with governance structure: plugin directories map cleanly to plugin teams and CODEOWNERS entries.
• It fits distribution constraints: each plugin can be self-contained (required by caching/path rules), bundling the references and scripts needed without fragile cross-plugin imports.
• It provides the cleanest path to least privilege: you can publish per-plugin IAM “role recipes,” and recommend role assumption / temporary credentials rather than broad persistent permissions.

Out of scope

Potential challenges

• Security and permission scoping risks for plugins
• Scope creep / god plugins: workflow oriented plugins naturally expand until they are huge, hard to review and hard to secure
• Ownership of plugins: who owns it when it combines multiple services together ?
• Discoverability and UX problems as plugin count grows: as the catalog grows, users won't know which plugin to install, and skills can overlap in intent causing confusion or inconsistent triggers
• Not all clients support the same features for plugins
• Governance, versioning and migration pitfalls for plugin evolution
• Operational and testing challenges for CI and IaC worfklows

Dependencies and Integrations

No response

Alternative solutions

Some complementary hybrid options:

• A Permission-Tiered Hybrid: domain workflow plugins split into read-only/inspect vs mutating/apply variants to better align with least-privilege and blast-radius boundaries.
• A Pattern + Capability Hybrid: “infrastructure pattern” plugins (e.g., static site, containerized web app) built on curated capability modules (documentation, cost estimation, IaC checks), implemented via vendoring or symlink-copy patterns compatible with Claude Code caching.

Other options:

• Service-centric model (per AWS service)
  A plugin corresponds to one AWS service family (e.g., “s3-tools”, “ec2-tools”, “iam-tools”). Each plugin bundles multiple skills for common tasks within that service.

Advantages: strong marketplace discoverability via familiar nouns (“S3”, “EC2”); naturally maps to AWS documentation families; can reuse per-service IAM action sets and the AWS Service Authorization Reference tables when authoring least-privilege guidance.

Limitations: encourages “god plugins” for large services; installation boundary becomes too permissive (enabling “ec2-tools” might implicitly need broad EC2 mutating permissions); cross-service workflows (deployments, CI/CD) still require composing many service plugins, which increases user friction and trigger ambiguity. This conflicts with the repository’s guidance to keep plugins cohesive and avoid bundling unrelated features.

• Resource-type model (per resource type)
  A plugin corresponds to a resource type (often aligning with CloudFormation resource families such as “bucket-governance” or “iam-role-management”), possibly spanning multiple services in edge cases.

Advantages: closer alignment to IAM resource scoping and policy reasoning: many policies are easiest to reason about at resource type granularity (bucket policies, roles, stacks); aligns with IaC patterns (CloudFormation or CDK) where resources are first-class.

Limitations: resource modeling is not always how users think about tasks (“set retention policy for logs” spans multiple resource types); some “resources” are multi-service composites; still risks skill overlap and ambiguous triggers across plugins.

• Workflow model (per high-level workflow)
  A plugin corresponds to an end-to-end workflow (e.g., “deploy-on-aws”, “lambda-cicd”, “incident-response”), bundling all skills/MCP/hook artifacts needed to complete that workflow reliably. This matches the existing deploy-on-aws plugin approach and what this RFC recommends.

Advantages: matches the existing deploy-on-aws pattern, which demonstrates that the repo is already optimized for deterministic, step-by-step playbooks (analyze → recommend → estimate → generate → deploy) with embedded guardrails. Workflow plugins are also the most natural unit for:

• Least privilege alignment: you can define a narrowly scoped “deployment role” or “pipeline role” to match the workflow boundary (and still advise temporary credentials and conditions).
• User outcomes: developers install what they want to accomplish, not what service they want to call.
• Governance/ownership: aligns well with repo governance mechanisms (per-plugin teams and CODEOWNERS for plugin directories).

Limitations: workflows can still become too broad if not curated; overlapping workflows can cause trigger collisions unless frontmatter descriptions are carefully differentiated (the repo explicitly notes that skill triggering relies heavily on the description field).

• Capability/intent model (per capability / user intent)
  A plugin corresponds to a reusable capability expressed as intent categories (e.g., “storage-governance”, “identity-access”, “cost-estimation”, “iac-validation”). Skills are smaller and more composable; the plugin boundary is chosen so that enabling the plugin roughly equals granting a capability class.

Advantages: maximizes composability (orthogonal capability modules) and can cleanly separate “inspect” vs “apply” layers. Skill triggers can remain very precise because each plugin focuses on a narrower intent slice; this is consistent with “single responsibility per skill” and “keep plugins focused.”

Limitations: requires strong taxonomy governance (naming/tags/categories) or it becomes less discoverable; users may not know which intent plugin to install. It also increases pressure on dependency sharing (common templates/policy snippets), which is constrained by Claude Code’s caching/path rules.

• Operation-level model (per API / operation)
  A plugin (or skill-as-plugin) corresponds to a single operation (e.g., “put-bucket-lifecycle”, “run-instances”, “create-role”). Extremely granular; intended to maximize least privilege but usually harmful to UX.

Advantages: best theoretical fit for least privilege (each plugin/skill can be mapped to a minimal action set), and easiest to test in isolation.

Limitations: catastrophically poor UX and governance overhead: plugin explosion, poor discoverability, constant trigger collisions, and massive maintenance cost. It violates the repo’s design guidance to avoid proliferation of monolithic or redundant artifacts, just inverted (too small rather than too big).

• Infrastructure-pattern model (per architecture pattern)
  A plugin corresponds to an architectural pattern (static website, containerized web app with DB, event-driven pipeline). This resembles “solution templates” and is often expressed as IaC generation plus operational guidance. It overlaps with workflow plugins but anchors on architecture patterns rather than tasks.

Advantages: matches how many teams think about deployments (“static site,” “web app with DB,” “event-driven”) and can bundle best practices, defaults, IaC, and checks in a single installable artifact—similar to deploy-on-aws defaults.

Limitations: patterns often imply broad multi-service permissions, which may conflict with least privilege goals unless paired with explicit plan/apply separation and strong confirmation gates (e.g., CloudFormation change sets).

[mojodna]

I see this a bit differently. My mental model for skills is the Waffle House training binder.

Waffle House doesn't train cooks with a binder section called "Serve Breakfast." The binder has a section for each station: eggs, hashbrowns, waffle iron, grill. Each section teaches what the equipment is, what it's for, and worked examples for common preparations. A cook reads the order and composes knowledge from the relevant sections at runtime.

Waffle House also has a plate-marking system. Servers don't write tickets — they place condiment packets on the plate in specific positions to encode orders. A jelly packet vertical at the bottom means scrambled eggs. Turn it horizontal at the top: ham omelet. Mustard underneath: add an extra egg. Multiple markers compose on a single plate, each pointing at a different station and configuration. The cook glances at the marked plate, identifies which stations are involved, then draws on their training to execute. The markers never re-teach how to cook an omelet. They reference that knowledge.

I think plugins provide two kinds of knowledge, and conflating them produces the tensions this RFC identifies:

1. What it is. Station knowledge. The binder's hashbrown section teaches the equipment, the technique, and that hashbrowns come from this station — not the grill. A CloudWatch Logs Insights plugin teaches the query language, API surface, operational characteristics, and when Logs Insights is the right tool versus CloudWatch Metrics. An S3 plugin teaches bucket operations, lifecycle rules, access patterns, and when S3 is the right storage primitive over alternatives. Station knowledge covers the primitive and its boundaries — when a customer's order involves this station and when it doesn't. This supplements the agent's training data with current, precise, opinionated reference material.

2. How to combine them. The plate-marking system. An observability debugging workflow says: check logs (CloudWatch Logs Insights), correlate with traces (X-Ray), examine metrics for anomalies (CloudWatch Metrics). It names the stations and their sequencing for a given job. The agent resolves those references at runtime by pulling from the relevant service plugins. The workflow doesn't duplicate how to write a Logs Insights query — it says "query the logs" and trusts the agent to know how.

The compression is the feature. The plate-marking system is food Braille — an extremely low-bandwidth encoding that produces rich, correct results because the cook's station training provides all the depth. A jelly packet's position encodes a few bits of information but produces a correctly cooked omelet. "Debug the latency spike in the order service" is a plate marking: one sentence that points at stations and a configuration. The agent produces a rich response because the service plugins supply the depth. Without station knowledge loaded, the same prompt requires paragraphs of elaboration, re-teaching the stations inline every time.

The RFC proposes each plugin correspond to a job-to-be-done, bundling all knowledge needed to complete that job. That's a binder with one section called "Serve Breakfast" containing re-transcribed egg procedures, hashbrown procedures, and grill procedures. It works for exactly one meal. When lunch service starts and some of the same stations appear in different combinations, you either duplicate the knowledge, write a second monolithic section, or attempt to actively cross-reference information (something that LLMs are very good at!).

Separating station knowledge from workflow knowledge avoids this. Service plugins are durable reference material that multiple workflows compose against (and that might contain some core workflows directly). Workflow plugins are lightweight orchestration layers — plate-marking systems — that name which stations are involved and in what configuration. The agent does the actual composition at runtime, the same way a cook reads a marked plate and draws on training rather than following a single script per menu item.
Plugins declare recommendations for complementary plugins. A workflow plugin lists the service plugins it references. If the agent encounters a workflow instruction pointing at a station it doesn't have loaded, it surfaces the recommendation: "This workflow references CloudWatch Logs Insights — install the CloudWatch Logs Insights plugin for full capability." Hard dependencies become soft discovery. The composition graph is visible without being rigid.

Two examples:

An aws-geospatial plugin consolidates Amazon Location Service, PostGIS on Aurora/RDS, Redshift spatial queries, and SageMaker geospatial capabilities. This is station knowledge: what each service's spatial capabilities are, their boundaries, and when to reach for each one over alternatives. Under a workflow model, this knowledge either scatters across "build-a-fleet-tracker" and "analyze-spatial-data" plugins or skills (duplicating station knowledge) or produces a god plugin that tries to be every geospatial workflow at once. As a cross-service plugin, it carries station knowledge for the geospatial domain. Workflow plugins that involve geospatial work reference this knowledge without duplicating it or requiring explicit cross-references that require curation.

A serverless web application pattern (from the Well-Architected Framework) composes S3, CloudFront, API Gateway, Lambda, DynamoDB, and Cognito. Six service plugins each teach their station: S3 bucket configuration, Lambda function packaging, DynamoDB table design. A "serverless-web-app" pattern plugin is the plate-marking system: it says this architecture needs S3 for static assets, CloudFront in front of it, API Gateway routing to Lambda, Lambda reading/writing DynamoDB, Cognito gating API Gateway. It names the stations and their configuration for this particular architecture. It doesn't re-teach S3 bucket policies. When the team swaps Cognito for a third-party auth provider, one service plugin changes. The pattern plugin updates one reference. Lambda and DynamoDB knowledge stays untouched.

Because station knowledge is independent of any workflow, new workflows compose against it in contexts the original authors never anticipated — the way Waffle House's storm playbook activates different menus by narrowing which stations operate, not by rewriting station procedures.

Ownership follows expertise, and expertise differs by plugin type. Service teams or aligned SAs own service plugins because they know what the primitive is and what it's for. Cross-cutting communities — TFCs, SAs, partners — own pattern and theme plugins because they understand how primitives compose at the boundaries. The geospatial plugin belongs to geospatial practitioners who work across Amazon Location, PostGIS, and Redshift daily, not to any single service team. The serverless web app pattern belongs to people who understand how those six services compose into a coherent architecture. This maps to CODEOWNERS cleanly; it maps to different groups for different plugin types rather than assuming one ownership model fits all.