Skip to content

Creating Skills

How to create custom skills that extend the toolkit with domain knowledge and workflows.

What is a skill?

A skill is a markdown file (SKILL.md) that provides context-sensitive instructions to Claude. Skills activate automatically when the work being done matches their domain.

Quick start

The fastest way to create a skill is to use the built-in skill creator:

/vt-c-skill-creator

This walks you through creating a well-structured skill interactively.

Manual creation

1. Create the directory

mkdir -p plugins/core-standards/skills/my-skill

2. Create SKILL.md

---
name: my-skill
description: Use when [specific situation]. Provides [specific guidance].
---

# My Skill Title

## When to Use

Describe when this skill should activate.

## Guidelines

The actual instructions for Claude when this skill is active.

## Examples

Concrete examples of the skill in action.

3. Add to the manifest

Add a line to the plugin's skill-symlinks.manifest:

my-skill -> skills/my-skill

4. Install

./scripts/setup.sh --full

Skill anatomy

Frontmatter (required)

---
name: my-skill          # Unique identifier
description: Use when...  # When this skill activates
---

The name becomes the command (/my-skill). The description helps Claude decide when to apply the skill.

Body

The markdown body contains the actual instructions. Structure it with clear sections:

  • When to Use — activation criteria
  • Guidelines — the rules and patterns to follow
  • Examples — concrete demonstrations
  • Anti-patterns — what to avoid

Advanced frontmatter fields

Beyond the required name and description, skills support several advanced fields:

context: fork

Runs the skill as an isolated sub-agent that returns only its output to the parent conversation. Used by /vt-c-4-review and /vt-c-5-finalize to form independent assessments.

---
name: my-reviewer
context: fork
description: Autonomous review that runs independently.
---

Critical rule: Fork-context skills must NEVER ask interactive questions (AskUserQuestion, "Would you like...?"). The question is swallowed, the sub-agent dies silently, and the parent gets no output.

allowed-tools

Restricts the skill to only use specific tools. Useful for read-only skills that should never modify files.

allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash

skills

Declares dependencies on other skills. When this skill runs, its dependent skills are also available.

skills: [defense-in-depth, test-driven-development]

hooks

Attaches PreToolUse or PostToolUse hooks that run when the skill uses specific tools.

hooks:
  PreToolUse:
    - matcher: "Edit|Write|Bash"
      hooks:
        - type: command
          command: "~/.claude/hooks/block-writes.sh"

triggers

Lists phrases that cause the skill to auto-activate when detected in the conversation.

triggers:
  - After significant code changes
  - After design decisions
  - When rationale is explained

argument-hint

Documents expected arguments. This field is informational only (not enforced by the skill loader).

argument-hint: "[--fix | --report-only]"

Best practices

  • Be specific in the description — vague descriptions lead to wrong activation
  • Focus on one domain — don't create a skill that does everything
  • Include examples — Claude follows examples better than abstract rules
  • Test activation — verify the skill activates when expected
  • Keep it concise — skills that are too long get summarized, losing detail

Further reading