AI Skills

# Conventional Commits

## Format

```text
<type>(<scope>): <subject>

<body: what changed and why, wrapped at ~72 columns>

<footers>
```

- **type** — one of:

  | Type | Use for |
  |---|---|
  | `feat` | A new capability for users |
  | `fix` | A bug fix |
  | `docs` | Documentation or content only |
  | `refactor` | Code change with no behavior change |
  | `perf` | Performance improvement |
  | `test` | Adding or fixing tests only |
  | `build` | Build system, dependencies, packaging |
  | `ci` | CI configuration |
  | `chore` | Maintenance that fits nothing above |
  | `revert` | Reverting an earlier commit |

- **scope** — optional, a short noun for the area touched (`tools`, `cli`, `auth`, `content`). Reuse the scopes already present in `git log` instead of inventing new ones.
- **subject** — imperative mood ("add", not "added"/"adds"), no trailing period, at most ~60 characters, lowercase start unless it is a proper noun.
- **body** — explain *why* and anything a reviewer could not see from the diff. Skip it for trivial changes.
- **footers** — `BREAKING CHANGE: <what breaks and how to migrate>` (or `!` after the type: `feat(api)!:`), `Refs: #123`, `Co-authored-by:` lines.

## Workflow

1. Look at the staged diff (`git diff --cached`); if nothing is staged, look at `git status` and ask what should go in.
2. Check `git log --oneline -20` to match the project's language, scopes and casing. If the project writes messages in another language, keep the type and scope in English and follow the project for the rest.
3. If the diff mixes unrelated intents (a feature plus an unrelated fix plus formatting), propose splitting it into separate commits and list which files go in each.
4. Write the message. Pick the type by the user-visible effect, not by which files changed: a bug fixed by refactoring is `fix`.
5. Only run `git commit` if the user asked you to commit; otherwise return the message.

## Examples

```text
feat(cli): install skills into .claude/skills

`skills name=<skill> install=1` writes every file of the skill to disk, so
agents can pick it up without a manual download.
```

```text
fix(invoice): round totals per line before summing

Rounding only the final total produced a one-cent difference from the
PDF rendered by the bank.
```

```text
feat(api)!: drop the v1 endpoints

BREAKING CHANGE: /v1/* now returns 410. Clients must use /v2, which has
been available since March.
```

## Avoid

- Vague subjects: `fix: bug`, `chore: updates`, `wip`.
- Listing files in the subject instead of the intent.
- A `feat` that is really internal (`refactor`) — it pollutes the changelog.

# Kubernetes manifest review

## Workflow

1. Identify each object (`kind`, `metadata.name`, namespace). If the user shared a Helm chart, review the rendered output (`helm template`) when possible, not just `values.yaml`.
2. Go through the checks below for every workload (Deployment, StatefulSet, DaemonSet, Job).
3. If the user reported a symptom, start from the symptom table and connect it to the manifest.
4. Answer with a verdict, findings ordered by severity, and a corrected YAML snippet for each **high** finding.

## Checks

**Selectors and labels**
- `spec.selector.matchLabels` matches `template.metadata.labels`, and every Service `selector` matches the pods it should reach. A mismatch means a Service with no endpoints.

**Probes**
- `readinessProbe` present on anything behind a Service.
- `livenessProbe` checks only the process itself. A liveness probe that calls the database or another service is a **high** finding: when the dependency fails, every pod restarts in a loop.
- Slow-starting apps use a `startupProbe` instead of a huge `initialDelaySeconds`.

**Resources**
- Every container has `requests` for CPU and memory, and a memory `limit`.
- A CPU `limit` causes throttling, not kills; flag it only if it is very close to the request on a latency-sensitive service.
- `requests` far above real usage waste capacity; far below cause noisy neighbours and evictions.

**Rollouts and availability**
- Deployments with `replicas: 1` in production → suggest at least 2 plus a `PodDisruptionBudget`.
- `strategy.rollingUpdate.maxUnavailable: 0` for services that must not drop capacity during deploys.
- Image tags are immutable versions (`1.4.2` or a digest), never `latest`.

**Security**
- `securityContext`: `runAsNonRoot: true`, `allowPrivilegeEscalation: false`, `readOnlyRootFilesystem: true` where the app allows it, capabilities dropped.
- No `privileged: true` or `hostNetwork`/`hostPath` without a stated reason.
- Secrets are referenced from `Secret` objects or an external secret store, never written in plain text in a ConfigMap or env value. Remind that a Secret is only base64-encoded unless etcd encryption is enabled.

**Scaling**
- An HPA targets a workload that has CPU/memory `requests` (utilization is computed against requests).
- `minReplicas` of the HPA is not lower than what the PodDisruptionBudget needs.

## Symptom table

