SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscreating-skills

creating-skills

Agents & models

View repository

Updated 10-15 21:12

About this skill

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

    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