Skill Launch Doctor

Overview

Use this skill to diagnose whether an agent skill is easy to discover, safe to install, compatible across runtimes, and ready for a marketplace or team rollout. Prefer deterministic checks first, then use judgment to rewrite only the parts that block adoption.

Quick Start

From a repository root:

python3 skills/skill-launch-doctor/scripts/audit_skill.py path/to/skill

When running from this skill directory:

python3 scripts/audit_skill.py path/to/skill

JSON output for automation:

python3 scripts/audit_skill.py path/to/skill --format json

Fail a CI or release gate below a threshold:

python3 scripts/audit_skill.py path/to/skill --fail-under 85

Workflow

1. Identify the target skill folder. If the user gives a single SKILL.md, audit its parent directory.
2. Run scripts/audit_skill.py and read the score, subscores, and findings.
3. Fix P0/P1 findings first: missing frontmatter, weak trigger description, unsafe install commands, missing resources, or runtime lock-in.
4. Rewrite description as a clear trigger surface: what it does, when to use it, and concrete user intents.
5. Trim the body so it teaches workflow, not generic agent behavior. Move detailed rubrics, examples, schemas, or provider-specific notes into references/.
6. Keep platform-specific metadata optional. Do not make the skill depend on one agent unless the skill truly cannot work elsewhere.
7. Re-run the audit and report the before/after score with remaining risks.

Review Heuristics

Strong skills usually have:

• A SKILL.md with only name and description in frontmatter.
• A description that names the job, the triggering contexts, and the artifacts or workflows it handles.
• A short body with a decision tree or concrete workflow.
• Scripts for repeated or fragile operations.
• References for longer guidance that should not always enter context.
• Explicit output contracts so agents know what to produce.
• Clear safety boundaries around destructive actions, credentials, payments, publishing, and external messages.
• Runtime-neutral instructions unless a runtime dependency is essential.

Weak skills usually have:

• Vague descriptions such as "helps with productivity".
• Long README-style body text that repeats common agent advice.
• Required tools or APIs without setup guidance.
• Hard-coded local paths, private names, secrets, or one-machine assumptions.
• Unreviewed shell commands for install or publish flows.
• Unreferenced bundled resources or references to files that do not exist.

Rewrite Rules

When improving a skill:

• Preserve the author's actual capability. Do not claim automation, integrations, or safety guarantees that are not implemented.
• Prefer concrete trigger language over marketing language.
• Remove platform lock-in unless requested by the user.
• Keep compatibility claims modest and testable.
• Keep the body concise. Put deeper scoring details in references/launch-rubric.md.
• Ask before changing author identity, license, pricing, or public publishing metadata.

Resources

• scripts/audit_skill.py: stdlib-only auditor for a skill directory.
• references/launch-rubric.md: detailed scoring rubric and severity definitions.
• references/description-patterns.md: trigger description templates and anti-patterns.

Output Contract

When reporting an audit, include:

• Overall score and verdict.
• P0/P1 findings with file paths and concrete fixes.
• Description rewrite, if the existing trigger surface is weak.
• Compatibility notes for generic AgentSkills and Hermes-style taps.
• Remaining launch risks and the smallest next action.