Agent Skill Creator

Foundational skill for designing and creating composable, portable agent skills that follow modern best practices.

When to Use This Skill

Use this skill when you need to:

• Create a new agent skill for specialized workflows
• Design a skill description that properly activates in Copilot
• Organize resources (scripts, documentation, templates) for a skill
• Understand skill design principles (consolidation, composability, evaluability)
• Create tech-specific skills (.NET, TypeScript, Python, etc.)
• Validate skill structure for cross-platform compatibility

Important: Foundational Reference

This skill establishes universal principles applicable to all agent skills. For the authoritative standards and validation checklist, see Agent Skills File Guidelines.

---

Core Skill Design Principles

Before creating a skill, understand these foundational concepts:

1. Consolidation: Group related capabilities into one skill (not fragmented across many)
2. Progressive Disclosure: Keep SKILL.md focused (~500 lines); move detailed content to references/
3. Composability: Each skill works independently AND integrates with other skills
4. Evaluability: Clear triggers and measurable outcomes enable validation

See Skill Design Principles for detailed explanation and design checklist.

---

Step-by-Step Skill Creation

Step 1: Define Scope

Input needed: Skill name and high-level purpose

Ask:

• What specialized workflow or capability does this skill teach?
• What problem does it solve?
• Is this skill focused enough (not trying to do too much)?

Consolidation check: Does your skill consolidate related capabilities, or does it fragment into multiple skills?

See Skill Design Principles - Consolidation for guidance.

Step 2: Design Skill Description

Output: YAML frontmatter with name and description

The description is critical—it's how Copilot discovers and activates your skill.

Formula: [CAPABILITY] for [DOMAIN]. Use when [TRIGGER 1], [TRIGGER 2], [TRIGGER 3]. [OPTIONAL: Supported details].

Example (webapp-testing skill):

description: Toolkit for testing local web applications using Playwright. Use when asked to verify frontend functionality, debug UI behavior, capture browser screenshots, check for visual regressions, or view browser console logs. Supports Chrome, Firefox, and WebKit browsers.

See Description Keywords & Activation Triggers for:

• How to write descriptions that activate properly
• Trigger phrase examples by category
• Testing your description before finalizing
• Common anti-patterns to avoid

Step 3: Create Directory Structure

Output: Directory tree with SKILL.md and optional subdirectories

.github/skills/[skill-name]/
├── SKILL.md                    # Required: Main skill instructions
├── LICENSE.txt                 # Recommended: Apache 2.0 license
├── references/                 # Optional: Deep documentation
│   └── [topic-guide].md
├── scripts/                    # Optional: Executable automation
│   └── [helper-script].py
└── templates/                  # Optional: Starter code (modified by agent)
    └── [scaffold].py

See Resource Bundling Strategy for:

• When to create scripts/ (complex, reusable code)
• When to create references/ (>500 lines of docs)
• When to create templates/ (boilerplate code)
• When to create assets/ (static files used as-is)

Step 4: Write SKILL.md Body

Structure (see Agent Skills File Guidelines for sections):

• ## When to Use This Skill - Reinforce description triggers
• ## Prerequisites - Required tools, setup, dependencies
• ## Step-by-Step Workflows - Numbered procedures for common tasks
• ## Troubleshooting - Common issues and solutions
• ## References - Links to bundled docs and external resources

Length guideline: Keep main body 400-500 lines. Move detailed content to references/ folder.

Content principles:

• Use imperative mood ("Run", "Create", "Configure")
• Be specific and actionable
• Include exact commands with parameters
• Show expected outputs

Link to references instead of embedding everything:

## Configure Environment
See [setup guide](./references/environment-setup.md) for detailed instructions.

Step 5: Bundle Resources

Decide which resources to include using the decision framework:

• Scripts: Reusable code that would be regenerated repeatedly? → scripts/
• References: Documentation >500 lines? → references/
• Templates: Boilerplate code the agent modifies? → templates/
• Assets: Static files used unchanged in output? → assets/

See Resource Bundling Strategy for decision trees and examples.

Step 6: Validate Skill Structure

Checklist (from Agent Skills File Guidelines):

• Frontmatter has valid name and description
• name is lowercase with hyphens, ≤64 characters
• description clearly states WHAT (capability), WHEN (triggers), KEYWORDS
• Body includes when-to-use, prerequisites, workflows
• SKILL.md body is 400-500 lines max (detailed content in references/)
• All resource links use relative paths
• Scripts include help docs and error handling
• No hardcoded credentials or secrets

Step 7: Test Activation

Verify the skill activates when expected:

1. Save the skill directory to .github/skills/[skill-name]/
2. Test activation by mentioning the trigger phrases from your description
3. Verify Copilot loads the full SKILL.md body
4. Check that referenced resources (scripts, docs) load on-demand

---

Tech-Specific Skills (.NET, TypeScript, Python)

Planning to create tech-specific agent skills?

See Tech-Stack Extension Pattern for:

• Naming convention: {tech}-agent-skill (e.g., dotnet-agent-skill)
• How to reference agent-skill-creator as foundational
• Structure for adding tech-specific principles on top
• Implementation timeline and examples

Future tech-specific skills will build on this foundational skill, allowing modular reuse across different technology contexts.

---

Best Practices Summary

Principle	Implementation
Progressive Disclosure	Keep SKILL.md ~500 lines; link to references/ for deep dives
Composability	Each skill works standalone; document integration points with other skills
Evaluability	Include clear triggers, measurable outcomes, validation steps
Consolidation	Group related capabilities; don't fragment into multiple skills
Description Quality	Include WHAT, WHEN, and KEYWORDS; avoid vague language
Resource Organization	Use scripts/, references/, templates/, assets/ appropriately
Documentation Standards	Follow Agent Skills File Guidelines

---

Related Skills & References

• Agent Skills File Guidelines - Authoritative standards and validation checklist
• Skill Design Principles - Core concepts (consolidation, progressive disclosure, etc.)
• Description Keywords Guide - Writing descriptions that activate properly
• Resource Bundling Strategy - When/how to use scripts/, references/, templates/
• Tech-Stack Pattern - Creating tech-specific skills (.NET, TypeScript, etc.)

Example Skills in This Library

These skills follow the principles above:

• context-fundamentals - Progressive disclosure, context engineering
• tool-design - Consolidation principle, architectural reduction
• evaluation - Evaluability framework, quality measurement
• webapp-testing - Resource bundling with Playwright helper