tsh-creating-skills

name	tsh-creating-skills
description	Create new skills (SKILL.md) for GitHub Copilot. Provides naming conventions (gerund form), description guidelines, body structure, progressive disclosure patterns, templates, and validation checklists. Use when creating, reviewing, or updating SKILL.md files, or when discussing skill design and organization.
user-invocable	false

Creating Skills

Creates well-structured, reusable skills for GitHub Copilot. Enforces naming conventions, content structure, and progressive disclosure patterns based on the Agent Skills specification and best practices.

Core Design Principles

A skill is a folder containing a `SKILL.md` file with YAML frontmatter and Markdown instructions. Skills provide **procedural knowledge** — step-by-step workflows, domain-specific context, templates, and reference materials that an agent loads on demand to perform specialized tasks.

• Skills = reusable workflows, domain knowledge, step-by-step processes, templates (SKILL.md files)
• Agents = behavior, personality, responsibilities, problem-solving approach (.agent.md files)
• Prompts = workflow triggers, task starters, reusable prompt templates (.prompt.md files)

A skill must NOT define who the agent is — that belongs in the agent file. A skill defines HOW to perform a specific task or workflow.

The context window is a shared resource. Every token in your skill competes with conversation history, other skills, and the user's actual request.

Default assumption: The LLM is already very smart. Only add context it doesn't already have.

Before adding any content, ask:

• "Does the LLM really need this explanation?"
• "Can I assume it already knows this?"
• "Does this paragraph justify its token cost?"

Write the minimum necessary to guide the agent effectively. Trim explanations of concepts the LLM already understands.

Use XML-like tags for structured content that requires explicit boundaries — principles, rules, specifications, or multi-part sections where nesting adds clarity. This ensures reliable parsing across all LLM model tiers.

Use plain Markdown for sequential content like step-by-step processes, guidelines, and reference tables where structure is already clear from headings and formatting.

When to use XML tags: Principles, rules, specifications, structured templates, sections with explicit open/close boundaries. When to use Markdown: Steps, checklists, tables, guidelines, reference lists, code examples.

Skills use a three-tier loading model:

1. Discovery (~100 tokens): Only name and description are loaded at startup for all skills — this is how the agent decides which skills to activate.
2. Activation (< 5000 tokens recommended): The full SKILL.md body is loaded when the skill is triggered.
3. Resources (as needed): Files in scripts/, references/, and assets/ are loaded only when required during execution.

Keep SKILL.md body under 500 lines. Move detailed reference material, examples, and templates to separate files. Reference those files from the SKILL.md body.

Skill Directory Structure

A skill is a directory containing at minimum a SKILL.md file:

skill-name/
├── SKILL.md              # Required: instructions + metadata
├── scripts/              # Optional: executable code
├── references/           # Optional: additional documentation
└── assets/               # Optional: templates, static resources

• The directory name MUST match the name field in the SKILL.md frontmatter.
• Keep file references one level deep from SKILL.md — avoid deeply nested reference chains.
• Name files descriptively: form-validation-rules.md, not doc2.md.

Skill Creation Process

Use the checklist below and track your progress:

Creation progress:
- [ ] Step 1: Define the skill's purpose
- [ ] Step 2: Create the skill name
- [ ] Step 3: Write the skill description
- [ ] Step 4: Write the skill body
- [ ] Step 5: Create supporting files (if needed)
- [ ] Step 6: Assemble and validate the skill

Step 1: Define the skill's purpose

Before writing anything, clarify the skill's purpose with the user. Use the vscode/askQuestions tool to gather answers to these questions in a single batch:

1. What task does this skill perform? — The core activity (e.g., "analyze test coverage", "generate API documentation").
2. What triggers activation? — When should the agent load this skill? What user requests or contexts should match?
3. What does it produce? — Expected output: a document, code changes, a report, analysis, etc.
4. What makes it distinct? — How is this different from existing skills? (List current skills for the user to compare against.)

If the user provided enough context in the conversation to answer these questions confidently, skip the clarification and proceed. Only ask about genuinely ambiguous or missing information.

Step 2: Create the skill name

Naming Formula

Use gerund form (verb + -ing) followed by the object:

{gerund-verb}-{object}

This format clearly describes the activity or capability the skill provides. It reads naturally as "this skill is about [doing something]."

Rules

