skill-authoring-review

name	skill-authoring-review
description	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.
license	Apache-2.0
metadata	{"internal":true,"author":"stark-ai-de","category":"skill-maintenance","version":"0.1.0"}

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

1. Inspect the skill path and identify the intended workflow.
2. Validate frontmatter syntax, name matching, and description routing quality.
3. Check progressive disclosure: keep core steps in SKILL.md and move long examples or rubrics into references.
4. Review scripts for deterministic behavior, clear documentation, and safe defaults.
5. Verify output artifacts are concrete enough for a future agent to act on.
6. Run available validation commands when working in a repository.
7. 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.md
• references/skill-quality-rubric.md

Scripts

No bundled scripts.

Output format

Return:

1. Verdict
2. Blocking issues
3. Non-blocking improvements
4. Suggested frontmatter or section rewrites
5. Validation result
6. 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.