Bring an existing MCP plugin into full alignment with the homelab canonical plugin spec. Use when the user wants to update a plugin to current standards, replace stale scaffolding with the `plugin-templates` repo, reconcile manifest drift, standardize Docker and CI files, or turn a review report into a concrete alignment plan and implementation.
From plugin-labnpx claudepluginhub jmagar/claude-homelab --plugin plugin-labThis skill uses the workspace's default tool permissions.
references/alignment-report-template.mdreferences/alignment-targets.mdreferences/verification-commands.mdProvides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Calculates TAM/SAM/SOM using top-down, bottom-up, and value theory methodologies for market sizing, revenue estimation, and startup validation.
Align an existing plugin to the current homelab canonical spec.
When the user does not provide full context, assume:
~/workspace/plugin-templates/~/workspace/plugin-templates/py/, ~/workspace/plugin-templates/rs/, or ~/workspace/plugin-templates/ts/ depending on the plugin's runtimeDo not begin editing from vague assumptions.
Start with one of:
docs/reports/plugin-reviews/If no review exists, perform a quick audit of the canonical surfaces before planning edits. Check that the key files are present and structurally sound before committing to a full alignment plan.
Prioritize these ten surfaces in order:
Correct alignment means plugin.json (or Cargo.toml / pyproject.toml / package.json) carries the same version string as the Git tag and as any version field in CHANGELOG.md. The name, description, and mcp_version fields match the canonical schema. Drift looks like a plugin.json version frozen at 0.1.0 while the package manifest is at 1.3.0, or a mcp_version field referencing a superseded protocol revision.
.env.example and Runtime ContractCorrect alignment means every environment variable the plugin reads at runtime appears in .env.example with a descriptive placeholder value and an inline comment explaining what it does. Drift looks like variables present in entrypoint.sh or application code that are absent from .env.example, or stale variables in .env.example that the application no longer reads.
Correct alignment means a two-stage build: a builder stage that compiles or installs dependencies, and a minimal runtime stage that copies only the production artifact and runs as a non-root user. Drift looks like a single-stage build that ships compilers and dev dependencies into the final image, a USER root in the runtime stage, or base images pinned to latest instead of a digest or minor-version tag.
docker-compose.yamlCorrect alignment means the service stanza references env_file: .env, defines a healthcheck with the canonical interval/timeout/retries defaults, exposes only the required port, and uses named volumes for any persistent data. Drift looks like inline environment: blocks that duplicate .env.example values, a missing healthcheck, or bind-mounts to absolute host paths that break portability.
entrypoint.shCorrect alignment means the script validates every variable listed in .env.example before starting the server, exits with a non-zero code and a clear error message for any missing variable, and ends with exec "$@" or an equivalent direct handoff to the server process. Drift looks like missing variable checks, silent failures when a required var is unset, or a sleep-loop health-wait that masks startup errors.
JustfileCorrect alignment means the canonical targets exist: build, up, down, logs, test, lint, and clean. Each target delegates to the correct underlying tool (Docker Compose, the language test runner, etc.) with no hardcoded project-specific paths that would break in another repo. Drift looks like missing targets, targets that call docker-compose (v1 binary) instead of docker compose (v2 plugin), or targets with inline logic that belongs in a script.
Correct alignment means hooks.json (or lefthook.yml) references only scripts that exist under hooks/scripts/, every referenced script is executable, and the hooks cover at minimum: env-file permission check, no-baked-env check, and ignore-file sync. Drift looks like hook entries pointing to deleted scripts, hooks that are defined but never triggered because the glob is wrong, or missing hooks that allow .env to be committed.
Correct alignment means .github/workflows/ci.yaml runs lint, test, and build on every pull request, uses the canonical job structure from ~/workspace/plugin-templates/ts/ (or py/ or rs/), and pins action versions to a SHA or tagged release. Drift looks like workflows that only run on push to main, unpinned @main action references, or a workflow that skips the build step and ships untested code.
Correct alignment means tests/test_live.sh (or the language-equivalent) exercises at least one real tool call against a running container, asserts a non-error HTTP response from /health, and exits non-zero on failure. Drift looks like a test file that is present but contains only echo "TODO", tests that require manual env setup with no documented steps, or tests that always pass because they never assert anything.
Correct alignment means README.md covers installation, configuration (referencing .env.example), and usage; CLAUDE.md describes the plugin's tools and any gotchas for AI assistants; any slash commands in commands/ have correct frontmatter; agents in agents/ reference real tool names. Drift looks like a README that describes a different plugin's setup flow, a CLAUDE.md that lists tool names that no longer exist, or command files with stale allowed-tools entries.
When aligning files:
~/workspace/plugin-templates/ for shared plugin-contract files (hooks, CI structure, check scripts)~/workspace/plugin-templates/py/, ~/workspace/plugin-templates/rs/, or ~/workspace/plugin-templates/ts/ for runtime and language-toolchain filesDo not erase a deviation just because it differs. Preserve it when it is clearly intentional and still valid. Document preserved deviations in the alignment report.
Write a concrete alignment plan before making broad edits.
The plan must separate:
Make changes in an order that reduces churn:
Do not claim full alignment unless the final files and verification steps support it.
Write the alignment summary to:
docs/reports/plugin-alignments/YYYYMMDD-HHMMSS.mdUse the template at skills/align-lab-plugin/references/alignment-report-template.md. Include:
Run the strongest available local checks after alignment. Use the concrete commands in skills/align-lab-plugin/references/verification-commands.md.
Required checks:
# Validate plugin manifest JSON is well-formed
jq . .claude-plugin/plugin.json
# Check version appears consistently
grep -r "\"version\"" plugin.json package.json pyproject.toml Cargo.toml 2>/dev/null
# Shell syntax check on all shell scripts
bash -n entrypoint.sh hooks/scripts/*.sh
# YAML lint on CI workflow
yamllint .github/workflows/ci.yaml
# Docker Compose config validation
docker compose config --quiet
# Env var coverage check (vars in entrypoint but not in .env.example)
grep -oE 'required_var "[A-Z_]+"' entrypoint.sh | sort
grep -oE '^[A-Z_]+=' .env.example | sort
State clearly what was and was not verified. If a check requires a running container or network access, note it as deferred.