Feat: Add an API Gateway agent skill

[rspurgeon]

Create an API Gateway "product specific" skill which will aide a user in creating new or managing existing Kong API Gateway control planes and their configurations. Here are some sample goals described via prompts:

• Create a new Kong Konnect control plane for our payments service and configure it with rate limiting, key authentication, and the routes defined in @apis/payments-spec.yaml
• List our existing Konnect control planes and show me what services and routes are configured on the production gateway
• Generate declarative configuration files from our current konnect control plane named "platform-gateway" and help me create github actions to manage them in CICD using kongctl and deck together
• Add the new @apis/orders-spec.yaml as a service and routes on our development control plane, applying our standard plugin policies (rate limiting, cors, request-transformer)
• Sync our local deck configuration in @kong/ to our staging control plane and show me the diff before applying
• Create a new control plane group with a staging and production control plane, then set up the proxy configuration from the openapi specs in @apis/

Build the skill and validate some initial results via popular coding tools.

[github-actions]

🎯 Agentic Issue Triage

Summary: Feature request to add a new kongctl-gateway agent skill — a product-specific skill focused on helping users create, configure, and manage Kong Konnect API Gateway control planes via natural language prompts. This complements the existing kongctl-declarative and kongctl-query skills with a gateway-centric UX layer.

📋 Issue Analysis

Type: Feature Request / New Skill
Area: skills/ — agentic workflows, Konnect API Gateway
Complexity: Medium-High

The request asks for a skill that covers:

1. Control plane lifecycle — create/list/manage control planes and control plane groups
2. Service & route configuration — adding services and routes from OpenAPI specs
3. Plugin management — rate limiting, key auth, CORS, request-transformer
4. Declarative config generation — dumping to deck format, managing via CICD
5. deck integration — sync, diff, and apply deck configurations to Konnect

The sample prompts are concrete and well-scoped — they serve well as acceptance criteria.

Relationship to existing work:

• kongctl-declarative skill covers plan/apply/sync/diff/adopt workflows — the new skill will likely call into declarative workflows rather than replace them
• kongctl-query skill covers read-only inspection — the new skill will use these patterns too
• Issue Feat: Add 'generate` subcommand #486 (generate subcommand) has surface area overlap around generating declarative config and GitHub Actions — worth coordinating

🗂️ Suggested Skill Structure

Based on the existing kongctl-declarative and kongctl-query skill layouts, the new skill should follow the same directory convention:

skills/kongctl-gateway/
├── SKILL.md              # Skill manifest: name, description, goal, preconditions
├── agents/               # Agent definition(s) for the skill
│   └── ...
└── references/           # Reference docs loaded on-demand
    ├── commands.md       # Control plane, service, route, plugin commands
    ├── resources.md      # Declarative resource skeletons for gateway resources
    └── troubleshooting.md

embed.go at the skills root embeds these files — confirm it picks up the new directory automatically (or add an explicit embed directive).

✅ Implementation Checklist

• Create skills/kongctl-gateway/SKILL.md with:
  • name: kongctl-gateway
  • Clear description (used for skill routing decisions)
  • goal, preconditions, config-and-environment-overrides sections matching existing skill style
• Create agent definition(s) under skills/kongctl-gateway/agents/
• Create skills/kongctl-gateway/references/commands.md covering:
  • Control plane CRUD (kongctl get/create/delete control-planes)
  • Plugin configuration patterns
  • deck sync/diff commands (deck sync, deck diff, deck dump)
  • Generating declarative config from OpenAPI specs
• Create skills/kongctl-gateway/references/resources.md with declarative skeletons for gateway resources (services, routes, plugins, upstreams)
• Create skills/kongctl-gateway/references/troubleshooting.md
• Verify skills/embed.go includes the new directory
• Update skills/README.md to document the new skill
• Validate the skill against each of the 6 sample prompts in the issue using at least one coding tool (Cursor, GitHub Copilot, etc.)

💡 Design Nudges

• Reuse, don't duplicate: Where the skill needs declarative operations (plan, apply, sync), consider referencing or delegating to kongctl-declarative rather than reimplementing. The skill routing description is the key lever — make it clear that kongctl-gateway is the entry point for gateway config goals while kongctl-declarative is the engine.
• deck vs. kongctl declarative: Several prompts mention deck directly. The skill should handle both the kongctl declarative path and raw deck CLI usage — clarify in the SKILL.md which tool to prefer and when.
• Safety first: Control plane operations are destructive. The skill should emphasize plan/diff before apply/sync, and warn about production control planes explicitly — similar to how kongctl-declarative handles this.
• OpenAPI → gateway config: The prompts around @apis/payments-spec.yaml suggest the skill should know how to call kongctl apply --spec (file) or equivalent. Make sure the commands reference covers OAS-to-gateway bootstrap flows.
• Control plane groups: The last sample prompt touches control plane groups, which may require additional kongctl subcommand support — worth checking current CLI capabilities and noting gaps as follow-on issues.

🔗 Related Issues & Resources

• Feat: Add 'generate` subcommand #486 — Feat: Add 'generate' subcommand — overlaps on declarative config generation and GitHub Actions scaffolding; coordinate to avoid duplication
• Existing kongctl-declarative skill — reference implementation for skill structure and style
• Existing kongctl-query skill — reference for read-only query patterns
• [Kong deck documentation]((docs.konghq.com/redacted) — deck CLI reference for sync/diff/dump commands
• [Konnect Control Planes API]((developer.konghq.com/redacted) — API reference for control plane operations
• kongctl declarative docs — in-repo declarative configuration guide

Generated by Opened Issue Triage for issue #576 · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/issue-triage.md@69b5e3ae5fa7f35fa555b0a22aee14c36ab57ebb