Imported from aws-samples/sample-apex-skills (skills/ecs-recon/SKILL.md). Install upstream with npx skills add aws-samples/sample-apex-skills --skill ecs-recon. Copyright stays with the author.

ECS Reconnaissance

Discover everything about an ECS environment. Run this skill to gather comprehensive context about clusters, services, and their tasks before making any decisions, changes, or recommendations. Standalone (run-task) and scheduled (EventBridge) tasks are not discovered — discovery enumerates workloads via list-services.

When to Use This Skill

Run this skill when the user:

• Asks about their ECS environment ("what clusters do I have?", "describe my ECS setup")
• Wants to understand their service configuration ("what launch type?", "how is it deployed?")
• Plans to modify a service and needs current-state context first
• Asks to document or review their ECS resources
• Needs task definition details, scaling policies, or networking config
• Mentions an ECS cluster or service and seems to need context

Also trigger this skill when:

• Another workflow needs ECS environment information as input
• User mentions ECS and needs discovery before recommendations
• You need to understand the ECS setup before giving guidance

Do NOT use this skill for:

• Cost scoring or efficiency analysis — belongs to ecs-cost-intelligence (once available)
• Security auditing or compliance scoring — belongs to ecs-security
• Best-practices evaluation or maturity ratings — belongs to ecs-operation-review
• Migration planning (replatform/refactor onto ECS) — belongs to ecs-modernize (once available)
• Amazon EKS requests — belongs to eks-recon; this skill discovers ECS only
• Creating or modifying ECS resources (this is read-only)
• Producing architecture design documents or diagrams

Access Model — READ-ONLY

This skill is strictly read-only. It CAN issue read-only calls (aws ecs describe-*/list-*, application-autoscaling describe-*, elbv2 describe-*, cloudformation describe-*/list-*, codepipeline list-*/get-*, deploy list-*/get-*, sts get-caller-identity, logs describe-*) to discover estate state, and CAN write the report file to the workspace. It CANNOT mutate any resource (no create, update, delete, register, deregister, run-task, or scale operations). If a detection would require a write, record the field as unknown instead.

Prerequisites

MCP Tools (Optional Supplement)

The Amazon ECS MCP server exists in preview (ECS MCP server docs), but its tools are diagnostics-shaped — all require a cluster_name and none enumerate clusters — so it cannot drive discovery. CLI Mode is the primary path for this skill. If the ECS MCP server is configured, its read tools may supplement drill-down diagnostics; it is in preview and subject to change — do not depend on it.

Required for CLI Mode (Primary)

Verifying Access

Before running reconnaissance, verify AWS credentials are available:

aws sts get-caller-identity

IMPORTANT: Never give up after checking only environment variables. AWS credentials can come from ~/.aws/credentials, ~/.aws/config, instance metadata, or ECS task roles — none of which appear in env | grep AWS_. Always try aws sts get-caller-identity before concluding credentials are unavailable.

Reconnaissance Modes

How to Invoke

Full reconnaissance:

"Run ECS reconnaissance in us-west-2"

Selective reconnaissance:

"Run ECS recon but only check compute and auto scaling for service api-prod"

Targeted query:

"What launch type does service api-prod use in cluster production?"

Modules and Reference Loading

Load only the references needed for the user's request — this keeps context focused. references/overview.md is always loaded first for the Overview Scan phase; it provides the cluster/service inventory all other modules depend on. For targeted queries, load only the matching row(s); for full recon, load all references.

Quick Detection Reference

CLI Commands (Current Default)

Running Reconnaissance

IMPORTANT: Load Reference Files

Before running each module, you MUST read its reference file (e.g., references/compute.md). References contain:

• Detection order and rationale
• Edge cases and how to handle them
• CLI commands with example outputs
• Output schema for structured reporting

Skipping references produces shallow results. The main skill provides orchestration; the references provide detection intelligence.

Never reproduce containerDefinitions[].environment values or non-awslogs logConfiguration.options in output or the report — they routinely contain plaintext credentials.

Step 1: Gather Prerequisites

Required:
- AWS region (or detect from context/CLI)
- AWS credentials (verified via sts get-caller-identity)

