Smoke-Test Your Agent Skills with test-skill

Where this fits

You've just installed the OpenCode Skills Plugin and wired up a few skills, but you're not sure the tools actually fire. Instead of debugging a custom skill, you load test-skill and run its checklist—find_skills, use_skill, read_skill_file, run_skill_script—to confirm every plugin tool responds correctly. This is the agent equivalent of a hello world script: a zero-risk sanity check before you trust your workflow with real skills.

Why agents benefit

• End-to‑end verification – The skill exercises all four plugin tools in one pass, so you know the plugin API is intact, not just the skill loader.
• Non‑markdown file handling – read_skill_file loads example-config.json and helper-docs.md, proving your agent can parse both structured and plain text files.
• Script execution – run_skill_script runs greet and echo-args, validating that your agent can invoke external scripts and pass arguments correctly.
• Discovery check – find_skills lists installed skills, confirming your skill registry is populated and searchable.
• Isolated debugging – If a tool fails, the failure is contained to the plugin layer, not your custom skill logic—saving hours of tracing.

Practical scenarios

Onboarding a new agent runtime

You switch from one agent harness to another and need to confirm the skill plugin is compatible. Run the test checklist immediately after installation. If all steps pass, your existing skills will likely work; if not, you know the plugin layer needs attention before you port your own skills.

CI pipeline for skill plugins

Add a step to your CI that invokes test-skill on a fresh environment. This catches regressions when you update the plugin or change the agent's base image. A failing test blocks deployment, so you never ship a broken skill setup.

Teaching agents to use skills

When you build a new agent from scratch, test-skill serves as a training example. The agent learns the correct sequence of tool calls by mimicking the checklist, and you can verify it internalized the pattern by watching its trace.

Add it to your agent workflow

Install the skill with:

npx skills add joshuadavidthomas/opencode-agent-skills --skill test-skill

Then ask your agent to "run the test-skill checklist". It will execute the five steps from the README and report results. For a quick manual check, you can run:

# List all skills
find_skills
# Load the test skill
use_skill test-skill
# Read a supporting file
read_skill_file test-skill helper-docs.md
# Execute a script
run_skill_script test-skill greet

Compare before adopting

Before you rely on test-skill, compare it against alternatives: check the GitHub repo for recent commits and open issues (maintenance freshness), verify the author's other skills for consistency (quality signals), and see if a more comprehensive smoke test exists in your plugin's ecosystem. Also assess how well it fits your workflow—if you use a different plugin, this skill may not apply.

Why it is worth tracking

test-skill is a tiny but essential utility. Its value isn't in what it does—it's in what it prevents. The skill has 272 stars and an active author, indicating community trust. Watch for updates that add new plugin tools or expand the checklist. When you upgrade your agent or plugin, re‑run this skill to ensure nothing broke. It's the kind of low‑effort, high‑certainty check that saves you from silent failures. For more skills like this, browse OpenAgentSkill to see how it fits into a broader toolkit.