Skills Design Patterns — How to Write SKILL.md and Trigger Conditions

Designing Skills well allows Claude to automatically function as “an expert who knows how to write in this project” in specific contexts. This page covers SKILL.md format, design principles, directory structure, and how to register skills with the harness — in order.

---

What Are Skills?

Skills are “role definition documents” that Claude automatically references in specific contexts. Unlike commands that the user explicitly invokes, Claude judges the nature of the task and loads the appropriate skill.

Skill files are automatically added to Claude’s system prompt. As a result, Claude operates not by “answering as a general-purpose AI” but by “following the role, steps, and rules defined in this skill.”

Confirming the Difference from Commands

Aspect	Commands (/command)	Skills (SKILL.md)
Trigger	The user types /command	Claude auto-loads by judging the situation
Invocation	Explicit and intentional	Implicit and automatic
Purpose	Execute an entire workflow	Define behavior in a specific context
File location	shared/commands/*.md	shared/skills/*/SKILL.md

Commands are procedure manuals for “what to do”; skills are role definitions for “what kind of expert to behave as.”

---

The Format of SKILL.md

A skill file consists of frontmatter and a body.

The Structure of frontmatter

---
name: skill-name
description: A description of the skill (referenced when Claude selects a skill)
metadata:
  short-description: A short description (for list display)
---

• name: An ID that identifies the skill. Match it to the directory name
• description: A description Claude uses when judging which tasks to use this skill for
• metadata.short-description: A short description used in harness list displays and logs

The Structure of the Body

After the frontmatter, write the instructions to Claude directly in Markdown.

---
name: docs-content
description: Skill for creating, updating, and quality-optimizing learning material documents for programming beginners
metadata:
  short-description: Beginner-friendly document writing and optimization process
---

# Document Writing & Learning Material Optimization Skill

## Role

You are a technical writer specializing in beginner-level learning materials in the programming and AI fields.

## Steps

1. Confirm the target audience's level
2. Select the document type (Tutorial / How-to / Reference / Explanation)
3. Understand the existing structure and related pages
...

## Rules

- Do not include personal anecdotes or emotional expressions
- Define technical terms at first use
...

The shared/skills/docs-content/SKILL.md in this project is a real example of this format. It defines a skill of around 650 lines, including the role, writing process, and quality checklist.

---

Directory Structure

Manage skills with one directory per skill.

shared/
└── skills/
    ├── docs-content/
    │   └── SKILL.md          # Document creation skill
    ├── blog-content/
    │   └── SKILL.md          # Blog post creation skill
    ├── i18n-sync/
    │   └── SKILL.md          # i18n sync skill
    ├── pr-review/
    │   └── SKILL.md          # PR review skill
    └── test-verify/
        └── SKILL.md          # Testing and verification skill

.claude/
└── skills/                   # Symlinks to shared/skills/ (auto-synced)
    ├── docs-content.md  →  shared/skills/docs-content/SKILL.md
    ├── blog-content.md  →  shared/skills/blog-content/SKILL.md
    └── ...

shared/skills/ is the source of truth. .claude/skills/ is automatically synced through symlinks. When adding or updating skills, only edit the shared/skills/ side.

---

Best Practices

Make Skill Names Specific

Avoid generic names; use names that make the task domain clearly identifiable.

Good example	Example to avoid
blog-content	writer
pr-review	review
docs-content	docs
i18n-sync	sync

When Claude selects a skill, it uses the description field and name as clues. Specific names prevent the wrong skill from being auto-selected.

Limit to One Role

Follow the principle of one skill, one responsibility. Avoid skills that can “both create documents and write blogs,” and define docs-content and blog-content as separate skills. Mixed responsibilities increase the risk of Claude behaving unexpectedly.

Write Steps as a Numbered List

Write clear steps in the skill’s body as a numbered list. Since Claude tries to execute the steps from top to bottom, explicitly specifying the order leads to stable quality.

## Steps

1. Confirm scope (target audience, document type)
2. Check for overlap or contradictions with existing pages
3. Design the structure
4. Write the Japanese page first
5. Conduct a fact-check
6. Translate and sync to the English page

Include a Rules Section

Explicitly state the constraints and prohibitions the skill must follow as a “Rules” section.

## Rules

- Do not run `npm run build` without explicit user approval
- Do not include personal anecdotes or emotional expressions
- Create and update the Japanese page first (English comes after)
- Do not use `we`/`our`/`us` in English content (use `I`)

