Testing and Debugging Skills

The Authoring-to-Execution Gap

Writing a SKILL.md is not the same as having a working skill. The gap between authoring and reliable execution is where most skill problems live: a description that is too vague to trigger correctly, a procedure step that references a tool incorrectly, a verification step that gives false positives. These problems are invisible during authoring and become obvious during use — usually at the worst possible moment.

Testing a skill is simpler than testing application code, but it requires deliberate steps. The tools are already built into Hermes: /reload-skills, skill_view, and direct invocation. Building a habit of running through these steps before relying on a skill in real work saves time and prevents errors from compounding.

Reloading Skills After Changes

The first step after any skill change is ensuring the agent's skill directory is current. Within an active session, run:

/reload-skills

This triggers a fresh skills_list() call and rebuilds the slash command registry. Without this step, the agent may be operating from a cached directory that does not reflect your recent changes. A common debugging mistake is spending time investigating a problem that was fixed in the SKILL.md but not yet reflected in the agent's loaded state because /reload-skills was not run.

After /reload-skills, confirm the skill appears in the updated directory. If it does not, check the name field in the frontmatter — a name with spaces or uppercase letters may not generate the expected slash command.

Using skill_view to Inspect What the Agent Sees

To see exactly what the agent loads at each disclosure level, use skill_view directly. This is the most reliable way to verify that your SKILL.md is being parsed and served correctly.

At Level 0, check the metadata the agent receives in skills_list(). The three fields that matter are name, description, and category. Verify that the description is 60 characters or fewer and conveys the right trigger condition. A description that is truncated at the Level 0 scan will produce a garbage signal for the agent's relevance decision.

At Level 1, run skill_view(your-skill-name) and read the output as the agent would. Go through each section: Does the When to Use section describe the right trigger conditions? Does the Procedure use real Hermes tool names? Does the Pitfalls section cover the failure modes you know about? Does the Verification section provide a concrete confirmation step?

At Level 2, if your skill has reference files, run skill_view(your-skill-name, references/your-file.md) to confirm the file is accessible and formatted correctly. Verify that the Procedure steps that reference this file name it correctly — a mismatch between the step text and the actual filename causes the agent to fail to retrieve the reference.

Common SKILL.md Authoring Errors

Five errors appear repeatedly in hand-authored skills and in skills generated by /learn from ambiguous source material.

Description over 60 characters: The most common error and the easiest to overlook. Count the characters. Tools that display descriptions may wrap long text without indicating truncation, making the issue invisible until you check the Level 0 output directly. If a skill is not triggering in contexts where it should, check the description length first.

Missing body sections: Every SKILL.md must have all four sections — When to Use, Procedure, Pitfalls, Verification — in that order. Omitting Pitfalls (common when authoring from documentation that does not discuss failure modes) or Verification (common when the success state feels obvious to the author) breaks compatibility with tools that parse skills programmatically. Add placeholder content if you do not have real content yet: "Pitfalls: None known yet. Update after first use."

Invented commands in Procedure steps: Steps like "deploy the application using the deployment tool" or "run the integration test suite" reference capabilities that may not exist or may not be named correctly. Every Procedure step must reference a real Hermes tool and a real command that can be executed in the agent's environment. Test every command in the procedure before publishing the skill.

Conditional activation misconfiguration: A skill configured with requires_toolsets: [docker] will be invisible in any session without the Docker toolset — including your local test session where Docker is not enabled. If a newly installed skill does not appear after /reload-skills, check whether its conditional activation fields are excluding it from the current session context.

Name/slug mismatch: The skill directory name, the frontmatter name field, and the expected slash command need to be consistent. The slash command is derived from the frontmatter name, not the directory name. If you create a directory called my-skill/ but the frontmatter says name: MySkill, the resulting command will be /MySkill, not /my-skill.

Media Delivery Directives

Skills can include special directives that control how output files are delivered to the user. These directives matter most in messaging platform deployments, where the default rendering of files varies by platform.

[[as_document]]: Forces a file to be delivered as an attachment rather than being rendered inline. This is critical for high-resolution screenshots, charts, or PDFs where inline rendering applies lossy compression. A skill that generates architecture diagrams should use [[as_document]] to ensure the full-resolution file is delivered rather than a compressed preview.

[[audio_as_voice]]: Promotes an audio file to a native voice message bubble on platforms that support it (Telegram, WhatsApp). Without this directive, audio files are delivered as generic file attachments. With it, they appear in the platform's native voice message UI.

Bare absolute paths: When a skill's procedure output includes a bare absolute file path (like /home/user/output/report.pdf), Hermes auto-detects the file type and delivers it natively — as an image preview, document download, or media player depending on the file extension and the platform's capabilities.

These directives are added to the Procedure or Verification sections where output is produced. They apply to the specific file reference they annotate, not to all output from the skill.

Debugging Conditional Activation

If a skill is not appearing after installation, conditional activation is the most likely cause. The diagnostic process is straightforward.

First, check the frontmatter for fallback_for_toolsets, requires_toolsets, fallback_for_tools, and requires_tools entries. Note what they require or exclude. Then check which toolsets are active in your current session — if the skill requires docker and your session does not have the Docker toolset, the skill will not appear.

To verify which toolsets are active, run hermes toolsets list. Compare the active toolsets against the skill's activation conditions. If the mismatch is intentional (the skill is designed for a different environment), the behavior is correct. If the mismatch is a mistake in the frontmatter, patch the skill with the corrected activation conditions and run /reload-skills.