Kong/ai-marketplace / plugins/kong-konnect/skills/kong-skill-authoring
kong-skill-authoring
VerifiedCreate or refactor a skill in this repo. Use when deciding extend-versus-create, classifying domain/tool/router ownership, tightening a description, or reviewing a skill package against repo policy. Not for the product workflow itself.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.1 KB |
SKILL.md
View on GitHub---
name: kong-skill-authoring
description: Create or refactor a skill in this repo. Use when deciding extend-versus-create, classifying domain/tool/router ownership, tightening a description, or reviewing a skill package against repo policy. Not for the product workflow itself.
license: MIT
metadata:
product: repo
internal: true
category: skill-authoring
tags:
- kong
- skills
- authoring
- review
- workflow
---
# Kong skill authoring
## Goal
Help contributors create or revise high-signal skills for this repository
without creating overlap, generic filler, root bloat, or tool-boundary
confusion.
Treat `AGENTS.md` as the canonical authoring policy. Use this skill as the
decision layer for what the skill should own, how it should be structured, and
what should stay out of it.
## Tool Selection
- Use the host environment's built-in generic skill-authoring helper first when
it materially improves structure, then apply this repo's rules as the final
authority.
- Use this skill for authoring decisions and review workflow, not for the
Konnect or Gateway task that the target skill will later handle.
- When the user is asking for product execution, diagnosis, or declarative
implementation rather than skill authoring, hand off to the relevant domain,
router, or tool skill instead of keeping the work here.
## References To Load
- Load `AGENTS.md` first for authoring policy, section conventions, layered
skill design, and plugin-aware repo boundaries.
- Load `docs/skills.md` and inspect `plugins/*/skills/*/SKILL.md` when checking
for overlap, adjacent trigger surfaces, or handoff targets.
## Workflow
1. State the target skill's job in one sentence.
- If the request is really about doing Konnect or Gateway work rather than
authoring the skill, stop and hand off.
2. Check overlap before drafting.
- Inspect `docs/skills.md` and the existing `plugins/<plugin>/skills/`
trees.
- Extend an existing skill when the trigger class, ownership boundary, and
operating procedure are substantially the same.
- Create a new skill only when the workflow, owner, or trigger surface is
materially different.
3. Classify the skill boundary.
- Use a domain skill when the hard part is Kong-specific diagnosis,
inspection order, or operator workflow.
- Use a tool skill when the hard part is `decK`, `kongctl`, Terraform,
import/adopt behavior, or file-shape ownership.
- Use a router skill only when the main problem is broad classification
across existing specialist skills.
- If both domain and tool concerns appear, keep diagnosis in the domain
skill and hand off implementation to the tool skill.
4. Define the trigger surface before writing body text.
- Write down what a user would actually ask.
- Name the nearby requests that should not activate the skill.
- Keep the `description` activation-grade: front-loaded, explicit, and
usually under roughly 260 characters.
- Tighten the boundary instead of adding long example lists.
5. Keep `SKILL.md` as the decision layer.
- Root content should cover ownership, workflow or inspection order,
defaults, validation, and handoffs.
- Do not turn the root into a command catalog, product guide, schema dump,
or copy of repo policy that already lives in `AGENTS.md`.
- Prefer subtraction before rewriting. Delete detail that does not change
agent behavior.
6. Place detail in the cheapest useful layer.
- Keep branch-specific depth in `references/` with an explicit load
condition.
- Make each reference file support one branch, failure domain, or execution
mode. Split files that carry multiple unrelated jobs.
- Add a `scripts/` helper only when deterministic validation or
transformation is materially safer than prompt text.
- Do not create companion files just to relocate generic filler.
7. Run the review tests before you finalize structure.
- Overfitting test: remove assumptions about one repo layout, starter
bundle, exact command path, exact auth check, current UI behavior, or one
canonical naming scheme unless that specificity is safety-critical.
- Minutiae test: trim long field lists, dense flag catalogs, or examples
that the model would copy more readily than reason from.
- Progressive-disclosure test: move detail down a layer when metadata, root,
references, or scripts can hold it more cheaply without harming behavior.
- If the root still reads like a condensed runbook or partial manual, cut or
relocate content before polishing wording.
8. Apply the repo's section conventions.
- Domain skills should use `Goal`, `Tool Selection`, `References To Load`,
`Workflow` or `Inspection Order`, an explicit gotchas section,
`Validation Checklist`, and `Handoffs`.
- Tool skills should use `Goal`, `Tool Positioning`, `References To Load`,
`Validation Contract`, `Operating Rules`, `Workflow`,
`Validation Checklist`, and `Handoffs`.
- Router skills should use `Goal`, `Shared Operating Defaults`,
`Classification Order`, `Routing Rules`, `Validation Checklist`, and
`Output Style`.
- Do not introduce cosmetic heading drift for equivalent concepts.
9. Preserve Kong-specific boundaries.
- For Konnect work, prefer the shared `kong-konnect` MCP server for live
inspection when available, but keep fallback paths through `kongctl`,
declarative config, logs, or user-provided artifacts.
- Preserve the repository's existing toolchain instead of forcing migration
between `decK`, `kongctl`, and Terraform.
- Keep domain skills focused on reasoning quality and handoffs instead of
absorbing full tool-execution playbooks.
10. Produce the smallest useful authoring output.
- State whether to extend an existing skill or create a new one.
- Name the owning plugin path.
- Provide the exact `description` trigger surface.
- List the minimum root sections and any justified companion files with
exact load conditions.
- When reviewing an existing skill, lead with the highest-risk finding and
the smallest corrective move.
- Before stopping, name the main pass/fail call for trigger quality,
boundary discipline, reasoning quality, root bloat, reference discipline,
and reference bloat.
## Validation Checklist
- The edit stays within the owning skill directory unless the task explicitly
broadens scope.
- Overlap was checked against `docs/skills.md` and the existing
`plugins/<plugin>/skills/` trees.
- The skill boundary is explicit: existing-skill revision, domain, tool, or
router.
- The `description` activates on the right requests and excludes nearby ones.
- `SKILL.md` stays focused on trigger boundary, ownership boundary, workflow or
inspection order, defaults, validation, and handoffs.
- The root teaches workflow, defaults, validation, and handoffs rather than
reciting commands or product facts.
- Any reference file has a narrow load condition and does not carry core
defaults that the root needs.
- Any reference file supports one branch, failure domain, or execution mode
instead of acting like a second root skill.
- Any script has a deterministic job and a clear run condition.
- Konnect MCP guidance is a preferred live-inspection path, not a hard
dependency.
- The skill preserves the user's existing declarative toolchain unless the user
asked to change it.
- The revision does not silently pull in shared scaffolding, generated
manifests, or unrelated skills.
- If the task is a review, the main issue is identified before line editing:
boundary drift, root bloat, reference bloat, drift risk, weak validation, or
poor handoffs.
- The overfitting, minutiae, and progressive-disclosure tests were run before
calling the skill done.
## Handoffs
- Hand off broad Konnect request classification to `konnect-platform-router`
when the authoring question is really "which existing skill should own this?"
- Hand off product diagnosis or implementation details to the relevant domain
or tool skill once the authoring boundary is settled.
- Use existing skills as boundary examples, not as templates to copy verbatim.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |