Create create-skill

create-skill/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: create-skill
+description: >-
+  Creates, rewrites, reviews, and improves concise, unambiguous, progressively
+  disclosed, and agent-actionable Agent Skills. Use this skill when creating,
+  reviewing, or revising a SKILL.md, its routing description, references,
+  assets, scripts, or reusable workflow guidance. Do not use for installing
+  third-party skills or capturing one-off preferences that do not warrant a
+  reusable skill.
+license: MIT
+metadata:
+  short-description: Create and evaluate concise Agent Skills
+---
+
+# Create Skill
+
+## Required resources and checks
+
+- Before using a starter, read and adapt [`assets/skill-template.md`](assets/skill-template.md). Replace every sentinel and remove unused sections.
+- Before finalizing or reviewing, read [`references/skill-quality-checklist.md`](references/skill-quality-checklist.md). Record applicable evidence.
+- Run repository-provided skill validators when they exist.
+- Otherwise perform equivalent checks manually. Report the unavailable gate.
+
+Follow user and higher-priority constraints. Keep one coherent job. Preserve behavior outside an evidence-backed requested change.
+
+## Scale the work
+
+Match evidence and validation to the requested outcome:
+
+- For a review, inspect and report without editing or running execution evaluations unless requested or needed to verify a material risk.
+- For a narrow revision, make the requested change and run applicable static checks.
+- For creation or substantial revision, define relevant use cases, make the requested changes, and run applicable static checks.
+- When evaluating or claiming improvement, test representative behavior and compare with the previous version when feasible.
+
+Do not turn a narrow review into an unsolicited rewrite or benchmark.
+
+## Skill contract
+
+- Put all activation guidance in frontmatter `description`. The body loads only after activation.
+- Use: `[Third-person capability]. Use this skill when [intents/triggers]. Do not use when/for [material near misses].`
+- Keep the description under 1024 characters. Focus on intent, outcomes, and adjacent boundaries—not mechanics.
+- Keep `SKILL.md` concise and actionable. Put critical constraints, mandatory resources, fragile sequencing, validation, and safety early.
+- Default to short headings, compact bullets, numbered procedures, and small tables. Use prose paragraphs only when they communicate necessary nuance more clearly.
+- Keep each bullet focused on one instruction or tightly coupled behavior. Prefer direct wording; remove throat-clearing, repeated rationale, and paragraph-length bullets.
+- Match the surrounding skill catalog's density. A longer main file requires execution-critical justification; move conditional detail into `references/`.
+- Use progressive disclosure deliberately. Do not squeeze useful reusable detail into `SKILL.md` merely to avoid a resource.
+- Use `references/` for detailed workflows, schemas, examples, tool guidance, and gotchas.
+- Use `assets/` for reusable templates and static output shapes.
+- Use `scripts/` for repeated or fragile deterministic operations.
+- Add resources when they improve repeated execution, clarity, consistency, or maintenance.
+- Keep references one level deep.
+- Add a resource pointer only after its file exists. Give its exact path, purpose, and read/use/run condition.
+- Repeat mandatory resource loading at the relevant workflow step. Delete stale pointers and empty directories.
+- Refer to other skills by name, such as `create-plan`. Do not use relative paths to their `SKILL.md` files.
+- Ground changes in relevant evidence: user requirements or corrections, project conventions, static inspection, real tasks or artifacts, recurring failures, or evaluation results. Match the strength of evidence to the claim.
+- Reject one-off or speculative preferences. Prefer the smallest durable correction.
+- Check tools, schemas, commands, and examples for staleness. Ask when reusability is unclear.
+- Prescribe fragile, destructive, security-sensitive, and validation-critical sequences. Allow judgment elsewhere.
+
+## Workflow
+
+### 1. Define observable use cases
+
+For creation, substantial revision, or behavioral evaluation:
+
+- Record two or three realistic tasks.
+- For each, record inputs, expected output, success criteria, and constraints.
+- Record two or three strong near misses. Name the correct adjacent skill or direct workflow.
+- For an existing skill, record reusable change evidence and the smallest durable correction.
+- Do not broaden scope because related guidance is available.
+
+### 2. Inspect the ecosystem
+
+- Read the target skill and project instructions.
+- Inspect nearby global and project skills, conventions, scripts, tools, and schemas.
+- Identify duplicated policy and resource boundaries.
+- Reuse good patterns. Do not copy generic advice or another skill's whole workflow.
+
+### 3. Draft frontmatter first
+
+For creation or a requested routing change:
+
+- Write the description before the body.
+- Include realistic user phrasing, useful co-activation, and material near misses.
+- Use lowercase kebab-case for `name`. Keep it under 64 characters and match the directory.
+
+### 4. Build the post-activation contract
+
+For creation or a requested body or resource change:
+
+- Include only rules needed after activation.
+- Define critical constraints, sequence, resources, validation, failure handling, and safety.
+- Remove redundant explanation, excessive menus, stale examples, vague guidance, and unrelated content.
+- Perform a compression pass: shorten wording, split overloaded bullets, convert scannable prose to lists, and remove content that does not change execution.
+- Create supporting resources when detail is reusable or would crowd the main file.
+- Follow the target repository's established language, runtime, dependency, packaging, and test conventions. Do not introduce a runtime solely for a helper script when existing project tooling is sufficient.
+- Make command-line scripts automation-safe: non-interactive by default, bounded output, meaningful exit statuses, and safe idempotent defaults.
+- Provide `--help` or the ecosystem-equivalent. Document prerequisites, working directory, inputs, outputs, and side effects.
+- Send primary or machine-readable output to stdout and diagnostics to stderr where the environment supports that convention.
+- For stateful or destructive operations, default to a dry run or require an explicit opt-in; add confirmation where appropriate.
+
+### 5. Evaluate routing and execution
+
+When evaluating behavior, finalizing a substantial skill, or claiming improvement:
+
+- Test three to five realistic should-trigger prompts and two to three strong near misses.
+- Judge routing from the description alone. Expand cases only for broadly distributed or high-risk skills.
+- Run one representative task with realistic input. Compare its output with the recorded success criteria.
+- Prefer a fresh, safely available subagent for unbiased execution or review.
+- Otherwise record the direct fallback and its independence limit. Treat child claims as evidence, not acceptance.
+- Revise only material evidence-backed gaps. Rerun affected routing and output checks once.
+- Do not build a benchmark framework for a small skill.
+
+### 6. Validate and finalize
+
+Run applicable checks from the repository root using its documented commands and established runtime.
+
+- Run an available Agent Skills specification validator when the repository provides or permits one.
+- Otherwise check specification compliance manually and report the unavailable automated gate.
+- Run each added or changed command-line script's `--help` or ecosystem-equivalent, focused repository-native tests, and one representative safe execution.
+- Before finalizing, read and complete [`references/skill-quality-checklist.md`](references/skill-quality-checklist.md) against the final revision.
+- Report changed files, evaluated cases, exact results, skipped checks, reasons, and remaining risks.
+- Never claim resources or artifacts that do not exist.

create-skill/assets/skill-template.md

@@ -0,0 +1,33 @@
+<!-- Replace every REPLACE_ME marker before validation. Delete every unused section and optional frontmatter field. -->
+<!-- Keep the body compact and scan-friendly. Prefer short bullets and numbered steps; use prose only for necessary nuance. Move conditional detail into references/. -->
+---
+name: REPLACE_ME
+description: REPLACE_ME. Use this skill when REPLACE_ME. Do not use when REPLACE_ME.
+# Delete when the skill has no material runtime, platform, or capability requirements.
+compatibility: REPLACE_ME
+---
+
+# REPLACE_ME
+
+## Critical rules
+
+- REPLACE_ME
+
+## Workflow
+
+1. REPLACE_ME
+2. REPLACE_ME
+3. Validate the result using the exact checks below.
+
+## Resources
+
+<!-- Delete this section when no resource is needed. Add a link only after its exact one-level-deep file exists. State what it contains and the precise condition for reading, using, or running it. Repeat mandatory loading at the relevant workflow step. -->
+
+## Validation
+
+- Run `REPLACE_ME`; expect REPLACE_ME.
+- Inspect REPLACE_ME; expect REPLACE_ME.
+
+## Constraints
+
+- REPLACE_ME

create-skill/references/skill-quality-checklist.md

@@ -0,0 +1,66 @@
+# Skill Quality Checklist
+
+Complete the applicable parts before finalizing, reviewing, or substantially revising an Agent Skill. Match evidence and validation to the requested outcome, and record evidence rather than checking boxes from intent alone. For a narrow review, inspect and report without requiring creation or execution evidence unless needed to verify a material risk. Do not manufacture artifacts solely to satisfy this checklist.
+
+## Purpose and evidence
+
+- The skill has one coherent job, explicit non-goals, and clear adjacent-skill boundaries.
+- For creation, substantial revision, or behavioral evaluation, two or three realistic use cases record inputs, expected outputs, observable success criteria, and material constraints.
+- For creation, substantial revision, or routing evaluation, two or three strong near misses identify the correct adjacent skill or direct workflow.
+- An existing-skill change cites applicable evidence, is the smallest durable correction, and does not encode a one-off preference. Claims of behavioral improvement compare the old and revised versions when feasible. Reusability uncertainty was resolved with the user.
+- Current tool names, command flags, schemas, paths, runtime assumptions, and examples were checked rather than copied from stale memory.
+
+## Frontmatter and routing
+
+- `name` is lowercase kebab-case, at most 64 characters, and exactly matches the directory.
+- `description` is under 1024 characters and uses: third-person capability + literal `Use this skill when...` + material `Do not use when/for...`.
+- Routing focuses on user intent/outcomes, includes realistic phrasing and useful co-activation, and keeps all activation guidance out of the body.
+- No unresolved starter sentinel, sample name, bare ellipsis, bracket instruction, or other placeholder remains.
+- `compatibility` names material runtime, CLI, credential, platform, or capability assumptions when applicable.
+
+## Main body
+
+- Critical constraints, mandatory resource loads, fragile sequencing, validation, and safety rules appear early.
+- The workflow is concrete enough to execute without guessing; defaults replace unnecessary menus.
+- Prescriptiveness matches risk, and failure/cleanup/recovery behavior is explicit where material.
+- Generic explanations, duplicated policy, transcript history, redundant examples, and unrelated guidance are removed.
+- The main file matches nearby catalog density and is normally under roughly 150 lines; longer files retain only execution-critical material and move conditional detail into resources.
+- The body favors short headings, compact bullets, numbered procedures, and small tables. Prose is retained only where it improves clarity.
+- Bullets express one instruction or tightly coupled behavior; paragraph-length bullets, repeated rationale, and introductory filler are absent.
+- Cross-skill references use skill names, not relative paths to another skill's `SKILL.md`.
+
+## Resources and progressive disclosure
+
+- Every referenced file exists at the exact relative path, is one level deep, and has a clear content summary plus read/use/run condition.
+- Mandatory resources are named early and repeated at the point of use with “Before doing X, read/use...” force.
+- No vague “see references”, “as needed”, nonexistent fake link, empty resource directory, or unreferenced resource remains.
+- References over roughly 100 lines have a short table of contents.
+- Assets are reusable output skeletons rather than duplicated instructions; unused sections and all template sentinels were removed.
+
+## Scripts and safety
+
+- Every script is justified by repeated/fragile deterministic work, not a simple pinned one-off command.
+- Scripts follow the target repository's established language, runtime, dependency, packaging, and test conventions; introducing a runtime solely for a helper script is justified only when existing tooling is insufficient.
+- Command-line scripts are non-interactive by default, bound output, return meaningful exit statuses, provide `--help` or the ecosystem-equivalent, and document prerequisites, working directory, inputs, outputs, and side effects.
+- Primary or machine-readable output goes to stdout and diagnostics to stderr where the environment supports that convention.
+- Stateful/destructive scripts are idempotent, default to a dry run, or require an explicit opt-in; confirmation is added where appropriate.
+- No secrets, tokens, sessions, `.env` contents, generated credentials, unsafe third-party code, or accidental machine-only paths are included.
+
+## Evaluation
+
+Apply this section when evaluating behavior, finalizing a substantial skill, or claiming improvement.
+
+- Three to five realistic should-trigger prompts route from the description alone; broadly distributed/high-risk skills use additional cases only when warranted.
+- Two to three near-miss prompts do not trigger incorrectly and retain useful co-activation where intended.
+- At least one representative real-use task ran with realistic input; its actual output meets the recorded success criteria.
+- A fresh safely available subagent performed execution/review when useful, or the direct fallback and independence limitation are recorded.
+- Material evidence-backed gaps received one concise revision and affected routing/output checks were rerun; no benchmark framework was added without need.
+
+## Validation
+
+Run applicable repository checks with the repository's documented commands and established runtime, and retain exact results.
+
+- Run an available Agent Skills specification validator when the repository provides or permits one; otherwise check specification compliance manually and report the unavailable automated gate.
+- Metadata, names, literal routing, description length, placeholders, and resource links pass mechanically where repository validators exist; unavailable gates are checked manually and reported.
+- Every added/changed command-line script's `--help` or ecosystem-equivalent, focused repository-native tests, and one representative safe execution pass.
+- Final diff/status inspection shows only intended files, no stale generated artifacts, and no owner work lost.