| name | k8s-at-home-research |
| description | Research Kubernetes GitOps patterns from public GitHub repositories tagged `k8s-at-home` and adapt findings to this cluster. Use before adding or upgrading apps, writing HelmRelease/Kustomization/HTTPRoute/PVC/backup manifests, comparing chart values, or investigating how homelab clusters configure an application.
user: "How do homelab clusters deploy X?" → Search topic repos, cite exemplar manifests user: "Find k8s-at-home examples for jellyfin" → Shortlist repos, compare HelmRelease patterns user: "Chart values for app-template like others use" → Code search scoped to top repos
Prefer this before inventing Kubernetes YAML when the app may exist in the k8s-at-home ecosystem. |
| compatibility | Requires network access to GitHub (REST API, `gh`, or GitHub MCP). Optional GH_TOKEN/GITHUB_TOKEN; Python 3 for the bundled repo search script. |
k8s-at-home research
When to use
- Real-world examples before authoring or upgrading cluster manifests.
- Comparing chart values, probes, persistence, routes, backups, or secrets patterns.
- User names an app and asks how k8s-at-home / homelab repos configure it.
Research is advisory: never copy secrets, domains, cluster-specific IDs, or unreviewed defaults verbatim.
Workflow
- Define target — app aliases; resource type (
HelmRelease, HTTPRoute, ReplicationSource, …); chart/image; namespace.
- Discover repos —
topic:k8s-at-home shortlist (5–10), inspect top 3–5. Query recipes: references/research-workflow.md.
- Compare exemplars — chart/version, values, probes, securityContext, resources, persistence, routes, env, secrets, Flux intervals/deps/postBuild.
- Adapt to this cluster —
kubernetes/apps/<namespace>/<app>/ with ks.yaml; ${SECRET_DOMAIN}; internal HTTPRoute parentRef envoy-internal in network; Reloader when config-backed; Recreate for RWO ceph-block; SOPS only.
- Report with evidence — cite repo/path per recommendation.
Tool routing
- kubesearch MCP first when available:
kubesearch_search_releases, kubesearch_get_release, kubesearch_grep_values, kubesearch_search_images.
Then repo_clone/repo_read_file to inspect exemplar manifests. Kubesearch queries the pre-indexed kubesearch.dev database — no topic:k8s-at-home tag needed.
- GitHub MCP second:
github_search_repositories, github_get_file_contents for repos not yet indexed by kubesearch.
- Fallback:
gh search repos <app> --topic k8s-at-home --limit 10 then scoped gh search code with repo:<owner>/<repo>.
- Repo shortlist:
python3 .agents/skills/k8s-at-home-research/scripts/search_k8s_at_home.py <term> --limit 10
- Web search only to find repo names; confirm in repository files.
- Local repo — compare against existing
kubernetes/apps/ before proposing YAML.
- Upstream chart docs for chart values — not k8s-at-home mining.
Efficiency
- Bound discovery (5–10 repos, 3–5 deep reads); scope code search with
repo: after the shortlist.
- Prefer in-session GitHub MCP repo search before shell when available.
Evaluation and output
Per source: relevance, reuse, reject (hardcoded domains, plaintext secrets, deprecated APIs, wrong storage/ingress), cluster adaptation. Quality ranking and adaptation rules: references/research-workflow.md.
Unless the user asks for raw dumps, use:
## k8s-at-home research: <target>
### Best references
1. <repo/path> — <why>
### Patterns to reuse
- <pattern> — source: <repo/path>
### Adaptation for this cluster
- <change>
### Risks / mismatches
- <item>
### Recommendation
<next step>
Scripts
Format reference: agentskills.io.
