platform-skills

Platform Skills

A practical handbook for developers and DevOps engineers working with Kubernetes, GitOps, Terraform, GitHub Actions, cloud infrastructure, and secrets management — with an optional Claude plugin layer for interactive guidance.

What is this?

This repository is a reference handbook for developers, DevOps engineers, SREs, and platform teams. It is structured in two independent layers:

• Handbook — references/ and examples/ are the main product. Every domain has a deep-dive guide and working example assets you can copy directly into your project. Use it on GitHub, from a local clone, or as a team knowledge base.
• Claude plugin — SKILL.md and .claude-plugin/marketplace.json add an optional routing layer so Claude surfaces the right section of the handbook when you ask platform engineering questions interactively.

Both layers work independently. The plugin is optional.

Navigate

I want to...	Go to
Get started in 5 minutes	QUICKSTART.md
Full installation guide and troubleshooting	INSTALLATION.md
Read a domain guide	references/
Copy a working example	examples/
Install as a Claude plugin	Installation
Set up VSCode with or without Claude	VSCODE_INTEGRATION.md
Contribute a pattern	CONTRIBUTING.md

Domains

Domain	Reference guide	What it covers
☸️ Kubernetes	references/kubernetes.md	Cluster baseline, workload patterns, network policy, RBAC, pod security
🟥 OpenShift	references/openshift.md	Routes, SCC compatibility, operator usage, tenant isolation
🚢 Argo CD	references/argocd.md	App-of-apps design, ApplicationSet, sync control, promotion flows
🔄 Flux CD	references/flux.md	Monorepo structure, reconciliation, multi-tenancy, image automation
☁️ AWS	references/aws.md	IAM least-privilege, IRSA, EKS, resource tagging, cost allocation
🌐 Azure	references/azure.md	Workload identity, AKS, RBAC, resource tagging, Azure Policy
🏗️ Terraform	references/terraform.md	Module design, state management, testing, CI/CD integration
🚀 GitHub Actions	references/github-actions.md	Security hardening, OIDC, SHA pinning, reusable workflows
🗺️ Platform model	references/platform-operating-model.md	Ownership boundaries, promotion flows, cross-tool design
🔐 Secrets	references/secrets.md	External Secrets Operator, Sealed Secrets, provider setup, troubleshooting
🔗 Linkerd	references/linkerd.md	mTLS, proxy injection, AuthorizationPolicy, observability, multi-cluster
🐧 Linux & Networking	references/linux-networking.md	Linux admin, DNS, load balancing, VPC/VNet design, connectivity troubleshooting
🧠 Platform Mindset	references/platform-mindset.md	DevEx, friction audits, RFC/ADR, incident comms, post-mortems, capacity planning

Core principles

Every pattern in this handbook follows the same ground rules:

• Production-first — patterns are battle-tested, not theoretical
• Root-cause over symptom — troubleshooting works backwards from evidence to fix
• Explicit blast radius — every risky operation documents scope and rollback
• Security by default — least-privilege IAM, restricted pod security, SHA-pinned actions
• Rollback plans are mandatory — if you cannot safely undo it, the guide is incomplete

Troubleshooting structure

Every troubleshooting section in the handbook follows this consistent framework — from quick diagnosis to safe resolution:

Step	What it answers
Symptom	Exact error and observable behavior
Evidence	Commands to run: logs, events, status
Hypothesis	Most likely root cause
Diagnosis	Commands that confirm or rule out the hypothesis
Fix	Specific change with justification
Validation	Post-fix verification steps
Prevention	How to avoid it next time
Rollback	Safe undo path if the fix makes things worse

Installation

Browse on GitHub

No installation needed. Navigate directly:

• examples/ — copy-paste examples for all domains
• references/ — deep-dive domain guides
• SKILL.md — core patterns and routing logic

Clone for local templates