testchimp-skills

TestChimp skill for policy-backed QA workflows (skill ≥ 1.0.0). Agents run pre-defined playbooks under references/; project-specific decisions live in plans/knowledge/policies/*.policy.md. Use with @testchimp/cli (≥ required_cli_version in SKILL.md) and TESTCHIMP_API_KEY.

Primary commands

Synonyms (same workflow): /testchimp test → run QA; /testchimp evolve (legacy /testchimp audit) → upkeep; /testchimp plan → author plans.

Thin / nested playbooks (also invokable on their own): connect-to-test-env, create-tests, execute-tests, run-smart-smoke, author-plans, fix-test-execution, fix-issue, cleanup, security scans, requirement quality, and more — see Command routing in SKILL.md.

Layout matches common single-skill repos (e.g. bunnyshell/bunnyshell-environments-skill): SKILL.md at the repository root, with references/ and assets/ beside it. name in SKILL.md is testchimp, so the install directory must be named testchimp (see Agent Skills spec — name matches directory).

Recommended install: git clone into <skills-parent>/testchimp and keep .git so agents can git pull for updates (/testchimp skill upgrade).

Claude Code plugin: run /plugin marketplace add testchimphq/testchimp-skills, then /plugin install testchimp@testchimp. It installs the same skill; update it with /plugin marketplace update testchimp instead of git pull.

Install by host

See llms-install.md for copy-paste MCP config.

Install the MCP server per project, not globally. TestChimp API keys are scoped to one project. For the hosted server (OAuth), you pick the project during sign-in; plugin installs register it at user level and bind to one project across all workspaces. For stdio, configure at project level (Cursor: .cursor/mcp.json; Claude Code: .mcp.json) with TESTCHIMP_API_KEY and TESTCHIMP_USER_ID for that project.

Entrypoint: SKILL.md — then load the matching references/*.md (and default policy under assets/policies/ when seeding).

What’s new in 1.0.x (policy-aware skill)

From v1.0.0 onward the skill is organized as a modular workflow catalog, not a handful of monolithic scripts:

1. Playbooks — battle-tested how-to in references/<workflow>.md (renamed to match catalog ids: run-qa, upkeep, run-explorechimp, instrument-truecoverage, …).
2. Policies — team overrides in the mapped repo under plans/knowledge/policies/<workflow-id>.policy.md. Init seeds defaults from assets/policies/. When a policy is missing, plans/knowledge/ai-test-instructions.md remains the fallback.
3. Composites — run-qa and upkeep declare subflows in their policy (e.g. author-plans → connect-to-test-env → create-tests → …). Agents follow the composite order and can still run a subflow alone.
4. Traceability — Plan phases mint a workflow_execution_id (ULID); plans live under plans/knowledge/workflow_plans/<workflow-id>/; upload via upsert-plans-support-file before Execute; mutating work reports via report-agent-action / inline agentTraceability. Details: references/policies-and-traceability.md.
5. CLI/MCP — workflow tools (get-policy, list-policies, upsert-policy, list-workflow-catalog, get-last-run-workflow-detail, …) plus API operation coverage (list-api-operation-services, list-api-operations, get-api-operation-detail, CLI ≥ 0.1.28). Pin @testchimp/cli to at least required_cli_version in SKILL.md.

Upgrade note: If your installed skill is older than 1.0.0, upgrade now (/testchimp skill upgrade / git pull). Policy and traceability tooling assume 1.0+.

Overview docs: QA on Autopilot (TestChimp + Claude).

Project structure

testchimp-skills/
├── SKILL.md                 # Entrypoint: preamble, routing, guardrails
├── README.md                # Install + 1.0 overview (this file)
├── LICENSE
├── bin/
│   └── testchimp-preamble-check
├── references/              # One playbook (or deep dive) per concern
│   ├── init-testchimp.md
│   ├── run-qa.md            # /testchimp run QA (synonym: test)
│   ├── upkeep.md            # /testchimp upkeep (synonym: evolve)
│   ├── implement-requirement.md
│   ├── author-plans.md
│   ├── connect-to-test-env.md
│   ├── execute-tests.md
│   ├── run-smart-smoke.md
│   ├── run-smart-regression.md  # legacy stub → run-smart-smoke
│   ├── run-explorechimp.md
│   ├── instrument-truecoverage.md
│   ├── create-policy.md
│   ├── policies-and-traceability.md
│   ├── write-smarttests.md
│   ├── cli.md
│   └── …
└── assets/
    ├── policies/            # Default policies seeded on init
    │   ├── run-qa.policy.md
    │   ├── upkeep.policy.md
    │   ├── connect-to-test-env.policy.md
    │   └── implement.policy.md
    ├── sample-mcp.json
    └── template_*.config.*

In the application repo (after init / Git sync), policies live at:

plans/knowledge/policies/
├── run-qa.policy.md
├── upkeep.policy.md
├── connect-to-test-env.policy.md
└── …

Product: testchimp.io

Installation

Repository: https://github.com/testchimphq/testchimp-skills
Default branch: main

Clone into a directory literally named testchimp under your host’s skills parent:

mkdir -p <skills-parent>
git clone https://github.com/testchimphq/testchimp-skills.git <skills-parent>/testchimp

If testchimp already exists, either update in place (see Updating) or replace:

rm -rf <skills-parent>/testchimp
git clone https://github.com/testchimphq/testchimp-skills.git <skills-parent>/testchimp

<skills-parent> by host

Copy-paste examples

Claude Code (global):

mkdir -p ~/.claude/skills
git clone https://github.com/testchimphq/testchimp-skills.git ~/.claude/skills/testchimp

Amazon Kiro (global):

mkdir -p ~/.kiro/skills
git clone https://github.com/testchimphq/testchimp-skills.git ~/.kiro/skills/testchimp

Kiro workspace (project):

mkdir -p .kiro/skills
git clone https://github.com/testchimphq/testchimp-skills.git .kiro/skills/testchimp

After install

Restart the IDE or CLI session if the skill does not appear.

Amazon Kiro — skills vs steering: This pack is a skill under .kiro/skills / ~/.kiro/skills. Steering uses .kiro/steering/ / ~/.kiro/steering/ (Steering vs Agent Skills).

Kiro / GitHub import: SKILL.md on main (Kiro import rules). For ongoing updates, prefer a git clone install so git pull works.

Slash / discovery: /testchimp. Docs: Cursor, Claude Code, Codex, Copilot skills, Kiro.

Updating

Use this when the user or workflow wants the latest skill content from main (same as /testchimp skill upgrade / /testchimp update).

1. Resolve the skill root SKILL_DIR (the directory that contains SKILL.md and .git), e.g. ~/.claude/skills/testchimp or .cursor/skills/testchimp.
2. Run:

git -C "$SKILL_DIR" fetch origin
git -C "$SKILL_DIR" merge origin/main

Or a single step (if main tracks origin/main):

git -C "$SKILL_DIR" pull origin main

3. Restart the IDE or agent session if the host caches skill files.

If SKILL_DIR has no .git (old copy-only install): run a fresh clone into a temp path, then replace the skill folder contents, or remove SKILL_DIR and re-run Installation.

Agents: Search the user machine for testchimp/SKILL.md under known parents (~/.claude/skills, ~/.cursor/skills, ~/.kiro/skills, ~/.agents/skills, project .claude/skills, .cursor/skills, .kiro/skills, .agents/skills, .github/skills) and use that directory as SKILL_DIR.

Copy-only install (fallback)

If policy forbids .git under skills, use a one-off sync (no in-place git pull afterward):

git clone https://github.com/testchimphq/testchimp-skills.git /tmp/testchimp-skills-tmp
mkdir -p <skills-parent>
rsync -a --exclude='.git' /tmp/testchimp-skills-tmp/ <skills-parent>/testchimp/
rm -rf /tmp/testchimp-skills-tmp

Repeat that block (or re-clone) when you need updates.

Usage examples

/testchimp init
/testchimp run QA
/testchimp upkeep
/testchimp implement US-12
/testchimp execute tests tests/checkout in QA
/testchimp explore
/testchimp create policy for connect-to-test-env
/testchimp skill upgrade

Natural-language equivalents still route correctly (e.g. “Write tests for this PR” → run QA; “Analyze coverage gaps and fix them” → upkeep). Full table: SKILL.md → Command routing.

MCP

Two modes supported:

1. Hosted (OAuth): https://mcp.testchimp.io/mcp with type: http or streamable-http. No API key in MCP config. User picks the TestChimp project during sign-in. Plugin manifests in this repo (.mcp.json, .cursor-plugin/plugin.json, gemini-extension.json, .codex-plugin/plugin.json) register the hosted server. Test runners still need TESTCHIMP_API_KEY in the runner process environment.

2. Stdio (local process): npx -y @testchimp/cli@latest mcp with TESTCHIMP_API_KEY, TESTCHIMP_USER_ID, and TESTCHIMP_PROJECT_ID in the server's env block. Use at project level (.cursor/mcp.json or .mcp.json) when you need per-project MCP config. Template: assets/sample-mcp.json.

During /testchimp init, agents check for an existing testchimp server (plugin or project config). If none exists, they offer hosted vs stdio and write the chosen config at project level. Full steps: references/init-testchimp.md (Workstation gate). Agents verify CLI compatibility via Preamble checks in SKILL.md.

Policy / workflow MCP tools (CLI ≥ 0.1.21, skill required_cli_version may be higher): get-policy, list-policies, upsert-policy, list-workflow-catalog, report-agent-action, get-last-run-workflow-detail.

Privacy and support

• Privacy policy: https://testchimp.io/privacy-policy
• Support: contact@testchimp.io, or open an issue at https://github.com/testchimphq/testchimp-skills/issues
• Docs: https://docs.testchimp.io