| Symptom | Look at |
|---|---|
| `Pending` | Requests larger than any node, missing PVC/StorageClass, node selectors or taints |
| `ImagePullBackOff` | Image name/tag, registry credentials (`imagePullSecrets`) |
| `CrashLoopBackOff` | App startup errors (`kubectl logs --previous`), liveness probe too strict, missing config |
| `OOMKilled` | Memory limit vs real usage |
| Service returns nothing | Selector vs pod labels, readiness failing (`kubectl get endpoints`) |
| Slow but no errors | CPU throttling from a tight CPU limit |

## Output format

```markdown
## Verdict
Ready | Ready with fixes | Not ready — one sentence why.

## Findings
1. **[high]** `Deployment/api` — liveness probe calls `/health/db` → restart loop when the database is down. Fix: point liveness to `/live` and move the DB check to readiness.

## Suggested patch
(YAML for the high findings)
```

# Technical guide writer

Write guides that explain *why* before *how*, are accurate for the current version of the technology, and can be read in one sitting.

## 1. Research first

- Start with **primary sources**: official docs, changelogs, specifications, the project's repository. Then independent sources (reviews, postmortems, critiques), and say in the text when a claim comes only from the vendor.
- For anything that evolves (languages, cloud services, CLIs), confirm the **current stable version** and state from which version each feature applies ("since 1.11").
- Open every link you plan to cite. Drop the ones you could not verify.
- Base code examples on official docs; mark your own adaptations.

## 2. Structure

Use `##` for sections (they become the table of contents) and `#####` for subsections. Default outline, adapt when the topic needs it:

1. **What it is** — one-paragraph definition plus where the name comes from.
2. **The problem** — what was painful before it existed.
3. **How it works** — the mechanism, with a diagram; a table if there are types or variants.
4. **In practice** — one to three short examples the reader can run, ideally a local lab that needs no paid account.
5. **Limits** — what it does not do, caveats, what you could not verify.
6. **When to use it (and when not)** — a two-column table with concrete alternatives.
7. **Videos** and **References** — each link with one line of context.

For operational topics, a **Symptoms and causes** table (symptom → usual cause → command to investigate) is often the most useful section.

## 3. Style

- Direct sentences; no marketing adjectives. Vendor numbers always carry the caveat.
- Bold the one idea per section the reader must remember.
- Tables for comparisons, lists for steps, prose for reasoning.
- 2 to 4 Mermaid diagrams per guide (` ```mermaid ` blocks). Each must explain something the text alone would leave confusing — flows, sequences, architecture. Quote labels that contain punctuation, and use `<br/>` for line breaks.
- Code blocks always have a language tag and comments in the reader's language.
- No raw HTML inside Markdown unless the target platform requires it.
- Link concepts the reader may not know to a short explanation (a glossary entry or note) rather than explaining them inline at length.

## 4. Before delivering

- Re-check every version number and date against the sources you opened.
- Render or lint the Mermaid diagrams if a tool is available; an invalid diagram usually breaks the build.
- Deliver the guide plus a short summary: sections, sources used, and open points the author should decide.

# Terraform review

Review infrastructure changes the way a careful platform engineer would before approving an apply: first what will be destroyed or replaced, then what could break later.

## Workflow

1. **Find the plan.** If the user only shared code, ask for (or run, if you have a shell and credentials are not needed) `terraform plan -no-color`. A review without the plan can only judge the code, so say so.
2. **Read destructive actions first.** List every resource marked `-` (destroy), `-/+` (replace) or `+/-` (create before destroy). For each one, quote the `# forces replacement` attribute and say whether data can be lost (databases, disks, buckets, DNS zones, KMS keys).
3. **Check the code** against [the checklist](references/checklist.md). Only report items that actually apply to the change.
4. **Write the review** in the format below.

## Output format

```markdown
## Verdict
Safe to apply | Apply with care | Do not apply — one sentence why.

## Destructive changes
- `aws_db_instance.main` will be **replaced** because `identifier` changed → data loss unless restored from snapshot.

## Findings
1. **[high]** <problem> — <file:line> — <concrete fix, with a code snippet when short>
2. **[medium]** ...

## Nice to have
- ...
```

Severity: **high** = data loss, outage, security exposure or state corruption; **medium** = will hurt on the next change (count reorder, missing pin, missing lock); **low** = style and readability.

## Rules of thumb

- A rename is not a destroy: suggest a `moved` block instead of accepting a replace caused by a new address.
- Adopting existing infrastructure goes through an `import` block, never by deleting and recreating it.
- Never recommend `terraform state rm`, `state mv` or `force-unlock` without explaining the risk and asking for confirmation.
- Do not invent provider behavior. If you are not sure whether an attribute forces replacement, say the plan is the source of truth.
- Keep findings specific: a file, a resource address, a fix. Skip generic advice that does not apply to this diff.