Skill Authoring Coach
Use this skill to help users design, review, genericise, and package reusable Agent Skills.
Purpose
A good skill is not a long prompt dump. It is a focused, reusable capability with:
- A clear trigger description.
- Practical step-by-step instructions.
- Guardrails and edge cases.
- Optional references, assets, or scripts.
- A compact structure that an agent can load when needed.
Skill vs reference vs template
Use these distinctions:
- Skill - Teaches the agent how to perform a repeatable task or workflow.
- Reference - Supplies detailed information the skill may need, such as policies, rubrics, examples, taxonomies, or checklists.
- Template - Supplies a reusable output shape or file structure.
- Script - Performs deterministic work that should not rely on prose instructions alone.
If the user tries to put everything into SKILL.md, recommend moving detailed lookup material into references/ and static output structures into assets/.
Recommended skill shape
<skill-folder>/
├── SKILL.md
├── references/ optional
├── assets/ optional
└── scripts/ optional
The SKILL.md should contain:
- Frontmatter with
name and description.
- A short explanation of when to use the skill.
- Inputs to look for.
- Workflow steps.
- Output formats.
- Guardrails and quality checks.
Workflow
- Identify whether the user wants to create, improve, review, package, or submit a skill, along with the target platforms and any target repository or authoring tool.
- Identify the repeatable workflow or capability the user wants to package.
- Decide whether the best fit is a skill, reference, template, script, or combination.
- Read the target's current authoring and submission requirements before proposing files or metadata.
- When reviewing existing files, run available deterministic schema, layout, and packaging checks before qualitative feedback. Report failures and recommend Revise until they are resolved.
- Write or improve the skill trigger description.
- Keep instructions concise and operational.
- Move long examples and detailed reference material out of
SKILL.md where appropriate.
- Check for sensitive, organisation-specific, or non-reusable content.
- Verify that scripts, runtime dependencies, commands, and filesystem assumptions work on every declared platform.
- Produce a candidate folder structure and files.
- Run the available target validators again. Recommend Submit only when the known target requirements are met and all available checks pass; state anything that could not be verified.
Review rubric
Score candidate skills from 0 to 5 on:
- Trigger clarity - Will the agent know when to use it?
- Task focus - Is it one coherent capability?
- Instruction quality - Are the steps clear and repeatable?
- Portability - Can others use it without private assumptions?
- Safety and evidence discipline - Does it avoid invented claims, secret leakage, or risky actions?
- Packaging quality - Are references, assets, and scripts separated cleanly?
- Target compliance - Does it satisfy the target's schema, layout, packaging, and platform requirements?
Output format for review
## Skill review
Overall recommendation: [Submit / Revise / Keep private]
| Dimension | Score /5 | Notes |
|---|---:|---|
## Required changes
1. [Change]
2. [Change]
3. [Change]
## Suggested folder structure
```text
[folder tree]
```
References
This skill includes supporting reference material. Read the relevant reference file when the task needs additional structure, rubric detail, examples, or checklist support.
references/skill-design-checklist.md - use this when additional structure, examples, or checks are useful for the task.
Quality checklist
Before responding, check:
- The proposed skill has a clear reusable job.
- The trigger description is precise.
- Organisation-specific material is removed or parameterised.
- Long reference content is not overloaded into the main skill file.
- The target's current requirements are satisfied and available deterministic checks pass.
- Scripts, dependencies, commands, and paths work on every declared platform.
- The result is practical for a maker to copy into a skills repository.
1---2name: skill-authoring-coach3description: Use this skill when the user asks to create, improve, review, package, genericise, or submit an Agent Skill, SKILL.md file, skill metadata, or reusable agent instruction bundle.4metadata:5 source: https://skillmd.com/skills/microsoft/skill-authoring-coach6---78# Skill Authoring Coach910Use this skill to help users design, review, genericise, and package reusable Agent Skills.1112## Purpose1314A good skill is not a long prompt dump. It is a focused, reusable capability with:1516- A clear trigger description.17- Practical step-by-step instructions.18- Guardrails and edge cases.19- Optional references, assets, or scripts.20- A compact structure that an agent can load when needed.2122## Skill vs reference vs template2324Use these distinctions:2526- **Skill** - Teaches the agent how to perform a repeatable task or workflow.27- **Reference** - Supplies detailed information the skill may need, such as policies, rubrics, examples, taxonomies, or checklists.28- **Template** - Supplies a reusable output shape or file structure.29- **Script** - Performs deterministic work that should not rely on prose instructions alone.3031If the user tries to put everything into `SKILL.md`, recommend moving detailed lookup material into `references/` and static output structures into `assets/`.3233## Recommended skill shape3435```text36<skill-folder>/37├── SKILL.md38├── references/ optional39├── assets/ optional40└── scripts/ optional41```4243The `SKILL.md` should contain:44451. Frontmatter with `name` and `description`.462. A short explanation of when to use the skill.473. Inputs to look for.484. Workflow steps.495. Output formats.506. Guardrails and quality checks.5152## Workflow53541. Identify whether the user wants to create, improve, review, package, or submit a skill, along with the target platforms and any target repository or authoring tool.552. Identify the repeatable workflow or capability the user wants to package.563. Decide whether the best fit is a skill, reference, template, script, or combination.574. Read the target's current authoring and submission requirements before proposing files or metadata.585. When reviewing existing files, run available deterministic schema, layout, and packaging checks before qualitative feedback. Report failures and recommend **Revise** until they are resolved.596. Write or improve the skill trigger description.607. Keep instructions concise and operational.618. Move long examples and detailed reference material out of `SKILL.md` where appropriate.629. Check for sensitive, organisation-specific, or non-reusable content.6310. Verify that scripts, runtime dependencies, commands, and filesystem assumptions work on every declared platform.6411. Produce a candidate folder structure and files.6512. Run the available target validators again. Recommend **Submit** only when the known target requirements are met and all available checks pass; state anything that could not be verified.6667## Review rubric6869Score candidate skills from 0 to 5 on:70711. **Trigger clarity** - Will the agent know when to use it?722. **Task focus** - Is it one coherent capability?733. **Instruction quality** - Are the steps clear and repeatable?744. **Portability** - Can others use it without private assumptions?755. **Safety and evidence discipline** - Does it avoid invented claims, secret leakage, or risky actions?766. **Packaging quality** - Are references, assets, and scripts separated cleanly?777. **Target compliance** - Does it satisfy the target's schema, layout, packaging, and platform requirements?7879## Output format for review8081````markdown82## Skill review8384Overall recommendation: [Submit / Revise / Keep private]8586| Dimension | Score /5 | Notes |87|---|---:|---|8889## Required changes90911. [Change]922. [Change]933. [Change]9495## Suggested folder structure9697```text98[folder tree]99```100````101102103## References104105This skill includes supporting reference material. Read the relevant reference file when the task needs additional structure, rubric detail, examples, or checklist support.106107- `references/skill-design-checklist.md` - use this when additional structure, examples, or checks are useful for the task.108109## Quality checklist110111Before responding, check:112113- The proposed skill has a clear reusable job.114- The trigger description is precise.115- Organisation-specific material is removed or parameterised.116- Long reference content is not overloaded into the main skill file.117- The target's current requirements are satisfied and available deterministic checks pass.118- Scripts, dependencies, commands, and paths work on every declared platform.119- The result is practical for a maker to copy into a skills repository.