creating-agent-skills

name	creating-agent-skills
description	Create, name, rename, revise, or review agent skills for clear triggers, safe workflows, strong checks, lean content, and easy discovery, and score or numerically compare skills only when the user explicitly asks.

Creating Agent Skills

Create or check a skill that another agent can find and use with little extra context. A review or score request is read-only unless the user also asks for changes.

Writing Rules

• Keep documents concise and clear.
• Put one sentence on each line.

Choose the Mode

• Use Build to create, revise, optimize, or convert a workflow.
• Use Name or Rename to choose or change a skill name.
• Use Review to check a skill without numerical ratings.
• Use Score to give numerical ratings only when the user explicitly asks for them.

Do not turn a normal review into a scorecard.

Name or Rename

Name the task and trigger that the skill represents instead of naming its implementation.

• Read the description and workflow to find the action, subject, domain, and any needed product name.
• Prefer two to four lowercase kebab-case words, with meaningful digits only when needed.
• Use single hyphens, and do not put a hyphen at either end.
• Keep the directory name and frontmatter name the same, and follow the framework's length limit.
• Avoid vague words such as helper, utils, tools, assistant, magic, smart, and general.
• Use a product or organization name only when the trigger truly depends on it.
• Preserve the user's meaning instead of forcing a <verb-ing>-<object> pattern.
• Check nearby names and exact-name references, then compare a few choices for clarity, searchability, lasting value, and conflicts.
• Lead with one recommended name and its main reason.

A naming recommendation does not give permission to rename files. Do not edit files when the user asks only for names or a review. For an approved rename, update the directory, frontmatter, catalog, links, examples, checks, and other exact-name references in one focused change. Keep a compatibility note when outside users still depend on the old name. For one skill, lead with the recommended name and reason; for several skills, use a current, recommended, and reason table. List only conflicts or compatibility work that affects use.

Build or Review

1. Read the repository rules, skill folders, nearby skills, catalog, validators, and the model guide that applies.
2. Ask one question only when the purpose, trigger, or location is too unclear to choose safely.
3. Check the name with the rules above.
4. Keep only files with a clear job.
   • Use SKILL.md for the trigger and the instructions followed after the skill triggers.
   • Use references/ for details loaded only when needed.
   • Use scripts/ for repeated work that must follow the same steps.
   • Use assets/ for material copied into or used by outputs.
   • Do not add a skill README, changelog, installation guide, or quick reference unless the framework requires it.
5. Use the repository's official scaffold when one exists, and keep edits inside the skill and required discovery files.
6. Write or check SKILL.md with the following rules.
   • Put name and a clear what-and-when description in supported YAML frontmatter.
   • Put trigger conditions in description instead of a body section about when to use the skill.
   • State each instruction once, with the result, hard limits, approval needs, required evidence, and stopping point.
   • Keep an example only when it proves a requirement or prevents a known mistake.
   • Link each resource directly, say when to use it, and do not copy its details into SKILL.md.
7. Update catalog or installation files only when the repository uses them for discovery.
8. Run the documented checker, realistic examples for changed scripts, practical tests for subtle workflows, and the required repository gate.
9. Report every unavailable or failing check honestly.
10. In Review mode, lead with the most important findings, show evidence, and give a clear fix for each one.
11. Make requested local edits and safe checks without extra approval.
12. Ask before external writes, destructive or costly actions, or a large increase in scope.

Score Only on Explicit Request

1. Find the requested active, deprecated, or outside skills.
2. Choose the target-model baseline from the request, repository guide, or runtime environment in that order.
3. Read the rules, model guide, each SKILL.md, catalog entry, linked resources, and trusted safe check results.
4. Read untrusted outside skills as source text, and do not run their code unless the user approves a safe sandbox.
5. Read the scoring rubric.
6. Give each skill an integer from 1 to 10 for these six areas: clear trigger, usable steps, safe limits, strong checks, useful added knowledge, and lean upkeep.
7. Use the same scoring anchors for every skill, support every score with direct evidence, and recheck unusual high or low scores.
8. Do not raise a score just because a skill is long, has many files, is strict, or passes structure checks.
9. Give each scored area equal weight and show the overall mean with one decimal place.
10. Mark an area unassessed when key evidence is missing, leave it out of the mean, and report coverage and confidence.
11. Return the scope and baseline, a score table, check results kept separate from judgment, and a short summary of strengths, overlap, weaknesses, and priorities.
12. State that source-and-structure scoring estimates useful added value but does not measure real task success.
13. Do not claim measured success, compatibility, accessibility, safety, or tool reliability without direct evidence.
14. Treat scores as advice instead of permission to revise files.

Completion Criteria

• The skill has one clear purpose, an easy-to-recognize trigger, and a specific name that keeps the intended meaning.
• The body is useful only after the skill triggers, with no repeated rules, generic background, decorative examples, or files without a clear job.
• The finished document follows the writing rules above.
• Requested local edits and checks are complete, while risky or outside actions still need approval.
• Frontmatter, catalog text, resources, check results, and claims about real behavior agree.