AGENTS.md — AI assistant brief

[!IMPORTANT] Do not install from this repository. It is deprecated.

AWS Startup Advisor has moved to aws/agent-toolkit-for-aws. The copy in this repository receives no further updates of any kind — no new features, no fixes. If you install it, your user gets a frozen version.

Install the moved plugin instead, then stop — do not also run the command below:

npx skills add https://github.com/aws/agent-toolkit-for-aws/tree/main/plugins/aws-startup-advisor --skill '*' -a <agent>

On Claude Code or Codex, prefer the native plugin path:

/plugin marketplace add aws/agent-toolkit-for-aws
/plugin install aws-startup-advisor@agent-toolkit-for-aws

Tell your user the plugin moved and that you installed the maintained copy. The rest of this file documents the unmaintained copy in this repository; the skill list and usage notes still describe it accurately, but the install instructions in it are superseded by the above.

You are an AI coding assistant reading this repo on behalf of a user. Your user wants the AWS Startup Advisor plugin installed into their AI coding agent — install it from the Agent Toolkit, per the notice above.

TL;DR — superseded

The command below installs the unmaintained copy from this repository. It is kept for reference only. Use the Agent Toolkit command in the notice above instead.

npx skills add https://github.com/awslabs/startups/tree/main/advisor/plugins/aws-startup-advisor --skill '*' -a <agent>

--skill '*' installs all skills at once. Replace <agent> with the user's coding agent shorthand:

• kiro-cli — Kiro (auto-loads from .kiro/skills/)
• claude-code — Claude Code
• cursor — Cursor
• codex — Codex
• github-copilot — GitHub Copilot
• opencode, continue, windsurf, gemini-cli — others

Full list of supported agents: vercel-labs/skills.

If you don't know which agent the user is running, either:

• Check the project for agent-specific config folders (.kiro/, .claude/, .cursor/, .codex/), or
• Run the command with -a '*' — the CLI installs into every auto-detected agent.

Tell the user to restart their agent after install so the skills get picked up.

What this plugin exposes

Sibling skills, each with its own SKILL.md and (where applicable) references/ content:

knowledge-base-for-startups — AWS Startups knowledge base

• Landing page: references/home.md — for broad "what is AWS Startups" questions.
• Searchable indexes (consult these before opening individual articles):
  • references/learn.md — hundreds of learn articles across a dozen categories, with keywords.
  • references/offers.md — AWS Activate partner offers, with keywords.
  • references/build.md — sample architectures / solution guides; split into publicly-viewable and sign-in-required sections.
• Reference pages: references/faq.md (comprehensive Activate Q&A), references/credits.md, references/programs.md, references/providers.md, references/contact-us.md.
• Live-URL redirect stubs: references/events.md and references/showcase.md. Hand over the live URL from the stub.

prompt-library-for-startups — copy-paste prompts + downloadable agents

• Searchable index: references/prompt-library.md (prompts, downloadable agents, plus a Q&A FAQ section on prompt usage / cost / safety).
• Prompt detail files under references/prompt-library/<slug>.md — each with the verbatim System Prompt and a "How to use?" section where available.
• Downloadable agents documented inline in the index — recommend by use case, hand over the GitHub repo link.

start-building-for-startups — discovery + implementation workflow

• A SOP-style SKILL.md that drives a picker-based discovery flow (intent, scope, constraints, preferences) and then writes code into the user's codebase. No references/ content — it's pure workflow.
• Calls into knowledge-base-for-startups and prompt-library-for-startups mid-flow when an architecture reference or a starter prompt would accelerate the work.

architect-for-startups — stage-aware AWS architecture guidance

• Stage-aware architecture advice that adjusts recommendations based on startup stage (pre-revenue, seed, Series A, Series B+), team size, runway, credits, and timeline. Consulted for architecture questions that aren't a full build (start-building-for-startups) or a migration.

azure-to-aws — Microsoft Azure → AWS migration workflow