Optional:
- Specific cluster/service to target (default: discover all)
- Specific modules to run (default: all)
- Output file path (default: .ecs-recon-report.yaml)

Region resolution order:

1. User-provided region
2. AWS_DEFAULT_REGION or AWS_REGION environment variable
3. aws configure get region
4. If none available, ask the user

Step 2: Check Tool Availability

CLI Mode is the primary path — the ECS MCP server (preview) offers no cluster-enumeration tools, so discovery always runs on the AWS CLI. If the ECS MCP server is configured, its read tools may optionally supplement drill-down diagnostics; record tool_mode: mixed in that case, otherwise tool_mode: cli (the normal value).

Step 3: Run Overview Scan

Load references/overview.md and execute the Overview Scan:

1. List all clusters (paginated — collect all pages)
2. List services per cluster (paginated — collect all pages)
3. Describe clusters (get task counts, capacity providers, settings)
4. Present the overview map to the user

If only one cluster exists, auto-select it for drill-down. If multiple clusters exist, ask the user which to drill into (or run full recon if requested).

Step 4: User Selection

After presenting the overview map:

• If user requested full recon: proceed with all modules on all clusters
• If user picks a specific cluster/service: scope drill-down to that target
• If targeted query: run only the relevant module

Step 5: Run Drill-Down Modules

For each selected module:

1. Load the reference file — REQUIRED
2. Run detection commands following the reference's guidance:
   • Use the CLI commands from the reference (primary path)
   • ECS MCP server read tools (if configured) may supplement diagnostics
   • If detection is not possible, record as unavailable with reason
3. Collect output into report section using the reference's output schema

Execution order: Modules are independent — run them in any order. Each module is self-contained with its own detection commands and output schema.

Step 6: Generate Report

Write report to .ecs-recon-report.yaml and present summary to user.

