Automating My Homelab Workflow with Claude Code Skills

I started using Claude Code as an AI pair programmer. Then I realized it was something closer to a workflow automation layer — if I was willing to teach it how my lab works.

The mechanism is called Skills. And after building out about eight of them for my homelab, the individual skills aren't the interesting part anymore. The chaining is.

What Are Claude Code Skills?

Skills are custom prompt templates that Claude loads into context when you invoke them. They live as Markdown files in ~/.claude/skills/, and you invoke them by typing /skill-name in the Claude Code interface. Claude reads the file, loads all that context, then responds as if it had just been briefed by an expert on that specific task.

The Markdown file is the skill. There's no code, no API integration, no tool registration (beyond a single entry in your config). Just structured instructions that tell Claude what problem this skill solves, what context it needs, what format to produce, and what rules to follow.

Here's what the entry in my global CLAUDE.md looks like:

## Skills Available
 
### Content Creation
- `/blog-post` — Draft a technical blog post from completed infrastructure work
- `/linkedin-post` — Draft a LinkedIn post from completed infrastructure work
 
### Architecture Review
- `/platform-architect` — Review Kubernetes/ArgoCD deployments for platform engineering
  best practices, GitOps patterns, and operational excellence.
- `/security-architect` — Review deployments for security vulnerabilities, threat modeling,
  and compliance against CIS Kubernetes Benchmark, NSA/CISA Hardening, OWASP K10.
 
### Documentation Maintenance
- `/doc-sync` — Sync reference docs after a build session.
- `/phase-complete` — Mark a project phase done, sync docs, optionally chain to content.
- `/incident-runbook` — Generate a structured troubleshooting doc after resolving an incident.

That entry doesn't configure anything — it just tells Claude what skills are available so it can surface them at the right moment. The actual skill logic is in each file.

The Skills I Built and Why

Each skill represents a repeated task I was doing manually — badly and inconsistently.

/blog-post generates a full draft post for this blog from completed infrastructure work. It knows my audience (intermediate-to-advanced Kubernetes practitioners), my tone (first-person, show the rough edges), the required frontmatter schema for Velite, and the post structure I've landed on after a few iterations. Without the skill, I'd write a post outline, forget half of it, and produce something inconsistent. With it, I invoke the skill after finishing a phase and get a structured 1,500-word draft to edit from.

/linkedin-post produces a LinkedIn-formatted summary of the same work — shorter, slightly less technical, still specific. The constraint it enforces is no vague hype. Every post has to include what actually broke or what was non-obvious.

/platform-architect reviews Kubernetes and ArgoCD manifests for operational correctness: GitOps compliance, ApplicationSet patterns, resource structure, sync policies. It validates against my internal conventions — things like "all HTTPRoutes reference homelab-gateway in kube-system, not cilium-gateway in default" — alongside general Kubernetes and ArgoCD best practices.

/security-architect does the same review through a security lens: pod security standards, RBAC scope, secret handling, network policy coverage, CIS benchmark alignment. Both architect skills return severity-rated findings and a final approve/block decision.

/doc-sync runs after a build session where I've pushed changes to gitlab.com/cybersecuritybro/argo-autopilot. It reads recent git history, identifies gaps between what I built and what's documented in my reference docs, and updates argocd-deploy.md, the repo structure map, and the lessons files. Without this, my docs drift from reality within a week.

/phase-complete is the orchestration skill for my monitoring project tracker. When I finish a phase, invoking it marks the phase done in monitoring-db-project.md, chains to /doc-sync to capture the technical detail, and optionally chains to /blog-post and /linkedin-post if the phase is worth announcing.

/incident-runbook generates a structured troubleshooting doc after I've resolved something. I describe what broke and how I fixed it; the skill produces a homelabRef/troubleshooting/<incident>.md file with diagnosis steps, root cause, fix, and prevention notes. I have two of these already — from the CNPG NFS permissions incident and the Prometheus scrape label issue.

What Makes a Skill Actually Useful

The first few skills I wrote were too generic. "Review this Kubernetes manifest" isn't a skill — it's a prompt. A skill needs to be opinionated about your specific environment.

