Guide ID	T-3
Audience	Developers, all users
Prerequisites	T-1: Creating Your First Skill
Time	15 minutes
Difficulty	Intermediate

Skill Format Guide

Every skill in GSD Skill Creator follows a specific file format: Markdown with YAML frontmatter. This guide covers the official Claude Code format fields, the extension fields added by GSD Skill Creator, how to write effective descriptions that maximize activation accuracy, and the complete file structure for a well-organized skill.

Official Claude Code Fields

These fields are defined by the Claude Code specification and work natively in any Claude Code environment. They control core behavior like naming, invocation, and tool access:

Field	Type	Required	Description
`name`	string	Yes	Unique identifier. Must match the directory name. Lowercase, hyphens, digits only.
`description`	string	Recommended	What the skill does and when to use it. 1-1024 characters.
`user-invocable`	boolean	No	If true, users can invoke with /skill-name. Default: true.
`disable-model-invocation`	boolean	No	If true, Claude will not auto-load this skill. Default: false.
`allowed-tools`	string	No	Comma-separated list of tools Claude can use without asking.
`model`	string	No	Model override: sonnet, opus, haiku, or inherit.
`context`	string	No	Set to "fork" to run in an isolated subagent context.

Extension Fields

GSD Skill Creator adds extension fields that enhance skill management. These fields are stored under metadata.extensions.gsd-skill-creator to avoid polluting the official namespace. Skills work in Claude Code even without them — they add management capabilities on top:

Field	Type	Description
`triggers.intents`	string[]	Intent patterns that activate the skill
`triggers.files`	string[]	File glob patterns that activate the skill
`triggers.contexts`	string[]	Context keywords that activate the skill
`triggers.threshold`	number	Minimum relevance score (0-1, default 0.5)
`enabled`	boolean	Whether skill is active (default true)
`version`	number	Auto-incremented on updates
`extends`	string	Parent skill name to inherit from
`createdAt`	string	ISO timestamp of creation
`updatedAt`	string	ISO timestamp of last update

Writing Effective Descriptions

The description field is the single most important factor in activation accuracy. Claude uses it to decide when to auto-activate your skill during conversations. A well-written description dramatically improves how reliably the skill triggers.

The "Use when..." Pattern

The most effective descriptions follow a two-part structure: a capability statement followed by trigger conditions using "Use when...":

# Good: Clear capability and specific triggers
description: Guides structured git commits with conventional format. Use when committing changes, preparing commit messages, or when user asks about commit conventions.

# Bad: No trigger context, vague
description: Guide for git commit patterns (seen 5 times).

Do and Don't

Do	Don't
Include a "Use when..." clause	Use generic descriptions
Add specific keywords users mention	Include occurrence counts
Keep under 150 characters	Put trigger info only in skill body
Describe observable triggers	Use first/second person
Use action verbs (generate, review, format)	Start with articles (a, the, an)

Checkpoint 1

Verify: Review one of your existing skill descriptions. Does it follow the "Use when..." pattern? Does it contain specific trigger keywords? If not, update the description and run skill-creator score-activation my-skill --verbose to see the improvement in activation score.

Complete Skill File Structure

A skill directory can contain multiple files. The only required file is SKILL.md:

.claude/skills/typescript-patterns/
  SKILL.md        # Required: main skill file with frontmatter + content
  reference.md    # Optional: supplementary reference material
  scripts/        # Optional: automation scripts
  tests.json      # Auto-generated: test cases from skill-creator test generate

Example: Complete Skill File

---
name: typescript-patterns
description: Common TypeScript patterns and best practices. Use when writing TypeScript, discussing type safety, or working with generics.
triggers:
  intents:
    - "typescript"
    - "type safety"
    - "generics"
  files:
    - "*.ts"
    - "*.tsx"
    - "tsconfig.json"
  contexts:
    - "refactoring"
    - "code review"
  threshold: 0.5
enabled: true
version: 3
extends: javascript-patterns
createdAt: "2026-01-30T10:00:00Z"
updatedAt: "2026-01-30T15:30:00Z"
---

## TypeScript Patterns

When working with TypeScript, follow these patterns:

### Type Definitions
1. Prefer interfaces over types for object shapes
2. Use generics for reusable utility types
3. Avoid `any` -- use `unknown` for truly unknown types

### Error Handling
1. Define custom error types with discriminated unions
2. Use Result types for operations that can fail
3. Leverage TypeScript's strict null checks

Checkpoint 2

Verify: Open one of your skills and confirm it has the correct structure: YAML frontmatter between --- delimiters at the top, followed by Markdown content. The name field must exactly match the directory name. Run skill-creator validate my-skill to confirm.

Name Requirements

Skill names must follow strict rules to be valid:

Lowercase letters a-z, digits 0-9, and hyphens - only
Length between 1 and 64 characters
No double hyphens (my--skill is invalid)
No leading or trailing hyphens (-skill and skill- are invalid)
Must not conflict with reserved names (Claude Code built-in commands)

Valid examples: code-review, test-generator, api-helper, docs

What's Next

Creating Your First Skill — Apply format knowledge in a hands-on tutorial
Calibrating Thresholds — Optimize activation thresholds for better accuracy