Summarize facts, not verdicts — this skill must not emit health/quality judgments (that is ecs-operation-review's lane).

Report sensitivity: the report embeds account IDs, subnet/security-group IDs, IAM role ARNs, and secret ARNs. Treat it as sensitive — write it only inside the workspace, and do not commit it (recommend adding .ecs-recon-report.yaml to .gitignore).

Report Generation

The final report follows this YAML schema:

# ECS Reconnaissance Report
# Generated: 2026-01-15T10:30:00Z
# Account: 123456789012
# Region: us-west-2
# Modules: overview, compute, task_definitions, deployment, autoscaling, networking, security, observability, iac, cicd

metadata:
  account_id: string
  region: string
  timestamp: string  # ISO 8601 UTC
  tool_mode: string  # "cli" (normal) | "mixed" (ECS MCP server supplemented diagnostics)
  modules_run: list[string]
  coverage:
    regions: list[string]     # Regions covered (single-region per run)
    scope_note: string        # "services and their tasks only; standalone (run-task) and scheduled (EventBridge) tasks not discovered"
    clusters_discovered: int  # Clusters found in the Overview Scan
    clusters_drilled_down: int  # Clusters covered by drill-down modules

overview:
  clusters: list[ClusterSummary]

# Drill-down sections (present only if module was run)
compute: ComputeOutput | UnavailableOutput
task_definitions: TaskDefinitionsOutput | UnavailableOutput
deployment: DeploymentOutput | UnavailableOutput
autoscaling: AutoScalingOutput | UnavailableOutput
networking: NetworkingOutput | UnavailableOutput
security: SecurityOutput | UnavailableOutput
observability: ObservabilityOutput | UnavailableOutput
iac: IaCOutput | UnavailableOutput
cicd: CICDOutput | UnavailableOutput

UnavailableOutput (for modules that could not complete)

unavailable: true
reason: string  # Human-readable explanation (e.g., "Access denied on ecs:DescribeServices")

Module-level unavailable: true is reserved for total module failure. Each module's per-service entries may carry error: string | null — per-resource failures are recorded inline on the affected entry and recon continues with the rest.

Example Report

metadata:
  account_id: "123456789012"
  region: us-west-2
  timestamp: "2026-01-15T10:30:00Z"
  tool_mode: cli
  modules_run:
    - overview
    - compute
    - task_definitions
    - deployment
  coverage:
    regions:
      - us-west-2
    scope_note: "services and their tasks only; standalone (run-task) and scheduled (EventBridge) tasks not discovered"
    clusters_discovered: 1
    clusters_drilled_down: 1

overview:
  clusters:
    - name: production
      arn: arn:aws:ecs:us-west-2:123456789012:cluster/production
      status: ACTIVE
      services_count: 3
      running_tasks: 12
      stopped_tasks: 2  # int | null (null = not collected)
      capacity_providers:
        - FARGATE
        - FARGATE_SPOT
      services:
        - name: api-service
          status: ACTIVE
          desired_count: 4
          running_count: 4
          launch_type: not_applicable  # capacity provider strategy in use
        - name: worker-service
          status: ACTIVE
          desired_count: 2
          running_count: 2
          launch_type: FARGATE

compute:
  cluster:
    name: production
    capacity_providers:
      - name: FARGATE
        type: FARGATE
        status: ACTIVE
        auto_scaling_group_arn: null
      - name: FARGATE_SPOT
        type: FARGATE_SPOT
        status: ACTIVE
        auto_scaling_group_arn: null
    default_capacity_provider_strategy:
      - provider: FARGATE
        weight: 1
        base: 1
      - provider: FARGATE_SPOT
        weight: 3
        base: 0
  services:
    - name: api-service
      launch_type: not_applicable
      capacity_provider_strategy:
        - provider: FARGATE
          weight: 1
          base: 1
        - provider: FARGATE_SPOT
          weight: 3
          base: 0
      task_counts:
        running: 4
        desired: 4
        pending: 0
    - name: worker-service
      launch_type: FARGATE
      capacity_provider_strategy: []
      task_counts:
        running: 2
        desired: 2
        pending: 0

task_definitions:
  services:
    - service_name: api-service
      family: api-service
      revision: 42
      task_cpu: "1024"
      task_memory: "2048"
      network_mode: awsvpc
      containers:
        - name: api
          image: 123456789012.dkr.ecr.us-west-2.amazonaws.com/api:v1.5.0
          cpu: 896
          memory: 1792
          memory_reservation: null
          essential: true
        - name: envoy
          image: public.ecr.aws/appmesh/aws-appmesh-envoy:v1.27.0
          cpu: 128
          memory: 256
          memory_reservation: null
          essential: true

deployment:
  services:
    - service_name: api-service
      controller_type: ecs_rolling  # ecs_rolling | ecs_blue_green | ecs_linear | ecs_canary | code_deploy | external
      strategy: ROLLING  # ROLLING | BLUE_GREEN | LINEAR | CANARY | null (ECS controller + deploymentConfiguration.strategy decides the ecs_* controller_type; ROLLING or absent strategy -> ecs_rolling)
      minimum_healthy_percent: 100
      maximum_percent: 200
      bake_time_in_minutes: null
      circuit_breaker:
        enabled: true
        rollback_enabled: true
      alarms:
        alarm_names: []
        enable: false
        rollback: false
      deployments:
        - id: ecs-svc/1234567890
          status: PRIMARY
          desired_count: 4
          running_count: 4
          rollout_state: COMPLETED

Integration with Other Workflows

Cost Intelligence Workflow

The cost intelligence workflow can invoke ecs-recon to gather baseline context:

1. Run ecs-recon modules: overview, compute, autoscaling
2. Extract:
   - Cluster capacity providers → cost model
   - Service task counts → utilization baseline
   - Auto scaling config → scaling efficiency

Security Audit Workflow

The security audit workflow can use ecs-recon for discovery:

1. Run ecs-recon modules: overview, security, networking
2. Extract:
   - Task roles → IAM analysis input
   - Secrets references → secrets management audit
   - Network config → isolation analysis

Migration Workflow

The migration workflow can use ecs-recon to understand existing state:

1. Run ecs-recon modules: all
2. Extract:
   - Complete environment inventory
   - IaC tooling → migration tooling decisions
   - Deployment config → migration strategy input

Sources

Facts verified 2026-07-14 against the URLs below.

• Amazon ECS MCP server (preview) — tool surface and preview status
• API_Service — service fields (launch type, capacity provider strategy, deployment controller)
• API_DeploymentConfiguration — strategy, bake time, circuit breaker, alarms
• Amazon ECS Developer Guide