typespec-create-api-plugin
Generate a TypeSpec API plugin with REST operations, authentication, and Adaptive Cards for Microsoft 365 Copilot
77
64%
Does it follow best practices?
Impact
100%
1.96xAverage score across 3 eval scenarios
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/typespec-m365-copilot/skills/typespec-create-api-plugin/SKILL.mdQuality
Discovery
64%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 excels at specificity and distinctiveness by naming a precise technology stack (TypeSpec, REST, Adaptive Cards, Microsoft 365 Copilot). However, it critically lacks any 'Use when...' guidance, which means Claude has no explicit trigger conditions for selecting this skill. Adding explicit trigger conditions would significantly improve its utility in a multi-skill selection scenario.
Suggestions
Add a 'Use when...' clause such as 'Use when the user asks to create a TypeSpec API plugin, build a Microsoft 365 Copilot extension, or scaffold REST operations with Adaptive Cards.'
Consider including common variations of trigger terms like 'M365 Copilot', 'Copilot plugin', 'declarative agent', or 'API manifest' that developers might naturally use.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'Generate a TypeSpec API plugin', 'REST operations', 'authentication', and 'Adaptive Cards'. These are concrete, identifiable capabilities rather than vague language. | 3 / 3 |
Completeness | Describes 'what' it does clearly but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per rubric guidelines, a missing 'Use when...' clause caps completeness at 2, and since the 'when' is entirely absent, this scores a 1. | 1 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'TypeSpec', 'API plugin', 'REST operations', 'authentication', 'Adaptive Cards', 'Microsoft 365 Copilot'. These are the exact terms a developer working in this domain would use. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive niche combining TypeSpec, API plugins, and Microsoft 365 Copilot. This very specific technology stack is unlikely to conflict with other skills. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
64%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides strong, actionable TypeSpec templates covering the full scope of M365 Copilot API plugin creation, with excellent coverage of authentication patterns and function capabilities. Its main weaknesses are the lack of validation/verification steps in the workflow (no TypeSpec compilation check or testing guidance) and the monolithic structure that could benefit from splitting detailed reference sections into separate files. Some generic best practices could be trimmed to improve token efficiency.
Suggestions
Add validation steps to the workflow: e.g., 'Compile with `tsp compile .` and verify no errors before delivering files to user'
Split authentication options and function capabilities into separate reference files (e.g., AUTH.md, CAPABILITIES.md) and link from the main skill
Remove or significantly trim the 'Best Practices' section — items like 'use appropriate HTTP verbs' and 'use RESTful path conventions' are knowledge Claude already has
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is moderately efficient but includes some unnecessary verbosity like the 'Best Practices' section with generic advice Claude already knows (use appropriate HTTP verbs, RESTful conventions). The code templates are useful but some inline comments like '// Response structure' and '// Reference operations from actions.tsp' add little value. | 2 / 3 |
Actionability | The skill provides fully concrete, copy-paste-ready TypeSpec code templates for every component: agent definition, API operations, all four authentication patterns, confirmation dialogs, adaptive cards, and reasoning decorators. The code is executable and specific with real decorator syntax and proper imports. | 3 / 3 |
Workflow Clarity | The workflow section at the end lists questions to ask and files to generate, but lacks validation checkpoints. There's no guidance on how to verify the generated TypeSpec compiles correctly, no error recovery steps, and no mention of testing or validation tools. For a code generation task producing multiple interdependent files, validation steps would be important. | 2 / 3 |
Progressive Disclosure | The content is a single monolithic file with no references to supporting files, despite being ~150 lines with distinct sections (auth options, capabilities, cards) that could be split out. The structure within the file is reasonable with clear headers, but the authentication options and function capabilities sections are substantial enough to warrant separate reference files. | 2 / 3 |
Total | 9 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- github/awesome-copilot
- Commit
2e7c43b
- 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.