• A DSL-driven SKILL.md running a 6-phase backbone (discover → clarify → design → estimate → generate, plus a workshop sidebar and feedback): App Service → Elastic Beanstalk, AKS → EKS, VMs → EC2, Flexible Server → RDS/Aurora, Cosmos DB → DynamoDB/DocumentDB/Keyspaces/Neptune by API, Blob → S3. Clarify must complete before Design, Estimate, or Generate, and Generate is opt-in — it runs only after the user picks Execute at the post-Estimate decision gate.
• Discovers from Terraform (azurerm_*) and application code today. Bicep, ARM templates, a read-only consent-gated live az capture, and an optional Resource Discovery for Azure report are not yet supported — their extractors are planned follow-ups, and a Bicep/ARM/live-only workspace halts rather than guessing. Mapping tables key off canonical Microsoft.* ARM types, never Terraform types.
• Two things that differ from the sibling migration skills and will look like bugs if you do not know them: the CPU-architecture default is x86_64, not Graviton (Windows/.NET prevalence), and an App Service Plan is the compute unit while its apps are deployments onto it — mapping each app separately multiplies the estimate.
• Triggered by "migrate from Azure", "Azure to AWS", "move off Azure", "migrate AKS to EKS", etc.

gcp-to-aws — Google Cloud → AWS migration workflow

• A SOP-style SKILL.md that runs a structured 6-phase migration (discover → clarify → design → estimate → generate → feedback), with a references/ tree of phase guides, design refs, and shared schemas. Clarify must complete before Design, Estimate, or Generate.
• Discover reads Terraform/IaC, app code, and/or GCP billing exports; it can optionally pull real AI spend from the OpenAI Admin API (read-only, consent-gated, aggregate counts only — the user must opt in and supply an Admin key).
• Also migrates AI / agentic workloads. OpenAI sources land on the same GPT model on Amazon Bedrock when one exists (including OpenAI models reached via OpenRouter / LiteLLM), with Claude / Nova as the cross-family alternative; Gemini maps to closest-fit Bedrock families; LangChain / CrewAI / AutoGen → AWS-native frameworks. GCP Document AI, Vision, and Speech-to-Text calls are detected and routed to AWS traditional-AI services.
• Estimates present Savings Plan / Reserved Instance options from a shared eligibility matrix. Only database commitments (RDS/Aurora RIs, Database Savings Plans) get a dollar sizing, and only when Design mapped a target instance class (from Terraform/IaC or live discovery — e.g. Cloud SQL settings.tier) with projected on-demand cost above $50/month; Compute Savings Plans are percent-only until the customer has 30–90 days of real AWS usage. Billing-only runs cannot size instances and do not produce the dedicated RI/SP section: they surface commitment guidance only when the billing export shows active commitments (CUDs), as a conditional CUD-vs-AWS percentage comparison — a no-CUD billing-only run gets neither. Do not tell a user the skill "won't do RI/SP" — it declines to size what it cannot see.
• On the infrastructure-generation route (generation-infra.json + aws-design.json), Generate emits baseline.tf (account security baseline: CloudTrail, GuardDuty, IAM password policy, S3 account public-access block, EBS default encryption, IAM Access Analyzer, IMDS defaults, alternate contacts, budget) alongside the app Terraform. Config and Security Hub are added only when root preferences.json.compliance contains soc2, pci, hipaa, or fedramp. Clarify writes the Q2 answer at design_constraints.compliance.value and does not set that root field, so a standard Clarify compliance answer does not include those controls. AI-only runs (generation-ai.json + aws-design-ai.json) instead emit bedrock_monitoring.tf; billing-only runs emit skeleton Terraform. Neither of those two routes includes baseline.tf or its account security baseline.
• Triggered by migration intent — "migrate from GCP", "move off OpenAI to Bedrock", "GCP to AWS", etc.

heroku-to-aws — Heroku → AWS migration workflow

