Creating Skills

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:

• Does it exist already?
• List all skills: ls -la .github/skills/
• Read existing skill frontmatter and content
• If semantically similar skill exists, STOP

• 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

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

• YAML Frontmatter (required):

• 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

• Title and Overview: Brief introduction
• When to Use: Clear triggering conditions
• Prerequisites: Required tools, setup, or knowledge
• Step-by-Step Instructions: Numbered procedures
• Examples: Concrete use cases
• Troubleshooting: Common issues
• 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:

• Verify the file structure:

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

• Validate YAML frontmatter:
• Ensure proper YAML syntax
• Required fields are present
• Name matches directory name

• 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

• 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