Rule	Requirement
Format	Gerund form: {verb-ing}-{object}
Characters	Lowercase letters, numbers, and hyphens only (a-z, 0-9, -)
Length	1–64 characters. Aim for under 20 characters (used as /slash-commands)
Start/end	Must NOT start or end with a hyphen
Consecutive hyphens	Must NOT contain --
Directory match	Must match the parent directory name exactly

Naming Examples

Good names (gerund form — preferred):

Name	Chars	Slash command
creating-agents	15	/creating-agents
reviewing-code	14	/reviewing-code
testing-e2e	11	/testing-e2e
analyzing-tasks	15	/analyzing-tasks
designing-architecture	24	/designing-architecture
gathering-context	17	/gathering-context
finding-gaps	12	/finding-gaps

Avoid:

Pattern	Example	Why
Noun phrases	task-analysis	Passive — doesn't convey action
Vague names	helper, utils, tools	Indiscoverable — agent can't match them to tasks
Overly generic	documents, data, files	Too broad — will trigger on irrelevant tasks
Inconsistent form	Mix of code-review and creating-agents	Breaks convention — confuses pattern recognition

Shortening Long Names

When the gerund form gets too long (over ~20 chars), simplify the object — let the description field carry the specificity.

Verbose	Shortened	Strategy
analyzing-implementation-gaps (30)	finding-gaps (12)	Simpler verb + shorter object
discovering-technical-context (30)	gathering-context (17)	Broader verb + drop qualifier

Confirming the Name

When multiple valid names exist, use vscode/askQuestions to let the user choose. Present 2-3 candidates with character counts and /slash-command previews. Mark the shortest gerund-form option as recommended.

Step 3: Write the skill description

Purpose

The description field is the primary discovery mechanism. The agent reads all skill descriptions at startup to decide which skill to activate for a given task. Your description must provide enough detail for the agent to match it accurately from potentially 100+ available skills.

Rules

Rule	Requirement
Length	1–1024 characters. Non-empty.
Point of view	Always third person. Never use "I", "you", or "we".
Content	Must describe both WHAT the skill does AND WHEN to use it.
Keywords	Include specific trigger terms that help the agent identify relevant tasks.

Formula

{What the skill does — core capabilities}. {When to use it — triggers and contexts}.

Good Examples

description: "Create custom agents (.agent.md) for GitHub Copilot in VS Code. Provides templates, guidelines, and a structured process for building agent definitions. Use when creating, reviewing, or updating .agent.md files."

description: "Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction."

Bad Examples

# Too vague — agent can't determine when to activate:
description: "Helps with documents."

# Wrong point of view — causes discovery problems:
description: "I can help you process Excel files."

# Missing trigger context — agent doesn't know WHEN to use it:
description: "Processes data from various sources."

Step 4: Write the skill body

The Markdown body after the frontmatter contains the skill instructions. There are no strict format restrictions — write whatever helps the agent perform the task effectively.

Content Guidelines

Line limit: Keep the SKILL.md body under 500 lines. If approaching this limit, split content into referenced files using progressive disclosure patterns.

Structure the body with these sections (see template at ./skill.template.md):

Section	Required	Purpose
Introduction	Yes	1-2 sentences describing what the skill does.
Principles	No	Core design principles using <principles> XML tags — when the skill has foundational rules that constrain all decisions.
Process / Workflow	Yes	Step-by-step checklist and detailed instructions. The core of the skill.
Reference tables	No	Quick-reference tables for rules, patterns, or conventions.
Connected Skills	Yes	Links to related skills with brief rationale for each.

Conciseness rules:

• Only add context the LLM doesn't already have.
• Use examples instead of explanations — they convey style and expectations more efficiently.
• See examples/reviewing-code.skill.md for a complete example demonstrating conciseness.
• Provide a default approach, not multiple options. Add alternatives only when a specific condition requires them.
• Don't explain concepts the LLM already knows (e.g., what PDFs are, how REST APIs work).

Consistent terminology: Choose one term for each concept and use it throughout the skill. Don't alternate between "API endpoint", "URL", "route", and "path" if they mean the same thing.

No time-sensitive information: Don't include dates or version-dependent guidance. If you must reference a deprecated approach, use an "Old patterns" section.

Use workflows for complex tasks: Break operations into clear, sequential steps. Provide a checklist the agent can copy and track progress against.

