Claude Skills by insolvia-ai

How AWS authentication works for the Insolvia repo, locally and in CI. Use this WHENEVER you are about to run — or are debugging — anything that touches AWS from a developer machine: `terraform plan/apply` against any `infra/envs/*`, `docker` build/push to ECR, the `scripts/bootstrap-*` and `scripts/dev-aws-*` scripts, `aws` CLI calls, or any local step that needs Insolvia's AWS account. Trigger it the moment you see a credential error — "No valid credential sources found", "no EC2 IMDS role ...

Repo rule. Name every AWS resource in Insolvia as [project]-[env]-[component]-[identifier] — lowercase kebab, environment always second, component named for what it serves. Covers the per-resource-type patterns, the global-uniqueness suffix S3 needs, the required tags, and which resources cannot be renamed without destroying data. Use before creating or renaming any AWS resource, writing a new Terraform module, adding a service, or widening the deploy role's ARN patterns in infra/envs/ci-trust.

How to add or remove a required status check on `main` yourself, instead of asking a human to click through repo settings. Use this whenever a task means changing the `protect-main` ruleset — "make the Marketing site check required", "add a PR check to the ruleset", "gate merges on the API service job" — or diagnosing a PR stuck on "Expected — waiting for status to be reported". Trigger it the moment you rename a job `name:` or a matrix leg in any `*-pr.yml`, because the ruleset matches check...

How to change what the Insolvia CI deploy role is allowed to do — and why those changes can't be applied by CI. Use this WHENEVER a change touches the GitHub Actions deploy role's IAM permissions: editing infra/envs/ci-trust/main.tf (the OIDC provider / insolvia-shared-deploy-role role / its policy), or diagnosing a deploy that fails with an IAM AccessDenied. Trigger it the moment you see "not authorized to perform: <service>:<Action>" / "no identity-based policy allows" in a staging, prod, o...

How Insolvia ships — and the rule that deploys happen in CI, never from your CLI. Use this whenever a task is about deploying, shipping, releasing, or "applying" infrastructure/services to staging or prod: "deploy to prod", "ship the API", "apply the terraform", "push a new version live", "run terraform apply", "update the lambda", "release". Read it BEFORE running any `terraform apply`, `docker push` to ECR, `aws lambda update-function-code`, or `aws`/`gh` deploy command against staging or p...

How to take a new @insolvia-ai/design-system or @insolvia-ai/tokens version into this repo — and the rule that the packages themselves are NOT here to edit. Use this whenever a task means changing a shared component (Button, Field, Card, Select…), changing a design token or colour, or picking up a design-system release: "update the design system", "bump tokens", "change the button's padding", "make the brand colour warmer". Reach for it BEFORE searching for packages/insolvia_design_system, wh...

How to add a new package, app, or backend service to the Insolvia monorepo. Use this when scaffolding a new buildable unit — "add a package", "create a new app", "scaffold a service", "new shared library", "spin up services/<x>" — so it lands with the workspace wiring, the README + CLAUDE.md pair, the CI workflows, and the infra entry the repo expects. Reach for it before creating the directory, so nothing is missed.

How to write the title and body of an Insolvia pull request. Use this BEFORE running `gh pr create`, `gh pr edit --body`, or `gh stack submit` — and whenever a task says "open a PR", "write the PR description", "update the PR body", "describe these changes", or asks you to summarise a branch for review — and whenever a PR is part of a stack, because every body in a stack must carry the stack tree and `gh stack submit` will have overwritten it. Reach for it the moment you finish the code and s...

The catalogue of Insolvia's repo scripts and WHICH one to run WHEN — they are the project's tools, not incidental files. Use this the moment a task involves setting up or running any part of the monorepo locally, provisioning or wiping this machine's dev AWS resources, bootstrapping an environment, or deploying: "set up my dev environment", "get the API running", "reset/clear my dev database", "run the marketing site / Storybook / the app", "deploy to prod / staging", "seed the ECR image", "a...

How Insolvia tests — which shape applies where, where a new test file goes, and the per-stack conventions that are easy to get subtly wrong. Use this BEFORE writing or changing any test in this repo: a pytest test under services/api or services/mailer, a Jest test in apps/insolvia_app, a Vitest test in packages/insolvia_api_client, or a Playwright spec under e2e/. Reach for it the moment a task says "add a test", "write tests for", "improve coverage", "this needs test coverage", or when you h...

Run a piece of work as an ORCHESTRATOR of sub-agents instead of doing it all inline: decompose the task, dispatch scoped sub-agents — each on the cheapest model that can do its piece well — then verify and synthesize their results. The work to perform is whatever is passed as the skill's argument (`/orchestrate <work>`). Also use whenever the user asks to "orchestrate", "coordinate agents", "fan out", "parallelize", or "delegate" a task, or hands over a large multi-part job — a repo-wide audi...

Which GitHub account `gh` and `git` act as in this repo, and how to keep it right on a developer machine that holds more than one GitHub account. Use this BEFORE any GitHub write — `gh pr create/edit/merge`, `gh api` with a method, `gh run rerun`, `gh stack submit`, `git push`, turning on auto-merge — and the moment one fails with "Resource not accessible by integration", "Permission to insolvia-ai/… denied to <user>", HTTP 403/404 on an `insolvia-ai` repo, "must have admin rights", GraphQL `...