skill-creator
Guide for creating effective skills for AI coding agents working with Azure SDKs and Microsoft Foundry services. Use when creating new skills or updating existing skills.
66
51%
Does it follow best practices?
Impact
94%
2.68xAverage score across 3 eval scenarios
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./.github/skills/skill-creator/SKILL.mdQuality
Discovery
40%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description is too abstract and reads more like a meta-description than an actionable skill description. It lacks concrete actions (e.g., what specific patterns, templates, or configurations it provides) and relies on vague language. While it does include a 'Use when' clause and some domain-specific terms, the overall lack of specificity makes it hard to distinguish from other skill-authoring guides.
Suggestions
Add specific concrete actions the skill performs, e.g., 'Provides templates for Azure SDK integration, configures Foundry service connections, and structures skill YAML frontmatter for agent workflows.'
Expand trigger terms to include natural variations users might say, such as 'Azure SDK patterns', 'Foundry agent skill', 'skill template', 'skill authoring', '.NET SDK', 'Python SDK'.
Make the 'Use when' clause more specific, e.g., 'Use when authoring or updating skills that interact with Azure Blob Storage, Azure AI, Microsoft Foundry APIs, or other Azure SDK-based services.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description uses vague language like 'creating effective skills' and 'working with Azure SDKs and Microsoft Foundry services' without listing any concrete actions. It doesn't specify what the skill actually does beyond being a 'guide'. | 1 / 3 |
Completeness | It has a weak 'what' (guide for creating skills) and an explicit but vague 'when' clause ('Use when creating new skills or updating existing skills'). The 'what' is too abstract to be truly useful, but the 'when' clause is present. | 2 / 3 |
Trigger Term Quality | It includes some relevant keywords like 'Azure SDKs', 'Microsoft Foundry', and 'skills', but misses common variations and natural terms users might say such as 'Azure SDK patterns', 'Foundry agent', 'skill template', or 'skill authoring'. | 2 / 3 |
Distinctiveness Conflict Risk | The mention of 'Azure SDKs and Microsoft Foundry services' provides some specificity, but 'creating effective skills for AI coding agents' is broad enough to overlap with any general skill-authoring or meta-skill guidance. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
62%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a comprehensive and highly actionable meta-skill for creating Azure SDK skills, with excellent workflow clarity and concrete examples throughout. However, it significantly violates its own conciseness principle — at 400+ lines with inline content that should be in reference files, it wastes substantial token budget. The irony of a skill-creation guide that advises 'keep SKILL.md under 500 lines' while itself being borderline is notable.
Suggestions
Move the 4-language authentication examples, test scenario YAML templates, and acceptance criteria templates into reference files (e.g., references/auth-patterns.md, references/testing-guide.md) — the SKILL.md should show one example and link out
Remove the Azure product area categories table and the detailed documentation update steps (README line numbers, docs-site rebuild commands) into a references/categorization.md and references/documentation-checklist.md respectively
Cut explanatory text like 'Skills are modular knowledge packages that transform general-purpose agents into specialized experts' and the numbered list of skill types — an AI agent creating skills doesn't need this framing
Consolidate the anti-patterns table and checklist which have significant overlap — keep only the checklist as it's more actionable
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | This skill is extremely verbose at ~400+ lines. It explains concepts an AI agent already knows (what skills are, what progressive disclosure means, what product categories are), includes extensive tables of Azure service categories, and repeats patterns multiple times. The authentication example is shown in 4 languages when a reference file would suffice. Much of this content (test harness setup, documentation update steps, symlink creation) could be in reference files. | 1 / 3 |
Actionability | The skill provides fully executable code examples throughout — bash commands for symlinks, complete Python/C#/Java/TypeScript authentication snippets, YAML test scenario templates, and concrete directory structures. Commands are copy-paste ready with specific paths and patterns. | 3 / 3 |
Workflow Clarity | The 8-step skill creation process is clearly sequenced with explicit substeps. Each step has clear inputs/outputs, validation checkpoints (Step 6 testing with specific pass criteria), and the final checklist serves as a comprehensive verification gate. The test step includes a feedback loop via the Ralph Loop with threshold criteria. | 3 / 3 |
Progressive Disclosure | The skill references external files (references/azure-sdk-patterns.md, references/workflows.md, etc.) and demonstrates progressive disclosure patterns, but the SKILL.md itself is a monolithic wall of content. The authentication examples in 4 languages, the full test scenario YAML, the complete acceptance criteria template, and the detailed documentation update steps should all be in reference files rather than inline. | 2 / 3 |
Total | 9 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (614 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
- Repository
- microsoft/agent-skills
- Commit
265cb08
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.