Contributing New Skills
Relevant source files
The following files were used as context for generating this wiki page:
The process of contributing new skills to the repository involves a structured workflow designed to maintain high-quality procedural knowledge, SDK expertise, and domain context for AI agents. Skills are modular knowledge packages that transform general-purpose agents into specialized experts by providing them with specific workflows, API patterns, and design principles.
Contributors follow a standardized lifecycle that includes interactive brainstorming, template application, validation against quality standards, and final installation or registration within the project's directory structure. This ensures that every added skill is discoverable, context-efficient, and adheres to established technical requirements.
Sources: bundled-skills/skill-creator-ms/SKILL.md:16-20, bundled-skills/skill-creator/SKILL.md:18-24
Skill Development Lifecycle
The development of a new skill follows a rigorous multi-phase workflow to ensure deterministic quality and high-value input coverage.
Phase 1: Planning and Discovery
Before authoring, contributors must define the skill's purpose, scope, and target platform. For SDK-specific skills, identifying the package name and documentation URL is a mandatory prerequisite.
Sources: bundled-skills/skill-creator/SKILL.md:46-60, bundled-skills/skill-creator-ms/SKILL.md:10-12
Phase 2: Synthesis and Logic Refinement
Contributors analyze relevant source materials (documentation, codebases, or issue logs) to identify patterns and algorithms. This phase focuses on "Progressive Disclosure," where essential information is placed in the primary file while detailed references are moved to supporting files to optimize token usage.
Sources: bundled-skills/skill-writer/SKILL.md:41-48, bundled-skills/skill-creator-ms/SKILL.md:38-41
Phase 3: File Generation and Authoring
Skills are generated using standardized templates that enforce specific Markdown structures and YAML frontmatter.
The following flowchart illustrates the high-level creation process:
The workflow ensures that all required artifacts, including the core SKILL.md and optional references/ or scripts/, are created in the correct directory.
Sources: bundled-skills/skill-creator/SKILL.md:85-90, bundled-skills/skill-writer/SKILL.md:57-65
Structural Standards
All contributions must adhere to a strict directory and file naming convention to ensure discovery by the AI agent's trigger mechanisms.
Directory and File Requirements
| Element | Rule | Example |
|---|---|---|
| Directory Name | kebab-case, 1-64 characters | azure-storage-blob-py |
| Main File | Must be named SKILL.md (ALL CAPS) | SKILL.md |
| YAML name | Must match the directory name exactly | name: azure-storage-blob-py |
| Description | Must start with "Use when..." | description: Use when... |
Sources: bundled-skills/writing-skills/references/standards/README.md:12-32, bundled-skills/writing-skills/SKILL.md:71-76
The SKILL.md Template
Every SKILL.md file consists of a YAML frontmatter block followed by specific Markdown sections:
- YAML Frontmatter: Contains
name,description, andmetadata(includingtriggers). - H1 Title: Brief description of the skill.
- When to Use: A bulleted list of symptoms, error texts, or situations.
- Core Content: Step-by-step instructions, reference tables, or logic.
- Examples: Concrete usage scenarios.
Sources: bundled-skills/writing-skills/references/standards/README.md:34-58
Progressive Disclosure and Optimization
To remain context-efficient, contributors must manage the "documentation budget." Large monolithic files are discouraged in favor of a tiered architecture.
By keeping the primary SKILL.md under 500 lines, the agent reduces context consumption while retaining the ability to pull in detailed documentation from the references/ folder when a specific sub-topic is triggered.
Sources: bundled-skills/writing-skills/references/standards/README.md:65-75, bundled-skills/skill-creator/SKILL.md:154-162, bundled-skills/skill-creator-ms/SKILL.md:38-41
Validation and Testing
Before a skill is registered, it must pass several quality gates.
Pre-Deployment Checklist
- YAML Validation: Ensuring all required metadata fields (triggers, category) are present.
- Trigger Precision: Validating that the "Use when..." description accurately triggers the skill without false positives.
- Writing Style: Content must use the imperative or infinitive form and avoid second-person language ("You").
- Acceptance Criteria: For SDK skills, contributors must document correct versus incorrect import and authentication patterns.
Sources: bundled-skills/writing-skills/SKILL.md:82-89, bundled-skills/skill-creator/SKILL.md:195-205, bundled-skills/skill-creator-ms/SKILL.md:209-215
Automated Testing
Contributors are encouraged to create test scenarios in tests/scenarios/ using YAML to define expected patterns and forbidden anti-patterns.
scenarios:
- name: basic_client_creation
prompt: "Create a basic example using the SDK."
expected_patterns:
- "DefaultAzureCredential"
forbidden_patterns:
- "api_key='hardcoded'"
Sources: bundled-skills/skill-creator-ms/SKILL.md:244-255
Skill Evolution
The collection is designed to self-improve. Contributors should trigger the evolution process when new widget patterns are discovered, shader techniques are learned, or compilation errors are solved. Evolution involves capturing reusable knowledge and documenting it in the appropriate skill or troubleshooting guide.
Sources: bundled-skills/evolution/SKILL.md:78-88, bundled-skills/evolution/SKILL.md:113-125
Contributing to the skills collection requires a balance of technical accuracy and documentation scannability. By following the standardized creation workflow—from interactive brainstorming to automated validation—contributors ensure that AI agents have access to reliable, context-efficient, and highly specialized procedural knowledge.