chore(claude): Generic how to skill

[cloudjumpercat]

Description

Based on Tomek's AI Gateway how to skill, this one expands it to be more of a "catchall" in case a product-specific how to skill doesn't exist.
I modified the instructions for lead in sentences from Tomek's based on Lena's PR reviews for me where she wanted a lead in sentence to give context about why we were doing something.

Notes from testing:

• I tested this on a separate branch by adding the skill.md file as context and specifically asking Claude to use it, so this may have impacted my results.
• It seemed to do most of the body and front matter correctly, I did give it a rough outline for what I wanted, plus a plugin example.
• What it didn't do well:
  • It didn't seem to follow the "Step X:" sections exactly because I had it in plan mode and I only recieved one prompt from it and I thought it would prompt me for more context while it was building the plan.
  • It added related links to the how to it created, but did not go to other pages to link back to the one it created despite this being in the instructions.
  • It converted some "Konnect"s to {{site.konnect_short_name}}, but not all of them.
  • It guessed on some UI instructions and didn't ask me if it was correct.

Preview Links

Checklist

• Tested how-to docs. If not, note why here.
• All pages contain metadata.
• Any new docs link to existing docs.
• All autogenerated instructions render correctly (API, decK, Konnect, Kong Manager).
• Style guide (capitalized gateway entities, placeholder URLs) implemented correctly.
• Every page has a description entry in frontmatter.
• Add new pages to the product documentation index (if applicable).

[netlify]

✅ Deploy Preview for kongdeveloper ready!

Name	Link
🔨 Latest commit	79b3f16
🔍 Latest deploy log	https://app.netlify.com/projects/kongdeveloper/deploys/69d56bb6eca3a60008d8ee2c
😎 Deploy Preview	https://deploy-preview-4692--kongdeveloper.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

Pull request overview

Adds a generic Claude skill to guide contributors in writing/editing how-to guides for developer.konghq.com when no product-specific skill applies, standardizing sources, workflow, style, and validation expectations across products.

Changes:

• Introduces a fallback .claude skill for authoring how-to guides under app/_how-tos/.
• Defines required authoritative sources (schemas, plugin docs, API specs, etc.) and a gated 5-step workflow (context → plan → write → review → cross-link).
• Codifies style/frontmatter/body/validation rules plus an explicit pre-output checklist.

[Copilot]

The skill says to replace every em-dash, but this file itself contains em-dash characters (—), which can cause the model to copy the exact punctuation you’re trying to prohibit; please replace the em-dashes in this skill with commas/periods (or a plain hyphen) for consistency.

Suggested change

	- **Contractions are fine** throughout — write naturally. The only exception is danger or
	- **Contractions are fine** throughout, write naturally. The only exception is danger or

[Copilot]

api-specs is a repo directory (no leading slash), so /api-specs looks like an absolute path that won’t exist in most tooling; also “the how to” should be hyphenated as “the how-to” for consistency with the rest of the skill.

Suggested change

	- **API specs:** `/api-specs` contains the source of truth for public APIs. If the how to is for a new feature, ask the contributor for a link to the schema with the fields.
	- **Terraform resources:** If the how-to is for Terraform, the following are the source of truth for public Terraform resources: https://github.com/Kong/terraform-provider-konnect, https://github.com/Kong/terraform-provider-konnect-beta, https://github.com/Kong/terraform-provider-kong-gateway, https://github.com/Kong/terraform-provider-kong-mesh. If the how to is for a new feature, ask the contributor for a link to the Terraform resource with the updated fields.
	- **API specs:** `api-specs` contains the source of truth for public APIs. If the how-to is for a new feature, ask the contributor for a link to the schema with the fields.
	- **Terraform resources:** If the how-to is for Terraform, the following are the source of truth for public Terraform resources: https://github.com/Kong/terraform-provider-konnect, https://github.com/Kong/terraform-provider-konnect-beta, https://github.com/Kong/terraform-provider-kong-gateway, https://github.com/Kong/terraform-provider-kong-mesh. If the how-to is for a new feature, ask the contributor for a link to the Terraform resource with the updated fields.

[Copilot]

This example is labeled as an hcl code block but contains a shell echo command plus HCL, which is likely to confuse contributors (and syntax highlighting); consider either making it a sh block or splitting it into a sh block that writes a file and a pure hcl block with the actual Terraform content.

Suggested change

	echo '
	terraform {
	required_providers {
	konnect = {
	source = "kong/konnect"
	}
	}
	}
	provider "konnect" {
	server_url = "https://us.api.konghq.com"
	}
	' > auth.tf
	terraform {
	required_providers {
	konnect = {
	source = "kong/konnect"
	}
	}
	}
	provider "konnect" {
	server_url = "https://us.api.konghq.com"
	}

[Guaris]

It didn't seem to follow the "Step X:" sections exactly because I had it in plan mode and I only recieved one prompt from it and I thought it would prompt me for more context while it was building the plan.
It added related links to the how to it created, but did not go to other pages to link back to the one it created despite this being in the instructions.
It converted some "Konnect"s to {{site.konnect_short_name}}, but not all of them.
It guessed on some UI instructions and didn't ask me if it was correct.

What did you ask it to do in your test? That way we can replicate it as we edit the file.

We should add some changes based on your findings:

1. It should never guess on UI instructions, but instead lets the user know it doesn't have enough information.
2. It should conver all Konnect's to {{site.konnect_short_name}} or warn a user why it didn't (thinking about errors when quotes need to be added if a variable is the first in a front matter)
3. It should get the front matter right every time.

This is all uncharted territory, but what if we defined what exact inputs we need from a user at first? Like, product area first, then any sort of PRD's, or links to Github PRs. Then we ask Claude to read/review docs in the product area. This way we can avoid a user just saying "Write a how to guide about Vault", and instead encourage a user to provide as much context as possible.

Also, you have instructions for series, I wonder if we can remove that in favor of getting individual how-to's correct first.

Let me know what you think, if you give me the prompt you used I'm happy to try it too.

[cloudjumpercat]

@Guaris Here is the prompt I used:

Create a how-to doc (using the skill.md file I'm providing) in the app/_how-tos/gateway folder. The how to should cover the use case from @app/_kong_plugins/metering-and-billing/examples/meter-api-requests.yaml and use decK examples for the plugin. Use the files in app/_how-tos/metering-and-billing for some existing examples of how tos for Metering & Billing. We're going to set the plugin up on Kong Gateway, but we'll use Konnect for the event ingestion. I'll also share a markdown document someone put together with some rough steps. I'm imagining a rough outline would be like: * set up example service and example route in the prereqs (this is already built) * in the prereqs, we'll need to mention that they'll need the ingestion endpoint in Konnect, so they will need Konnect * setup the plugin like the example * for the validation, I'm guessing that they'd need to trigger requests through the example service/route from the prereq and then they'd go to the Konnect UI to verify that the events were collected? Not quite sure, double check with the markdown guide

"what if we defined what exact inputs we need from a user at first? Like, product area first, then any sort of PRD's, or links to Github PRs. Then we ask Claude to read/review docs in the product area." I like this idea. I'll adjust the skill with your feedback and remove the info about series.