123 lines
7.9 KiB
Markdown
123 lines
7.9 KiB
Markdown
---
|
|
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.
|