Implement feedback loops: For quality-critical tasks, include validation steps: run validator → fix errors → repeat.

Degrees of Freedom

Match specificity to the task's fragility and variability:

Freedom Level	When to use	Example
High (text instructions)	Multiple valid approaches; decisions depend on context	Code review guidelines
Medium (pseudocode / templates)	A preferred pattern exists but variation is acceptable	Report generation with customizable sections
Low (exact scripts, no params)	Operations are fragile; consistency is critical	Database migrations, file format validation

Step 5: Create supporting files (if needed)

When the SKILL.md body approaches 500 lines, or when the skill includes resources that should be loaded on demand:

File type	Location	Purpose	Load behavior
Templates	Skill root or assets/	Output format templates the agent fills in	Loaded when agent needs to produce output
Reference docs	references/	Detailed specs, API docs, domain knowledge	Loaded when agent needs specific details
Scripts	scripts/	Executable utility scripts	Executed (not read into context) — saves tokens
Examples	Skill root or references/	Input/output examples, sample files	Loaded when agent needs to understand expected format

File reference rules:

• Use relative paths from the skill root: ./references/REFERENCE.md
• Keep references one level deep from SKILL.md — avoid nested reference chains
• Make clear whether the agent should execute a script ("Run analyze.py") or read it as reference ("See analyze.py for the algorithm")
• Include a table of contents in reference files longer than 100 lines

Step 6: Assemble and validate the skill

Use the ./skill.template.md template to build the SKILL.md file. See examples/reviewing-code.skill.md for a complete filled-in example.

After assembling the skill, use vscode/askQuestions to run a final review with the user. Present the proposed name, description, and a summary of the skill's workflow steps. Ask the user to confirm or request changes before finalizing.

Then validate against this checklist:

Validation Checklist

Validation:
- [ ] Frontmatter: `name` is valid (gerund form, lowercase, hyphens, ≤64 chars)
- [ ] Frontmatter: `name` matches the parent directory name
- [ ] Frontmatter: `description` describes WHAT the skill does and WHEN to use it
- [ ] Frontmatter: `description` is in third person (no "I", "you", "we")
- [ ] Frontmatter: `description` includes specific trigger keywords
- [ ] Body: Under 500 lines total
- [ ] Body: Introduction is 1-2 sentences
- [ ] Body: Process/workflow has a trackable checklist
- [ ] Body: Only adds context the LLM doesn't already have
- [ ] Body: Uses consistent terminology throughout
- [ ] Body: No time-sensitive information
- [ ] Body: XML tags (if used) are properly opened and closed
- [ ] Body: Connected Skills section references existing skills
- [ ] Files: Supporting files are one level deep (no nested reference chains)
- [ ] Files: Template files (if any) use XML tags for structured sections
- [ ] Files: Reference files over 100 lines have a table of contents
- [ ] Testing: Skill tested with real usage scenarios

Common Patterns

For standard workflow patterns (checklists, templates, conditional workflows, feedback loops), see references/common-patterns.md.

Anti-Patterns to Avoid

Anti-pattern	Why it's harmful	Fix
Over-explaining known concepts	Wastes tokens; agent already knows what PDFs are	Remove. Only explain project/domain-specific knowledge
Offering too many options	Confusing; agent may pick wrong one	Provide a default, with escape hatch for edge cases
Deeply nested references	Agent may partially read files at depth > 1	Keep all references one level deep from SKILL.md
Vague file names	doc2.md, helpers.md	Use descriptive names: form-validation-rules.md
Windows-style paths	Breaks on Unix systems	Always use forward slashes: scripts/validate.py
Inconsistent naming within collection	Confuses pattern recognition; breaks discoverability	Use gerund form consistently for all skill names
Magic numbers in scripts	Agent can't determine the right value	Document why: TIMEOUT = 30 # HTTP requests typically complete within 30s

Connected Skills

• tsh-creating-agents - to understand how skills relate to agent definitions and avoid overlap
• tsh-creating-prompts - to understand how prompts reference and trigger skills
• tsh-technical-context-discovering - to discover existing skill patterns in the project before creating a new one
• tsh-codebase-analysing - to analyze existing skills and identify conventions to follow
• tsh-creating-instructions - to understand when project rules belong in instruction files rather than skill content