Skill Development: Patterns, Tests, and Best Practices

Why Skill Quality Matters

A custom skill that works once in a demo is easy. A skill that keeps working after model changes, permission updates, and teammate handoffs is much harder. This guide focuses on the engineering patterns that keep Hermes skills reliable over time.

• Design the contract before the implementation
• Make failure states explicit
• Keep side effects narrow and observable
• Test the skill at the command line and in isolation

Start with a Stable Contract

Before writing logic, define what the skill accepts, what it returns, and what it is allowed to touch. The contract should be readable without opening the implementation.

export interface DeployParams {
  service: string;
  environment: 'staging' | 'production';
  confirm?: boolean;
}

export interface DeployResult {
  success: boolean;
  summary: string;
  deploymentId?: string;
  warnings?: string[];
}

If you cannot describe the parameters and result in a small interface, the skill is probably doing too much. Split it into a planner skill and an executor skill.

Keep the Skill Small and Composable

A good Hermes skill does one job well and hands off the rest. Prefer this structure:

skill/
  index.ts           # entry point and validation
  schema.ts          # parameter schema and types
  adapters/          # API clients or filesystem helpers
  prompts/           # reusable prompt templates
  test/              # unit and smoke tests

Validate Inputs Early

Do not let malformed prompts or partial user input flow into external APIs. Validate before side effects begin.

function assertDeployParams(params: DeployParams) {
  if (!params.service) throw new Error('service is required');
  if (!['staging', 'production'].includes(params.environment)) {
    throw new Error('environment must be staging or production');
  }
}

Test at Three Levels

Level 1: Unit tests

Mock the filesystem, HTTP layer, and Hermes context. Verify branching logic and error handling.

npm test -- skill-development-best-practices

Level 2: Smoke tests

Run the skill through the real Hermes CLI with representative parameters.

hermes skill test deploy-review --params '{"service":"billing","environment":"staging"}'

Level 3: Failure drills

Simulate missing credentials, timeouts, empty input, and partial API responses. Most production incidents happen in these edges, not in the happy path.

Release Checklist

• Confirm permissions are the minimum required
• Confirm configuration keys are documented
• Confirm tests cover one success path and at least two failure paths
• Confirm CLI smoke test output is understandable
• Confirm README explains install, config, and rollback

Troubleshooting

Tests pass but the skill fails in Hermes

Your mocks are too optimistic. Add a smoke test through hermes skill test and check whether CLI serialization differs from your unit fixtures.

The skill works locally but not in automation

Check for hidden assumptions such as interactive prompts, writable home directories, or environment variables that only exist in your shell session.

The model output keeps drifting

Move from prose to a constrained JSON schema and reject invalid output before continuing.

Next Steps

• Create your first custom skill — Build a simple skill end to end
• How the self-learning loop works — See how Hermes turns experience into reusable skills
• MCP integration — Connect skills to external tools and data sources

---

Last updated: April 14, 2026 · Hermes Agent v0.8