Creating GitHub Copilot Agent Skills

This skill teaches you how to create effective GitHub Copilot Agent Skills for this repository.

Pre-Check: Avoid Duplication

STOP and check before creating a new skill:

1. •

   Does it exist already?

   • •List all skills: ls -la .github/skills/
   • •Read existing skill frontmatter and content
   • •If semantically similar skill exists, STOP
2. •

   Should an existing skill be expanded?

   • •If frontmatter semantically matches your use case → Update existing skill's description
   • •Add keywords to improve discoverability rather than creating duplicate
3. •

   Should existing skill content change?

   • •If frontmatter matches but content incomplete → Add section to existing skill
   • •Enhance with additional examples, procedures, or troubleshooting
   • •Update frontmatter only if significantly broadening scope

Only create new skill if:

• •No semantic overlap with existing skills
• •Addresses distinct problem domain
• •Has unique triggering conditions

Skill Structure

Directory Placement

Skills should be placed in .github/skills/ directory:

• •Project skills (repository-specific): .github/skills/skill-name/

Each skill must have its own subdirectory with a lowercase, hyphenated name that matches the name field in the frontmatter.

File Requirements

Every skill directory must contain a SKILL.md file (case-sensitive) with:

1. •

   YAML Frontmatter (required):

2. •

   Markdown Body with clear instructions, examples, procedures, guidelines, and references

Additional Resources

Skills can include:

• •Scripts (e.g., .sh, .fsx, .ps1)
• •Example files
• •Templates
• •Reference documentation

YAML Frontmatter Best Practices

The frontmatter is critical for skill discoverability and token efficiency:

Required Fields

• •

  name (string): Unique identifier, lowercase with hyphens

  • •Must match the directory name
  • •Should be descriptive but concise
  • •Example: hypothesis-driven-debugging, github-actions-failure-debugging
• •

  description (string): When and why to use this skill

  • •Should be 1-2 sentences
  • •Include trigger keywords that help the AI recognize when to load the skill
  • •Example: "Guide for debugging failing GitHub Actions workflows. Use this when asked to debug failing GitHub Actions workflows."
  • •SEO-like optimization for LLMs: Include key terms that would appear in user requests

Optional Fields

• •license (string): License for the skill (e.g., MIT, Apache-2.0)

Description Guidelines

The description is crucial for skill discoverability. Think of it like SEO for LLMs:

✅ Good descriptions (specific, actionable, keyword-rich):

• •"Guide for debugging failing GitHub Actions workflows. Use this when asked to debug failing GitHub Actions workflows."
• •"Systematic approach to investigating F# compiler performance issues using traces, dumps, and benchmarks."
• •"Step-by-step process for analyzing test failures using hypothesis-driven debugging."

❌ Poor descriptions (vague, generic):

• •"Helps with debugging"
• •"Tool for testing"
• •"Useful utility"

Token Efficiency

Skills should be concise to avoid wasting context tokens:

• •Keep instructions focused and relevant
• •Use bullet points and numbered lists
• •Avoid redundant information
• •Reference external resources rather than duplicating content
• •The agent will only load skills when relevant, so clear descriptions help prevent unnecessary loading

Skill Content Best Practices

Structure

1. •Title and Overview: Brief introduction
2. •When to Use: Clear triggering conditions
3. •Prerequisites: Required tools, setup, or knowledge
4. •Step-by-Step Instructions: Numbered procedures
5. •Examples: Concrete use cases
6. •Troubleshooting: Common issues
7. •References: Links to related documentation

Writing Style

• •Use imperative mood ("Run the test", not "You should run the test")
• •Be specific and actionable
• •Include command examples with expected output
• •Use code blocks with language identifiers
• •Highlight warnings and critical information
• •Reference tools and APIs that the agent has access to

Examples

Always include concrete examples:

• •Command invocations with flags and arguments
• •Expected output and how to interpret it
• •Common variations and edge cases
• •Links to real-world usage in the repository

Testing Your Skill

After creating a skill:

1. •

   Verify the file structure:

   bash

   ls -la .github/skills/your-skill-name/
   # Should show SKILL.md and any additional resources
   

2. •

   Validate YAML frontmatter:

   • •Ensure proper YAML syntax
   • •Required fields are present
   • •Name matches directory name
3. •

   Test skill invocation:

   • •Ask Copilot a question that should trigger the skill
   • •Verify the skill is loaded (check response for skill-specific guidance)
   • •Ensure instructions are clear and actionable
4. •

   Iterate based on usage:

   • •Monitor how often the skill is used
   • •Refine description for better discoverability
   • •Update instructions based on feedback

Examples from This Repository

See existing skills in .github/skills/ for reference:

• •hypothesis-driven-debugging: Systematic failure investigation
• •Additional skills may be added over time

References

• •GitHub Copilot Agent Skills Documentation
• •Agent Skills Open Standard
• •Community Skills Collection