| name | skill-authoring-coach |
| description | 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. |
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 the workflow the user wants to package.
- Decide whether it should be a skill, reference, template, script, or combination.
- 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.
- Produce a candidate folder structure and files.
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?
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 result is practical for a maker to copy into a skills repository.
