Syncs kongctl reference docs after a release: creates pages for new commands, removes pages for dropped commands, and updates navigation indexes and redirects. Trigger when the user runs '/kongctl-new-command', shares a 'Sync kongctl Releases' PR, asks to update pages under app/kongctl/, or asks to add, create, or document a new kongctl command (e.g. 'add docs for kongctl roar', 'create a page for the new kongctl command', 'update app/kongctl with the new command').
Syncs kongctl reference docs after a release: creates pages for new commands, removes pages for dropped commands, and updates navigation indexes and redirects. Trigger when the user runs '/kongctl-new-command', shares a 'Sync kongctl Releases' PR, asks to update pages under app/kongctl/, or asks to add, create, or document a new kongctl command (e.g. 'add docs for kongctl roar', 'create a page for the new kongctl command', 'update app/kongctl with the new command').
kongctl command docs skill
Generates reference pages and index updates for new kongctl commands, using pre-generated include files from app/_includes/kongctl/help as the source of truth.
If any paths correspond to removed commands (the include file no longer exists), handle those with Step 2 first, then skip to Step 3 for new ones.
Prerequisites
Check that kongctl is installed and up to date. Run:
which kongctl && kongctl version
# If missing: brew install kongctl (or: brew upgrade kongctl)
Ask the user to upgrade to the latest version before proceeding:
"Before I start, please upgrade kongctl to the latest version. You can use brew upgrade kongctl or curl -fsSL https://get.konghq.com/kongctl | sh -s -- --version <version-name>. Let me know when that's done."
Only continue once the user confirms their version is up to date.
Only run kongctl commands with the --help flag.
Step-by-step instructions
Step 1: Identify new and removed commands from the PR
Only needed for Option A. Skip to Step 2 if you used Option B.
Fetch added and removed include files from the PR (use --paginate — these PRs often touch 100+ files):
added: lines are new include files. Strip the app/_includes/kongctl/help/ prefix to get the <COMMAND-PATH> for each.
removed: lines are dropped commands. Strip the app/_includes/kongctl/help/ prefix to get the command path (e.g. get/gateway/consumer), then process with Step 2 before continuing.
Step 2: Handle removed commands
For each removed command, do all four of the following.
Remove from parent file
Determine where the command lives:
3-level command (e.g. get/event-gateway/backend-clusters): it's a ### section in the flat file app/kongctl/get/event-gateway.md. Remove the entire ### section (heading, description paragraph, and {% include_cached %} line). Do not reformat the rest of the file.
2-level command (e.g. get/dcr-provider): it's its own .md file (app/kongctl/get/dcr-provider.md). Remove its table row from app/kongctl/get/index.md and delete the file.
If the file or section doesn't exist locally, skip this sub-step.
Check the navigation index
Open app/_indices/kongctl.yaml and delete any entry that directly references the removed command's URL path. Sub-command pages are normally covered by glob patterns, but verify.
Remove crosslinks
Search for stale links and remove any related_resources entries or inline links pointing to the deleted URL:
Top-level commands (e.g. roar) become standalone index.md files at app/kongctl/roar/index.md:
---title:kongctl<command>description:"<First sentence from --help output>"content_type:referencelayout:referenceworks_on:-konnecttools:-kongctlbreadcrumbs:-/kongctl/related_resources:-text:Declarativeconfigurationwithkongctlurl:/kongctl/declarative/-text:Getstartedwithkongctlurl:/kongctl/get-started/---
<Fullopeningparagraphfrom--helpoutput>## Command usage
{%include_cached/kongctl/help/<command>/index.md%}
2-level commands (e.g. get/dcr-provider) become standalone .md files at app/kongctl/get/dcr-provider.md.
---title:<commandname,e.g."kongctl get dcr-provider">description:"<Short description of what the command does>"content_type:referencelayout:referenceworks_on:# kongctl is a Konnect-native CLI. Set both on-prem and konnect only for pages# under /gateway/, since those commands interact with on-prem Gateway resources.# All other pages should be konnect only.-konnecttools:-kongctlbreadcrumbs:# List each ancestor as a breadcrumb. For app/kongctl/get/dcr-provider.md:-/kongctl/-/kongctl/get/related_resources:-text:kongctl<verb>commandsurl:/kongctl/<verb>/---
<Shortdescriptionofwhatthecommanddoes>## Command usage
{%include_cached/kongctl/help/<path/to/include/file.md>%}
3-level commands (e.g. get/event-gateway/backend-clusters) are NOT standalone files. They are added as ### sections within the flat parent file app/kongctl/get/event-gateway.md. See Step 5 for how to add them.
Run kongctl <command> --help and use the opening paragraph (the text before "Usage:") as the description. Apply these rules:
Replace "Konnect" with {{site.konnect_short_name}}, "Event Gateway" with {{site.event_gateway_short}}, "Kong Gateway" with {{site.base_gateway}}
In body text only (not description frontmatter): wrap verb names and subcommand names in backticks
Use the first sentence for description; use the full paragraph for body text
Step 4: Create resource group pages for new command groups
When a new resource group appears (e.g. get/event-gateway/ in the includes), create a flat .md file at app/kongctl/get/event-gateway.md — not an index.md in a directory.
---title:<commandgroupname,e.g."kongctl get event-gateway">description:"<Short description of what this group of commands does>"content_type:referencelayout:referenceworks_on:-konnect# same rules as Step 3tools:-kongctlbreadcrumbs:# List ancestor paths only (not the page's own URL).# For app/kongctl/get/event-gateway.md:-/kongctl/-/kongctl/get/related_resources:-text:kongctl<verb>commandsurl:/kongctl/<verb>/---
<Shortdescriptionofwhatthisgroupofcommandsdoes>## Command usage
{%include_cached/kongctl/help/<verb>/<resource>/index.md%}
### kongctl <verb> <resource> <subcommand><Shortdescriptionofwhatthissubcommanddoes>
{%include_cached/kongctl/help/<verb>/<resource>/<subcommand>.md%}
Run kongctl <command group> --help to get the opening description and subcommand list. Apply the same rules as Step 3.
Step 5: Update parent index pages
Add rows in alphabetical order by command name.
New 2-level command (e.g. get/dcr-provider): add a row to app/kongctl/get/index.md with a page link: [kongctl get dcr-provider](/kongctl/get/dcr-provider/)
New resource group (e.g. get/event-gateway): add a row to app/kongctl/get/index.md with a page link: [kongctl get event-gateway](/kongctl/get/event-gateway/)
New 3-level subcommand (e.g. get/event-gateway/backend-clusters): add a ### section to app/kongctl/get/event-gateway.md in alphabetical order among the existing sections in that file.
Step 6: Update the navigation index
Update app/_indices/kongctl.yaml only when a new top-level command is added (e.g. explain, scaffold). Subcommand pages under an existing verb are covered by existing glob patterns and don't need changes.
For a new top-level command, add a section under "CLI References" in alphabetical order:
-title:<Descriptivesectiontitle>items:-path:/kongctl/<verb>/-path:/kongctl/<verb>/*/**# add if verb has subcommand groups