The thing that made /platform-architect useful wasn't adding general Kubernetes best practices (Claude already knows those). It was adding lines like:

Gateway name must be homelab-gateway in namespace kube-system. HTTPRoutes referencing cilium-gateway in default will not route correctly.

And:

SharedResourceWarning means two ArgoCD apps manage the same resource. Check exclude patterns in the infrastructure ApplicationSet — pattern should be '{**/kustomization.yaml,**/base/**,**/overlays/**}'.

Those are things Claude would never infer without being told. They're the institutional knowledge of my specific lab. The skill is a vehicle for encoding that knowledge so I don't have to re-explain it every session.

The same principle applies to /blog-post. The useful constraints aren't "write clearly" — they're "max 120 chars for title, max 300 chars for description (Velite schema limits), use github-dark-dimmed Shiki theme for code blocks."

The Chaining Is Where It Gets Interesting

Individual skills are useful. Chained skills are where the workflow compounds.

The review-to-content pipeline looks like this:

New manifests ready
        │
        ▼
 /platform-architect ──── findings ────▶ /security-architect
        │                                        │
        └──────────── combined review ───────────┘
                              │
                    approve / block / revise
                              │
                         (if approved)
                              │
                    /phase-complete
                    ├── updates monitoring-db-project.md
                    ├── chains to /doc-sync
                    │       └── updates argocd-deploy.md + lessons
                    ├── chains to /blog-post
                    │       └── draft MDX → content/posts/
                    └── chains to /linkedin-post
                            └── post copy ready to publish

When I finish a significant phase, I can go from "manifests pushed to GitLab" to "draft blog post + LinkedIn copy + updated reference docs + phase marked complete" in a single session, without manually writing any of those artifacts.

The session memory layer makes this work. Claude maintains context within a session, so when /phase-complete chains to /blog-post, the blog skill already has everything: what was built, what was hard, what broke, what the architecture looks like. It doesn't need to be re-briefed.

What Doesn't Work (Yet)

Cross-session chaining is still manual. If I finish a review session on Monday and come back Tuesday to write the blog post, I have to invoke /blog-post explicitly and give it context — the session memory didn't carry the architectural decisions across.

The fix is better MEMORY.md hygiene. When I finish a session now, I explicitly ask Claude to write the key decisions to memory so the next session can pick them up. It's a habit I'm still building.

The other gap: there's no skill for scaffolding new applications. Every time I deploy something new to the lab, I'm writing the same boilerplate — ApplicationSet, ExternalSecret, HTTPRoute, namespace. That should be /app-scaffold, and I haven't built it yet.

Lessons Learned

Skills need institutional knowledge, not general knowledge. The more specific you make a skill to your actual environment, the more useful it becomes. Generic prompts are prompts. Opinionated prompts with your specific conventions are skills.

The CLAUDE.md + memory + skills stack compounds. CLAUDE.md gives Claude your environment context. Memory gives it session persistence. Skills give it task-specific instructions. All three together mean you spend less time re-explaining context and more time on the actual work.

Write the skill from a bad experience, not a theoretical one. My best skills came from "I just did this manually and it took too long" or "I keep forgetting to include X when I write Y." If you haven't done a task enough times to know what goes wrong, you don't know enough to write a good skill for it.

Chain early. The value multiplies when skills trigger other skills. A skill that just produces output is useful. A skill that produces output and kicks off three more things is a workflow.

What's Next

Skills are a good start, but they're still prompt templates. I invoke them manually. I decide when to chain them. The ceiling is me.

The next evolution is giving Claude actual tools to interact with the environment directly. An MCP server — Model Context Protocol — that exposes homelab operations as callable functions. Not "here's context about my cluster," but "here's a tool that can query ArgoCD sync status, read Prometheus alerts, and check ESO secret sync health."

At that point the workflow flips. Instead of me finishing a task and invoking a skill to document it, Claude can monitor the environment, surface problems, and handle some of the operational work without me having to initiate it.

The skills library becomes the knowledge layer. The MCP server becomes the action layer. That combination is what I mean when I talk about building toward an AI-powered infrastructure agent — not a chatbot that knows my cluster, but one that can do something about it.