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, naming a very precise technology stack (TypeSpec, Microsoft 365 Copilot, Adaptive Cards, REST). 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 context.
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.'
Include common variations of trigger terms like 'M365 Copilot', 'Copilot plugin', 'API definition', '.tsp files', or 'declarative agent' to improve matching across different user phrasings.
| 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 (not even implied beyond the what), this scores at 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 specific technical terms a user would naturally use when requesting this kind of work. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with a very specific niche: TypeSpec API plugins for Microsoft 365 Copilot with Adaptive Cards. This combination of technologies 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 with concrete code examples covering agent definitions, API operations, authentication, and Adaptive Cards. Its main weaknesses are the lack of validation/compilation steps in the workflow and some unnecessary best practices that Claude would already know. The content could benefit from splitting detailed reference material into separate files and adding a TypeSpec compilation verification step.
Suggestions
Add a validation step to the workflow, e.g., 'Run `tsp compile .` to verify the generated files are valid TypeSpec before delivering to the user'
Remove or significantly trim the Best Practices section—items like 'use appropriate HTTP verbs' and 'use RESTful path conventions' are things Claude already knows
Consider splitting authentication options and function capabilities into separate referenced files (e.g., AUTH.md, CAPABILITIES.md) to keep the main skill lean
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably efficient but includes some unnecessary commentary in best practices that Claude would already know (e.g., 'Use appropriate verbs', 'Use RESTful path conventions'). The templates themselves are well-structured but the best practices section adds marginal value. | 2 / 3 |
Actionability | The skill provides fully concrete, copy-paste-ready TypeSpec code templates for main.tsp and actions.tsp, with specific syntax for all authentication options, decorators, and capabilities. Every section includes executable TypeSpec code rather than pseudocode. | 3 / 3 |
Workflow Clarity | The workflow section at the end provides a clear sequence of questions and outputs, but there are no validation checkpoints. Given that generating TypeSpec files could produce invalid syntax or misconfigured agents, there should be a validation/compilation step (e.g., running tsp compile) before considering the output complete. | 2 / 3 |
Progressive Disclosure | The content is well-organized with clear sections and headers, but it's a fairly long monolithic file. The authentication options, function capabilities, and card templates could be split into referenced files. No external references are provided for advanced topics. | 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
4020587
- 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.