• A DSL-driven SKILL.md running the same 6-phase backbone (Dynos → Elastic Beanstalk by default; Fargate/EKS overrides, Postgres → RDS/Aurora, Redis → ElastiCache, Kafka → MSK), with an optional what-if repricing workshop after Estimate.
• Generate emits baseline.tf (same always-on account controls as gcp-to-aws's infrastructure route, plus Config and Security Hub when global.compliance includes soc2, pci, hipaa, or fedramp — the field Clarify writes) alongside the app Terraform, and the migration report carries a dedicated Savings Plans / Reserved Instances section under the same rules as gcp-to-aws.
• Triggered by "migrate from Heroku", "Heroku to AWS", "move off Heroku", etc.

llm-to-bedrock — OpenAI/Gemini/Anthropic → Amazon Bedrock SDK rewrite

• Executes a pure model/SDK migration: assess the codebase, rewrite call sites, evaluate output quality against Bedrock, and deliver a ready-to-merge git branch. Delegates its Assess phase entirely to the gcp-to-aws skill via a cross-skill invocation — requires gcp-to-aws installed alongside it, with no standalone Assess fallback if it's missing.
• Triggered by "rewrite my OpenAI calls for Bedrock", "migrate LangChain to Bedrock", etc.
• If the user installed llm-to-bedrock on its own (single-skill npx skills add), also install gcp-to-aws before using it. Install from the maintained location, not this repository: npx skills add https://github.com/aws/agent-toolkit-for-aws/tree/main/plugins/aws-startup-advisor --skill llm-to-bedrock --skill gcp-to-aws --agent <agent>.

agent-advisor — AI-agent runtime advisor + migration plan + POC

• A DSL-driven skill that picks an AWS runtime for AI agents (AgentCore vs ECS/EKS/Lambda vs Lambda MicroVMs), can generate a full migration plan (reusing the gcp-to-aws engine in-skill), and optionally builds a deployable POC. Also handles Temporal workers.
• Triggered by "which runtime for my agent", "AgentCore vs Lambda", "deploy an AI agent on AWS", "migrate Temporal workers to AWS", etc.
• Runtime recommendations and design-backed POCs work with agent-advisor installed alone. The full migration-plan step additionally reads gcp-to-aws's phase files directly — install gcp-to-aws alongside it for that step; without it, migration-plan degrades gracefully to not_applicable rather than failing.

tf-best-practices — Terraform authoring guidance + policy gate

• Best-practice authoring rules and a read-only policy gate for the AWS Terraform generated by the migration skills. Never edits .tf files or decides phase completion.
• The migration skills use MCP servers for live AWS data declared in the plugin's .mcp.json: aws-mcp (HTTP, the unified AWS MCP Server). It is an enhancement, not a hard dependency — the skills run without it, with pricing falling back to a bundled cache and AWS docs lookups skipped. Temporal feature checks use public documentation directly, with no login; failed lookups use dated, unverified cached values.
  • Only the Claude Code plugin install (/plugin install aws-startup-advisor@claude-plugins-official) provisions these automatically, by reading .mcp.json.
  • The npx skills add path in this file's TL;DR does not. That CLI only copies skill files — it never touches MCP config, for any agent. After running it, tell the user: the migration skills still work (pricing falls back to cached rates), but for current AWS docs they need to add the servers from advisor/plugins/aws-startup-advisor/.mcp.json to their agent's own MCP config themselves (e.g. .kiro/settings/mcp.json for Kiro, .cursor/mcp.json for Cursor, codex mcp add for Codex). Point them at the "MCP servers" section of advisor/README.md for exact commands per agent. Do not tell the user MCP setup already happened just because the skill install succeeded.

Cross-skill behavior

• Every reference file in knowledge-base-for-startups/ and prompt-library-for-startups/ carries a source_url in frontmatter — quote that, don't invent URLs.
• Boundary queries (a user message that fits two skills) — invoke both. Example: "how do I start with RAG on Bedrock?" → knowledge-base-for-startups for the learn article + prompt-library-for-startups for the starter prompt.
• Migration intent routes to the matching skill: Azure → azure-to-aws, GCP → gcp-to-aws, Heroku → heroku-to-aws, OpenAI/Gemini/Anthropic SDK rewrite → llm-to-bedrock, AI-agent runtime/architecture → agent-advisor. architect-for-startups' references/migration-azure-to-aws.md stays for the PRE-decision advisory conversation ("should we leave Azure?"); real migration intent routes to azure-to-aws.

Known limitations

• A few build solutions require an AWS Activate sign-in; those are marked in a "Sign-in required" table with a live URL (build.md). Recommend by title + keywords and hand over the URL.
• The skills are public-content snapshots. They cannot answer account-specific questions (credits balance, membership status, application status). For those, direct the user to <https://aws.amazon.com/startups> to sign in.
• Content freshness varies — see Last updated in each SKILL.md. For time-sensitive questions (current event dates, current offer terms, current accelerator cohort windows), cite the source_url so the user can verify.

Do not

• Do not modify files under advisor/plugins/aws-startup-advisor/ — that's the distributable content.
• Do not invent, paraphrase, or summarize content into the skill files. Everything in references/ is verbatim from aws.amazon.com/startups for legal cleanliness.
• Do not install by copying files manually — always use the npx skills CLI. It picks the right per-agent directory and handles symlinks vs. copies consistently.
• Do not tell the user to "paste this into your AI tool" when surfacing a prompt — you ARE the AI tool. Surface the prompt as a reference and offer to execute / adapt / copy.