Manage Exceptions with skill-waivers.md

If you want to skip a skill in specific situations, record the exception in shared/skill-waivers.md. By declaring exceptions in a separate file rather than directly modifying the skill’s rules, you can keep a clear distinction between the normal rules and exceptions.

---

Hands-on Exercise

Step 1: Check the Structure of an Existing Skill

cat shared/skills/docs-content/SKILL.md

Check the name, description, and metadata.short-description in the frontmatter, and the “Role,” “Steps,” and “Rules” sections in the body.

✅ Verify: If the file contents are displayed and include the frontmatter and role/steps/rules sections, the read was successful.

Step 2: Create a New Skill code-review/SKILL.md

Create a new skill specialized for code review.

mkdir -p shared/skills/code-review

Content for shared/skills/code-review/SKILL.md:

---
name: code-review
description: Code review skill for pull requests. Inspects the purpose of changes, scope of impact, security risks, and compliance with coding conventions.
metadata:
  short-description: PR code review
---

# Code Review Skill

## Role

As a senior engineer in charge of pull request code reviews, evaluate the quality, safety, and maintainability of changes.

## Steps

1. Get the PR overview with `gh pr view $PR --json title,body,files`
2. Check the diff of the changed files
3. Create review comments from the following perspectives:
   - Is the purpose of the changes clear?
   - Are there any bugs or security risks?
   - Does it comply with coding conventions?
   - Is the test coverage sufficient?
4. Report the review result with a judgment of "Approve / Request Changes / Comment"

## Rules

- Comment based on objective grounds, not personal preferences
- Actively point out not only issues but also good points
- When changes are needed, provide specific improvement suggestions
- Report security-related issues as the highest priority

✅ Verify: Run cat shared/skills/code-review/SKILL.md to confirm the contents are displayed.

Step 3: Check the Symlinks

ls -la .claude/skills/

Example output:

docs-content.md -> ../../shared/skills/docs-content/SKILL.md
blog-content.md -> ../../shared/skills/blog-content/SKILL.md
...

✅ Verify: If the existing skills are displayed as symlinks (->), the adapter layer is functioning correctly. The newly created code-review skill will be registered with the harness in the next step.

Step 4: Sync and Validate the Harness

npm run harness:sync && npm run harness:check

harness:sync updates the symlinks, and harness:check detects drift (deviation from expected values) in the configuration and safety rule violations.

Example output:

✓ harness:sync complete
✓ 6 skills registered
✓ no drift detected
✓ harness:check passed

✅ Verify: If harness:check passed is displayed, the skill has been registered correctly. If an error occurs, check the SKILL.md frontmatter (especially that the name field matches the directory name).

---

Summary

• Skills are role definition documents that Claude auto-loads. Unlike Commands, the user does not need to explicitly invoke them
• SKILL.md consists of frontmatter (name, description, metadata) and body (role, steps, rules)
• Skills are placed in shared/skills/<name>/SKILL.md, and .claude/skills/ is auto-synced via symlinks
• Following the one-skill-one-responsibility principle and writing specific names with clear steps and rules stabilizes Claude’s behavior
• Confirm the skill registration state with npm run harness:sync && npm run harness:check

---

Next Steps

• Agents Spec Design — Learn how to define sub-agent roles and constraints, building on skills
• Harness Testing and Validation — Move on to systematically verifying that skills function as intended

---

Frequently Asked Questions

Q: When are skills automatically loaded?

A: The timing of skill loading depends on the harness implementation. In the case of Claude Code, Claude judges which skill to reference based on the description field and the content of the task. By explicitly specifying a skill in an agent spec (shared/agents/), you can ensure a specific agent always loads a specific skill.

Q: In what language should the skill body be written?

A: In this project, Japanese is the source of truth, so skill bodies are also written in Japanese. Claude correctly understands and operates on Japanese instructions.

Q: Is any additional work required after deleting a skill?

A: After deleting the shared/skills/<name>/ directory, run npm run harness:sync to update the symlinks. Then confirm consistency with npm run harness:check. If the skill is referenced in other agent specs or CLAUDE.md, also remove those references from those files.

Q: Can multiple skills be applied to one task?

A: Yes. By referencing multiple skills in an agent spec (shared/agents/), Claude operates combining multiple skills. However, be careful that the rules do not contradict each other across skills.