E01_The_Plugin_Surface

The Plugin Surface

The toolkit is four plugins. It is also 107 skills. Those two numbers are not the same kind of thing — and confusing them is the single most common mistake readers make on first contact.

Key Takeaways

• The repository ships four installable plugins and 107 SKILL.md files — those are different kinds of artifact. Plugins are packaging; skills are the work.
• Every plugin ships three manifest files (Claude Code, Codex, Cursor) plus a fourth marketplace shape under .agents/, because the four agent hosts have not converged on a single schema.
• The 107 skills split into 14 core-skills + 50 specialized-skills at the top level, plus 15+7+8+13 bundled inside the four plugins — duplicated deliberately, not by accident.
• The validator at tools/validate.py enforces kebab-case skill names, directory-name matching, description length, and JSON manifest schema; every CI run gates on it.
• The plugin boundaries map to four kinds of work: operate (aws-core), build agents (aws-agents), analyze data (aws-data-analytics), investigate incidents (aws-agents-for-devsecops) — pick by primary use case.

There are 107 SKILL.md files in the aws/agent-toolkit-for-aws repository. I counted them: 14 in skills/core-skills/, 50 in skills/specialized-skills/ spread across 10 service categories, 15 inside the aws-core plugin, 7 inside aws-agents, 8 inside aws-data-analytics, and 13 inside aws-agents-for-devsecops. I also counted something the README does not advertise: there are exactly four installable plugins. The ratio of skills to plugins is roughly 27 to 1, and that ratio is the most important fact in the entire codebase, because it tells you what the project is for.

The plugins are packaging. The skills are the work.

I assumed, walking into the repository, that the plugins were the product. They have version numbers (aws-core is 1.1.0; the other three are 1.0.0). They have manifest files. They have README.md documents with marketing language ("Start here." "Investigate incidents, review code and execute UAT for release readiness, scan code for vulnerabilities, and run penetration tests with AWS DevOps Agent and AWS Security Agent."). They look like the kind of artifact that gets shipped. Counting the skills changed my mind. Plugins are what an install command grabs; skills are what the agent actually reads when a developer asks it to do something. The repository's center of gravity is the 107 Markdown files, not the four plugin folders.

This chapter maps the surface so you can see the same thing I saw.

The four plugins

The top-level marketplace.json files (one for Claude Code at .claude-plugin/marketplace.json, one for Codex at .agents/plugins/marketplace.json, one for Cursor at .cursor-plugin/marketplace.json) all enumerate the same four plugins, in the same order:

1. aws-core (v1.1.0) — "Build, deploy, and operate applications on AWS." The general-purpose bundle. Service selection, CDK/CloudFormation, serverless, containers, storage, observability, billing, SDK usage, deployment. The README is unambiguous: start here. 2. aws-agents (v1.0.0) — "Build, deploy, and operate AI agents on AWS." Skills for scaffolding agents with Amazon Bedrock AgentCore (Strands, LangGraph), connecting tools via Gateway and MCP, multi-agent and A2A orchestration, memory, Cedar policies, evaluation, observability, and production hardening. 3. aws-data-analytics (v1.0.0) — "Data lake, analytics, and ETL workflows with S3 Tables, AWS Glue, and Athena." Managed Iceberg tables on S3 Tables, ingestion from JDBC databases, Amazon Redshift, Snowflake, BigQuery, federated Athena queries, vector storage on S3 Vectors, Amazon OpenSearch Service. 4. aws-agents-for-devsecops (v1.0.0) — "Investigate incidents, review code and execute UAT for release readiness, scan code for vulnerabilities, and run penetration tests with AWS DevOps Agent and AWS Security Agent." Note: this is the only plugin that ships a commands/ directory (9 slash commands) and an examples/ directory. The other three are pure skill bundles.

graph TB
  M[Agent Toolkit for AWS<br/>marketplace.json]
  M --> P1[aws-core v1.1.0]
  M --> P2[aws-agents v1.0.0]
  M --> P3[aws-data-analytics v1.0.0]
  M --> P4[aws-agents-for-devsecops v1.0.0]
  P1 --> S1[15 skills]
  P1 --> S2[hooks/secret-safety.py]
  P1 --> S3[.mcp.json: aws-mcp proxy]
  P2 --> S4[7 lifecycle skills]
  P2 --> S5[.mcp.json: knowledge endpoint]
  P3 --> S6[8 analytics skills]
  P3 --> S7[.mcp.json: aws-mcp proxy]
  P4 --> S8[13 devsecops skills]
  P4 --> S9[9 slash commands]
  P4 --> S10[examples/multi-space-walkthrough]
  P4 --> S11[.mcp.json: DevOps Agent endpoint]
  R1[Top-level skills/]
  R1 --> R2[14 core-skills]
  R1 --> R3[50 specialized-skills<br/>across 10 categories]

The diagram is worth a second look. Notice that three of the four plugins each ship their own .mcp.json — that is the configuration that tells the agent host which MCP server to launch. Each configuration is different, which is not what you would expect from a project that markets itself as a unified toolkit. We will get to why in E02. Notice also that aws-core is the only plugin that ships a hook. That is the single most distinctive security feature in the entire codebase, and only one of the four plugins has it. The toolkit is not a uniform product. It is a federation of four products that share a code style and a marketplace.

The 107 skills

The skill library is where the substance lives. The repository is split between skills that live *inside* a plugin (and are installed when the plugin is installed) and skills that live at the *top level* under skills/. The top-level directory is split into core-skills/ (14 skills, generic across services) and specialized-skills/ (50 skills, organized into 10 service categories). The categories are exactly what you would expect from a comprehensive AWS cookbook:

