tsh-creating-skills

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

• 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.

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 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.

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

Naming Examples

Good names (gerund form — preferred):

Avoid:

Shortening Long Names

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

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

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):

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:

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 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

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