localstack · gtsiolis · Aug 6, 2026
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
@@ -0,0 +1,25 @@
+name: Validate Agent Plugin
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          version: "0.11.16"
+
+      - name: Validate portable plugin and skills
+        run: ./scripts/validate.sh
diff --git a/README.md b/README.md
@@ -1,25 +1,44 @@
-# LocalStack AI Skills
+# LocalStack Agent Skills
 
-AI Agent Skills for developing and testing cloud applications against [LocalStack](https://localstack.cloud) - the local cloud development platform.
+Portable [Agent Skills](https://agentskills.io/) for developing and testing cloud applications with [LocalStack](https://localstack.cloud) through the [`lstk`](https://github.com/localstack/lstk) CLI.
 
-## Overview
+This repository is a skills-only [Agent Plugin](https://agent-plugins.org/) targeting the Agent Plugins v1.0.0 specification. It intentionally does not include `mcp.json`; LocalStack MCP integration is separate follow-up work.
 
-This repository contains a collection of AI skills designed to help developers work more efficiently with LocalStack. These skills enable AI assistants to help with common LocalStack workflows, from managing the local environment to deploying infrastructure and analyzing logs.
-
-## Available Skills
+## Available skills
 
 | Skill | Description |
-|-------|-------------|
-| [localstack-lifecycle](skills/localstack-lifecycle/) | Manage LocalStack container lifecycle (start, stop, status, restart) |
-| [iac-deployment](skills/iac-deployment/) | Deploy infrastructure using Terraform, CDK, CloudFormation, and Pulumi |
-| [state-management](skills/state-management/) | Save, load, and manage LocalStack state with Cloud Pods |
-| [logs-analysis](skills/logs-analysis/) | Analyze LocalStack logs, identify errors, and debug issues |
-| [iam-policy-analyzer](skills/iam-policy-analyzer/) | Analyze IAM policies and auto-generate least-privilege permissions |
-| [localstack-extensions](skills/localstack-extensions/) | Manage LocalStack extensions and plugins |
+| --- | --- |
+| [localstack](skills/localstack/) | Start, stop, configure, and troubleshoot LocalStack emulators with `lstk` |
+| [localstack-deploy](skills/localstack-deploy/) | Deploy and verify infrastructure through the `lstk` Terraform, CDK, SAM, and AWS CLI proxies |
+| [localstack-state](skills/localstack-state/) | Save, load, inspect, and manage LocalStack snapshots and persistent state |
+| [localstack-logs](skills/localstack-logs/) | Inspect emulator logs and diagnose AWS API or Lambda failures |
+| [localstack-iam](skills/localstack-iam/) | Test IAM enforcement and derive least-privilege policies from observed behavior |
+| [localstack-extensions](skills/localstack-extensions/) | Use and author Git-style `lstk-<name>` CLI extensions |
+
+## Use as an Agent Plugin
+
+Clone the repository and point a compatible client's local-plugin workflow at the repository root:
+
+```bash
+git clone https://github.com/localstack/skills.git
+```
+
+The client discovers the root `plugin.json` and each immediate child of `skills/`. Agent Plugins v1 standardizes the package, but intentionally leaves installation and distribution commands to each client. See the [compatible clients](https://agent-plugins.org/compatible-clients) page for client-specific instructions.
+
+This step only prepares a locally loadable skills package. Marketplace publication and bundled MCP configuration are deliberately out of scope.
+
+## Install individual Agent Skills
+
+Clients supported by the Agent Skills CLI can install the collection or select individual skills:
+
+```bash
+npx skills add https://github.com/localstack/skills
+npx skills add https://github.com/localstack/skills --skill localstack-deploy
+```
 
-## Installation
+## Install with Claude Code
 
-### Via the LocalStack standalone marketplace
+The existing Claude marketplace compatibility layer remains available:
 
 ```bash
 claude plugin marketplace add localstack/skills
@@ -28,20 +47,46 @@ claude plugin install localstack@localstack-dev
 
 ## Prerequisites
 
-- [LocalStack](https://docs.localstack.cloud/getting-started/installation/) installed and configured
-- [AWS CLI](https://aws.amazon.com/cli/) or [awslocal](https://docs.localstack.cloud/user-guide/integrations/aws-cli/#localstack-aws-cli-awslocal) wrapper
-- Docker running on your machine
+- [`lstk`](https://github.com/localstack/lstk#installation)
+- A Docker-API-compatible container runtime supported by `lstk`
+- A LocalStack account and `LOCALSTACK_AUTH_TOKEN` for workflows that require authentication
+- The standard AWS, Terraform, CDK, or SAM CLI when using the corresponding proxy skill
+
+## Validate locally
 
-## Usage
+Validation requires [`uv`](https://docs.astral.sh/uv/), Git, and network access to PyPI, GitHub, and `agent-plugins.org`. The script validates `plugin.json` against the canonical Agent Plugins schema and validates every skill with a pinned revision of the official `skills-ref` implementation:
+
+```bash
+./scripts/validate.sh
+```
 
-These skills are designed to be used with AI coding assistants that support the skills/commands interface. Each skill provides contextual guidance and commands for specific LocalStack workflows.
+If Claude Code is installed, also validate the compatibility package:
+
+```bash
+claude plugin validate --strict .
+```
+
+## Package layout
+
+```text
+.
+├── plugin.json
+├── skills/
+│   └── <skill-name>/
+│       └── SKILL.md
+├── .claude-plugin/
+│   ├── plugin.json
+│   └── marketplace.json
+└── scripts/
+    └── validate.sh
+```
 
-## Related Projects
+## Related projects
 
-- [LocalStack](https://github.com/localstack/localstack) - The core LocalStack platform
-- [LocalStack MCP Server](https://github.com/localstack/localstack-mcp-server) - Model Context Protocol server for LocalStack
-- [LocalStack Documentation](https://docs.localstack.cloud/)
+- [lstk](https://github.com/localstack/lstk)
+- [LocalStack MCP Server](https://github.com/localstack/localstack-mcp-server)
+- [LocalStack documentation](https://docs.localstack.cloud/)
 
 ## License
 
-Apache License 2.0 - see [LICENSE](LICENSE) for details.
+Apache License 2.0 — see [LICENSE](LICENSE).
diff --git a/plugin.json b/plugin.json
@@ -0,0 +1,24 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "localstack",
+  "version": "1.0.0",
+  "description": "Portable agent skills for developing and testing cloud applications with LocalStack through lstk.",
+  "author": {
+    "name": "LocalStack"
+  },
+  "homepage": "https://github.com/localstack/skills",
+  "repository": "https://github.com/localstack/skills",
+  "license": "Apache-2.0",
+  "keywords": [
+    "localstack",
+    "cloud",
+    "aws",
+    "azure",
+    "snowflake",
+    "iac",
+    "terraform",
+    "cdk",
+    "testing",
+    "local-development"
+  ]
+}
diff --git a/scripts/validate.sh b/scripts/validate.sh
@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+plugin_schema="https://agent-plugins.org/schemas/1.0.0/plugin.schema.json"
+check_jsonschema_version="0.37.4"
+skills_ref_revision="217be548739f21d6008915c29aefe320ea1a90af"
+skills_ref_source="git+https://github.com/agentskills/agentskills.git@${skills_ref_revision}#subdirectory=skills-ref"
+
+if ! command -v uvx >/dev/null 2>&1; then
+  echo "uvx is required; install uv from https://docs.astral.sh/uv/" >&2
+  exit 1
+fi
+
+echo "Validating plugin.json"
+uvx --from "check-jsonschema==${check_jsonschema_version}" check-jsonschema \
+  --schemafile "$plugin_schema" \
+  "$repo_root/plugin.json"
+
+skill_count=0
+for skill_dir in "$repo_root"/skills/*; do
+  [[ -d "$skill_dir" ]] || continue
+  if [[ ! -f "$skill_dir/SKILL.md" ]]; then
+    echo "missing SKILL.md in $skill_dir" >&2
+    exit 1
+  fi
+
+  echo "Validating ${skill_dir#"$repo_root/"}"
+  uvx --from "$skills_ref_source" skills-ref validate "$skill_dir"
+  ((skill_count += 1))
+done
+
+if (( skill_count == 0 )); then
+  echo "no skills found under $repo_root/skills" >&2
+  exit 1
+fi
+
+echo "Validated plugin.json and $skill_count skills"
diff --git a/skills/iac-deployment/SKILL.md b/skills/iac-deployment/SKILL.md