# Writing Skills

> Use when creating, revising, or validating Hermes skills so they are discoverable, reusable, and grounded in real successful workflows.

- Skill: `xiaohei-info/writing-skills` (Agent Skill)
- Install (CLI): `npx skillmds@latest add xiaohei-info/writing-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xiaohei-info/writing-skills/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: xiaohei-info (https://skillmd.com/u/xiaohei-info)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/xiaohei-info/writing-skills

---


# Writing Skills

## Overview

A good skill captures a reusable method, not a one-off story. It should help future sessions recognize when to load it and exactly how to use it.

Core principle: write skills from proven workflows, then verify they are clear and reusable.

## Use This When

Use when:
- creating a new Hermes skill
- updating a stale or incomplete skill
- converting a proven workflow into reusable procedural memory
- evaluating whether something should be a skill at all

## What A Skill Is

A skill is:
- a reusable technique
- a repeatable workflow
- a reference guide for a recurring task
- a compact procedure that improves future execution

A skill is not:
- a diary of one session
- raw notes with no trigger conditions
- project-specific temporary state
- something that should instead be enforced mechanically in code or tests

## Before Writing A Skill

Confirm all of these:
1. the workflow actually worked
2. it is likely to recur
3. future-you would benefit from loading it
4. the value comes from judgment/process, not just static data

## Skill Design Rules

### 1. Optimize for discovery

The `description` should primarily answer: when should this skill be used?
Do not stuff the description with the full workflow.
Trigger conditions are more important than implementation summary.

### 2. Optimize for execution

The body should include:
- what the skill is for
- when to use it and when not to use it
- concrete steps in order
- commands or tool patterns when relevant
- pitfalls and verification steps

### 3. Keep the boundary clean

Prefer:
- one clear workflow per skill
- linked references only when they truly reduce clutter
- concise wording over narrative prose

## Recommended Structure

A solid Hermes skill usually includes:
- YAML frontmatter
- Overview
- When to Use
- Steps / Process
- Pitfalls or Common Mistakes
- Verification / Expected Outcome

## Hermes-Specific Guidance

When authoring skills for Hermes:
- use Hermes tool names and workflows, not Claude/Codex-specific ones
- reference `delegate_task`, `todo`, `skill_manage`, `search_files`, `read_file`, `patch`, `terminal`, etc. where appropriate
- avoid assumptions about non-Hermes runtime features unless clearly labeled
- keep instructions compatible with Hermes categories and naming style

## Validation Checklist

Before saving or updating a skill, check:
- is the trigger condition clear?
- does the description describe when to use it?
- are the steps specific enough to follow?
- does it avoid session-specific temporary details?
- does it fit Hermes tools and conventions?
- is there any stale or platform-specific wording to remove?

## Anti-Patterns

Avoid:
- copying a foreign skill verbatim without adapting tool names and assumptions
- writing a description that summarizes the whole process instead of the trigger
- recording one-off progress as a skill
- leaving ambiguous steps that require guessing
- creating a skill when a simple memory note would be enough

## Remember

A skill should save future effort. If it won't reliably help future execution, do not turn it into a skill.