| Category | Count | Representative skill | |---|---|---| | analytics-skills | 11 | creating-data-lake-table | | database-skills | 9 | amazon-aurora-postgresql | | serverless-skills | 10 | aws-lambda-durable-functions | | networking-and-content-delivery-skills | 5 | creating-production-vpc-multi-az | | ec2-skills | 3 | launching-ec2-instance-with-best-practices | | operations-skills | 3 | setting-up-cloudtrail-multi-region | | migration-and-modernization-skills | 2 | dms-schema-conversion | | security-and-identity-skills | 1 | creating-secrets-using-best-practices | | storage-skills | 5 | securing-s3-buckets | | system-table-skills | 3 | querying-aws-cloudwatch | | web-and-mobile-development | 1 | aws-amplify |

You can already see the shape of the AWS surface from this distribution. The serverless skills are the deepest — 10 of them, including three for novel Lambda execution shapes (aws-lambda-durable-functions, aws-lambda-managed-instances, aws-lambda-microvms). The database skills are equally deep (9), covering Aurora MySQL and Postgres, DocumentDB, ElastiCache, Keyspaces, and the creating-amazon-aurora-db-cluster-with-instances and exporting-rds-to-s3 cross-cutting workflows. The system-table skills are new and small (3), and they signal something specific: AWS is investing in Iceberg-based log/metric/catalog analysis, and these skills are the on-ramp.

What is missing tells a story too. There is one security-and-identity skill (creating-secrets-using-best-practices) and zero skills for AWS WAF, AWS Shield, AWS KMS direct key management, or GuardDuty investigation. Either those workflows are folded into the broader skills, or they are deliberate gaps. The IAM-specific knowledge lives in skills/core-skills/aws-iam/SKILL.md, not in a dedicated security-and-identity skill — a structural choice that we will revisit when we discuss the routing graph in E04.

The manifest format zoo

The most underestimated detail in the repository is that each plugin ships three manifest files, not one. Open the aws-core plugin directory and you see:

• plugins/aws-core/.claude-plugin/plugin.json — the lean Claude Code manifest, with name, version, description, author, license, keywords, homepage, and repository.
• plugins/aws-core/.codex-plugin/plugin.json — the Codex manifest, which adds an interface block with displayName, shortDescription, longDescription, defaultPrompt, developerName, category, capabilities, websiteURL, privacyPolicyURL, termsOfServiceURL, and brandColor. Brand color for aws-core is #FF9900, AWS orange.
• plugins/aws-core/.cursor-plugin/plugin.json — the Cursor manifest, which uses yet another schema (Cursor's plugin format, designed to be lighter than Claude's but richer than Codex's marketing fields).
• The top-level .agents/plugins/marketplace.json adds a fourth shape: a policy block (installation: AVAILABLE, authentication: ON_INSTALL) and a structured source: { source: "local", path: "./plugins/aws-core" } object instead of a plain string.

The same plugin is therefore described in four different ways for four different agent hosts. This is not a mistake. The host platforms (Claude Code, Codex, Cursor, Kiro) have not converged on a single plugin manifest schema, and the toolkit ships the schema that each host expects. The cost is duplication — 12 manifest files where one would do — but the benefit is that the toolkit is installable from the official marketplace of each host, with the host's own UI affordances.

The validator at tools/validate.py (a 217-line stdlib-only Python script) is the enforcement mechanism. It checks each plugin's three manifests, validates that the skill name in each SKILL.md frontmatter matches ^[a-z][a-z0-9]+(-[a-z0-9]+)*$ (kebab-case), that the name equals the parent directory name, that the name is at most 64 characters, and that the description is at least 20 characters. It also validates the marketplace manifests and the per-plugin MCP configurations. Every CI run on every PR executes this validator via mise run lint:manifests. The 107 SKILL.md files all conform — the validator is not advisory, it is the gate.

You open your coding agent. You type /plugins install aws-core. Three seconds later, 15 skills are available to you — 15, not 107, because aws-core only bundles 15 of its own, plus the manifest that links the agent to the AWS MCP Server. The remaining 92 skills live in the top-level skills/ directory and are installed separately with npx skills add aws/agent-toolkit-for-aws/skills. The plugin does the MCP wiring; the skills directory does the workflow library. Two install paths, two purposes, one repository.

Why the four-plugin structure matters

The plugin boundaries are not arbitrary. They map to the four kinds of work an agent on AWS might do: *operate* (aws-core), *build agents* (aws-agents), *analyze data* (aws-data-analytics), *investigate incidents* (aws-agents-for-devsecops). A team adopting the toolkit can pick the plugin that matches their primary use case and ignore the rest. The fact that aws-agents and aws-agents-for-devsecops have a redundant prefix is not a naming accident — it signals that the team treats "agents" as a category, not as a single product. You might install aws-agents to build on Bedrock AgentCore and aws-agents-for-devsecops to investigate production incidents on the agents you have already built. The two are complements, not competitors.

The four-plugin structure also signals the limits of the toolkit's ambition. AWS Labs released roughly a dozen MCP servers in 2024-2025 (one per service or service family). The Agent Toolkit has consolidated those into four plugins. The consolidation is the governance story: instead of letting a developer pick from a dozen single-purpose MCP servers and assemble their own stack, the toolkit offers four curated bundles. The cost is choice; the benefit is coherence.

But what is the agent actually talking to? That is not a plugin question. Open the next chapter's .mcp.json files and you will see something I did not expect.