Claude Code Plugins for QA: Package Reusable Test Guardrails

Claude Code plugins for QA let teams package repeatable guidance and controls instead of copying local setup between repositories. A practical QA plugin can combine a namespaced test-review skill with a deterministic hook that protects sensitive files. The package improves consistency, but it does not make agent output correct by default.

This tutorial builds a deliberately small plugin, loads it locally, tests allow and block paths, checks configuration scope, and prepares evidence for team review. Use a sandbox repository and synthetic fixtures throughout.

What Claude Code plugins can package

Anthropic documents plugins as a distribution layer for reusable Claude Code extensions. A plugin can bundle skills, custom agents, hooks, commands, and MCP configuration. Plugin skills use a namespace such as /qa-guardrails:review-tests. Bundled hooks live in hooks/hooks.json and run while the plugin is enabled. During development, load a local directory with claude --plugin-dir.

QA scenario and acceptance criteria

Our sample plugin has two responsibilities: provide a reusable checklist for changed assertions, missing negative paths, risky retries, fixture leakage, and validation commands; and block edits to a synthetic secrets file.

Define success before implementation. The skill must appear under its plugin namespace, produce consistent review headings on two sample diffs, and never claim that a review replaces a test run. The hook must allow an ordinary test-file edit, block the protected fixture, explain the denial, and leave that file unchanged.

Step 1: create the minimal plugin structure

qa-guardrails/
  .claude-plugin/
    plugin.json
  skills/
    review-tests/
      SKILL.md
  hooks/
    hooks.json
  scripts/
    protect-fixtures.ps1

Keep the manifest name stable and avoid unrelated components. Small scope makes permission review, rollback, and failure diagnosis easier.

Step 2: write the namespaced review skill

Tell Claude what evidence to inspect and which output format to return. Include explicit boundaries so a persuasive narrative is not mistaken for proof.

Review only the supplied test diff.
Report changed intent, assertion risks, missing negative paths,
fixture exposure, retry changes, and commands to validate.
Do not modify files or report a pass without test evidence.
Return Findings, Required Tests, and Open Questions.

Use two representative diffs: one safe assertion improvement and one deceptive change that weakens validation. Verify that findings cite observable changes, distinguish facts from hypotheses, and recommend deterministic checks.

Step 3: add a deterministic protected-file hook

Configure a PreToolUse hook for edit tools and call a script that inspects the target path. In this tutorial the forbidden target is fixtures/synthetic-secrets.json. Use synthetic content only; never test a guardrail with real credentials.

Keep the match narrow. An overbroad rule blocks legitimate work, while a weak substring check may miss path variations. Normalize the path and compare it with the intended repository-relative target.

Step 4: load and inspect the plugin

claude --plugin-dir ./qa-guardrails

Confirm the namespaced skill is discoverable and inspect registered hooks with /hooks. Record the plugin path, manifest revision, repository commit, and effective hook source. This evidence separates a plugin defect from stale local configuration.

Step 5: run the positive path

Ask Claude to make a harmless edit to tests/checkout.spec.ts. The hook should allow the edit. Inspect the diff and run the formatter plus focused test.

• The permitted file changes as requested.
• No unrelated file changes appear.
• The hook does not alter content.
• The focused test runs against the exact changed commit.

A hook success only means the hook raised no objection; it does not prove the edit is correct.

Step 6: run the negative path

Request an edit to fixtures/synthetic-secrets.json. The hook should block the action, provide a useful reason, and leave the file hash unchanged. Test path separators, case behavior where relevant, absolute paths, and a safe lookalike such as fixtures/synthetic-secrets.example.json.

Fail the pilot if the protected file changes, the safe lookalike is blocked without reason, or the error reveals sensitive content. Preserve before and after hashes and the hook result.

Step 7: test scope and duplicates

Hook location determines scope. Plugin hooks are active while their plugin is enabled, while user, project, local, and managed settings can contribute other hooks. Use /hooks to inspect each handler and source.

Test in a clean profile and in a profile with a similar project hook. Look for duplicate runs, conflicting decisions, and confusing messages. Anthropic documents that plugin skills remain namespaced; do not assume every component resolves collisions identically.

Step 8: validate organization controls

For managed environments, review policy with an administrator. Anthropic documents allowManagedHooksOnly, which can block user, project, and unapproved plugin hooks while allowing managed hooks and explicitly force-enabled marketplace plugins. Test approved and unapproved cases on a non-production device.

Also verify source, version, update process, rollback, and ownership. A shared guardrail needs a maintainer and change-review path.

Step 9: rerun deterministic checks

Run relevant unit, integration, and static checks independently. Capture commands, exit codes, environment, commit SHA, reports, and diffs. Repeat positive and negative hook cases after a clean restart so cached state does not hide a loading problem.

Screenshot plan

1. Minimal plugin directory and manifest.
2. Namespaced skill visible in Claude Code.
3. /hooks showing plugin source.
4. Allowed test-file edit and passing focused check.
5. Blocked synthetic protected-file edit.
6. Unchanged protected-file hash.
7. Clean-profile scope test.
8. CI report for the exact revision.

Release checklist

• Purpose and owner are documented.
• Every component has positive, negative, and failure-path tests.
• Scripts avoid logging prompts, secrets, tokens, and unnecessary paths.
• Matchers and path checks are narrowly scoped.
• Skill output separates observation from inference.
• Configuration provenance is reviewable.
• CI evidence is tied to the exact revision.
• Rollback and disable instructions are tested.
• A human approves distribution.

Common mistakes

• Trusting the skill response: review the diff and run tests.
• Testing only a block: prove legitimate edits still work.
• Using real secrets: use synthetic fixtures.
• Ignoring scope: inspect user, project, plugin, and managed sources.
• Bundling too much: start with one workflow and one guardrail.
• Skipping rollback: test removal before team rollout.

References

• Create Claude Code plugins
• Automate actions with hooks
• Claude Code configuration
• Extend Claude Code

FAQ

Does a QA plugin guarantee safe AI edits?

No. Deterministic tests, security controls, code review, and human approval remain necessary.

Why use a plugin instead of copying settings?

A plugin provides reusable packaging, a consistent namespace, and a reviewable distribution path.

How should a protected-file hook be tested?

Test allowed and blocked edits, path variants, safe lookalikes, unchanged hashes, useful errors, and restart behavior.

Can administrators restrict plugin hooks?

Yes. Managed controls can limit hook loading and allow explicitly approved plugin sources.

Conclusion

Claude Code plugins for QA work best as narrow, reviewable packages. Build one namespaced skill and one deterministic guardrail, prove positive and negative paths, inspect scope, rerun CI independently, and keep distribution behind human approval.