Skill Authoring Review
Goal
Create or review an Agent Skill so another agent can use it reliably with minimal context, clear routing, safe bundled resources, and a concrete output contract.
When to use
- The user asks to create, rewrite, or review a skill.
- A public skill repository needs an installability or quality check.
- A skill has vague triggers, oversized instructions, unsafe scripts, or missing artifacts.
When not to use
- The user is asking to execute a domain workflow that an existing skill already covers.
- The task is ordinary repository review with no skill authoring surface.
- The user only needs installation help; use
skill-installation-support.
Inputs to inspect
SKILL.md frontmatter and body.references/, scripts/, assets/, and agents/ folders.- README catalog entries and install commands when reviewing a repo.
- Validation output from
npm run validate or an equivalent checker.
Review rubric
Check that name matches the folder, uses lowercase hyphen-case, and appears with a clear description. The description must front-load trigger words because it is the routing surface. The body should state goal, scope, workflow, safety rules, output format, completion criteria, and failure modes.
Read references/skill-quality-rubric.md when doing a scored review. Read references/frontmatter-examples.md when rewriting descriptions.
Workflow
- Inspect the skill path and identify the intended workflow.
- Validate frontmatter syntax, name matching, and description routing quality.
- Check progressive disclosure: keep core steps in
SKILL.md and move long examples or rubrics into references.
- Review scripts for deterministic behavior, clear documentation, and safe defaults.
- Verify output artifacts are concrete enough for a future agent to act on.
- Run available validation commands when working in a repository.
- Return blocking issues first, followed by improvements and a concise rewrite plan.
Safety rules
- Do not copy proprietary or unclear-license skill text into a public skill.
- Do not add scripts that mutate files, call services, or install globally without an approval gate.
- Keep secrets, private repo paths, customer data, and internal hostnames out of examples.
References
Read only when needed:
references/frontmatter-examples.mdreferences/skill-quality-rubric.md
Scripts
No bundled scripts.
Output format
Return:
- Verdict
- Blocking issues
- Non-blocking improvements
- Suggested frontmatter or section rewrites
- Validation result
- Remaining risks
Failure modes
- If the skill purpose is unclear, ask for concrete trigger examples before rewriting.
- If scripts appear destructive or credential-sensitive, stop and call out the risk before suggesting execution.
- If installability cannot be tested locally, say which command could not run and why.
Completion criteria
- Frontmatter is valid and routeable.
- The skill performs one workflow with clear exclusions.
- References and scripts are discoverable but not loaded by default.
- Safety constraints and output artifacts are explicit.
1---2name: skill-authoring-review3description: Create or review Agent Skills with correct SKILL.md frontmatter, trigger descriptions, concise workflow design, progressive disclosure, references, scripts, assets, safety rules, and installability. Use when writing a new skill, improving an existing skill, or validating a public skills repo.4license: Apache-2.05---67# Skill Authoring Review89## Goal1011Create or review an Agent Skill so another agent can use it reliably with minimal context, clear routing, safe bundled resources, and a concrete output contract.1213## When to use1415- The user asks to create, rewrite, or review a skill.16- A public skill repository needs an installability or quality check.17- A skill has vague triggers, oversized instructions, unsafe scripts, or missing artifacts.1819## When not to use2021- The user is asking to execute a domain workflow that an existing skill already covers.22- The task is ordinary repository review with no skill authoring surface.23- The user only needs installation help; use `skill-installation-support`.2425## Inputs to inspect2627- `SKILL.md` frontmatter and body.28- `references/`, `scripts/`, `assets/`, and `agents/` folders.29- README catalog entries and install commands when reviewing a repo.30- Validation output from `npm run validate` or an equivalent checker.3132## Review rubric3334Check that `name` matches the folder, uses lowercase hyphen-case, and appears with a clear `description`. The description must front-load trigger words because it is the routing surface. The body should state goal, scope, workflow, safety rules, output format, completion criteria, and failure modes.3536Read `references/skill-quality-rubric.md` when doing a scored review. Read `references/frontmatter-examples.md` when rewriting descriptions.3738## Workflow39401. Inspect the skill path and identify the intended workflow.412. Validate frontmatter syntax, name matching, and description routing quality.423. Check progressive disclosure: keep core steps in `SKILL.md` and move long examples or rubrics into references.434. Review scripts for deterministic behavior, clear documentation, and safe defaults.445. Verify output artifacts are concrete enough for a future agent to act on.456. Run available validation commands when working in a repository.467. Return blocking issues first, followed by improvements and a concise rewrite plan.4748## Safety rules4950- Do not copy proprietary or unclear-license skill text into a public skill.51- Do not add scripts that mutate files, call services, or install globally without an approval gate.52- Keep secrets, private repo paths, customer data, and internal hostnames out of examples.5354## References5556Read only when needed:5758- `references/frontmatter-examples.md`59- `references/skill-quality-rubric.md`6061## Scripts6263No bundled scripts.6465## Output format6667Return:68691. Verdict702. Blocking issues713. Non-blocking improvements724. Suggested frontmatter or section rewrites735. Validation result746. Remaining risks7576## Failure modes7778- If the skill purpose is unclear, ask for concrete trigger examples before rewriting.79- If scripts appear destructive or credential-sensitive, stop and call out the risk before suggesting execution.80- If installability cannot be tested locally, say which command could not run and why.8182## Completion criteria8384- Frontmatter is valid and routeable.85- The skill performs one workflow with clear exclusions.86- References and scripts are discoverable but not loaded by default.87- Safety constraints and output artifacts are explicit.
stark-ai-de