thesoftwarehouse/copilot-collections/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

<principles>

<what-is-a-skill> 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. </what-is-a-skill>

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

<xml-syntax> 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. </xml-syntax>

<progressive-disclosure> 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. </progressive-disclosure>

</principles>

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

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.

</naming-conventions>

Step 3: Write the skill description

<description-guidelines>

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

</description-guidelines>

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

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

</body-guidelines>

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:

<supporting-files>