SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsrefine-skill-design

refine-skill-design

Design & creation

View repository

Updated 10-16 01:35

About this skill

Skill: Refine Skill Design

Purpose

As a "meta-skill", this skillreviews and refactorsdraft-form AI capability definitions. It applies an advanced prompt engineering perspective to improve logical robustness, scenario coverage, and instruction adherence, so that every capability meets LLM best practices.

Core Objective

Primary objective: Generate a reviewed and refactored skill document that satisfies specification compliance and LLM best practices.

Success criteria(all requirements must be met):

  1. ✅ Structural compatibility: The skill follows the standard template (YAML, purpose, use cases, behavior, inputs and outputs, limitations, self-check, examples)
  2. ✅ Logical clarity: The input→behavior→output chain is clear and explicit
  3. ✅ Defined constraints: The limitations section covers common failure modes in the domain
  4. ✅ Comprehensive examples: At least 2 examples are provided, including an edge case or challenging scenario
  5. ✅ Documented changes: The diff summary lists all changes along with section, description, and reason
  6. ✅ Recommended version: SemVer recommendation with rationale

Acceptance test: Can an AI agent consistently apply this refined skill in different environments without producing ambiguity?

Scope boundaries

This skill is responsible for：

  • Reviewing the quality and compliance of existing skill drafts
  • Refactoring skill structure and content to meet the specification
  • Improving logical clarity and instruction precision
  • Adding missing sections or strengthening weak areas
  • Providing a diff summary and version recommendation

This skill is not responsible for：

  • Creating new skills from scratch (use the "Skill Creator" in human/skills)
  • Running package scripts or initializing workflows (use Skills.sh tools)
  • Planning skill assets or references (use Skills.sh documentation)
  • Generating the project docs/ structure (handled by AgentFabric runtime or manually)

Handoff point: When the SKILL has been refined and a diff summary is provided, hand off to the user for review and version control commit.

Usage scenarios (Use Cases)

  • New skill onboarding: Expert review after an agent generates a new skill draft.
  • Quality fixes: When a skill performs inconsistently on a new model, adjust the logic and strengthen the examples.
  • Consistency review: Check whether the new skill matches the tagging system and naming in INDEX.md; ensure description、tags、triggers is sufficient to support semantic discovery.
  • Upgrade: Transform a simple "formatting tool" into a complete agent capability with interaction strategy and error handling.

Scope: This skill is used toreview and refactor existing skills, not to create them from scratch. To learn how to create new skills, plan scripts/references/assets, or run init/package scripts, use the "Skill Creator" from Skills.sh (e.g., anthropics/skills).

Behavior

Meta-audit model

  1. Intent: Is the purpose sufficiently specific? Avoid vague terms such as "assistant", "utility", etc.
  2. Logic: Do input→behavior→output form a clear chain?
  3. Constraints: Do the constraints cover the most common failure modes in the domain?
  4. Examples: Do the examples go from simple to complex and include at least one edge case?
  5. Interaction policy(Spec §4.3): Does the behavior specify defaults, choice options, and which items require user confirmation? Prefer defaults first, prefer choices, contextual reasoning.
  6. Triggers(Optional): For high-discoverability skills, consider adding "triggers" (3-5 English phrases) at the front to enable fast invocation matching.

Optimization process

  1. Structure: Apply the standard template (YAML, purpose, use cases, behavior, I/O, constraints, self-check, examples).
  2. Verbs: Use precise, explicit verbs (e.g., "handle" → "parse", "convert", "trim").
  3. Interaction: For complex logic, add "confirm before continuing" or "choose an option". Stay consistent with the spec interaction policy (defaults first, prefer choices).
  4. Metadata: Align tags with INDEX.md; suggest triggers for high-discoverability skills; suggest a reasonable SemVer.
  5. Apply changes: Unless the user explicitly requests a dry run/temporary refinement file, write the refined contentdirectly back to the source SKILL.md, and include both a diff summary and a version number suggestion in the output for easy review and auditing.

Input & Output

Input (Input)

  • A SKILL Markdown document that needs optimization, or a draft.

Output (Output)

  • Optimized skill: Production-grade Markdown that satisfies the spec.
  • Diff summary: What was changed and why.
  • Version suggestion: SemVer recommendation.

Output (Output) Persistence (Document Processing)

Rule: By default, improve directly and overwrite the originalSKILL.md, while providing an auditable diff summary and version number suggestion; only when the user explicitly requests "only generate a refined draft, do not modify the source file" should a temporary or newly created refined file be written. Each run must choose one of the following policies:

Strategy Path mode Behavior
Direct overwrite(Default) 技能/<技能名称>/SKILL.md Directly overwrite the source file, ensuring the prerequisites版本are updated, and include a change summary in the output, which counts as an audit
Fixed temp(Opt-out) skills/<技能名称>/SKILL.refined.md Use when the user requests "do not modify the original file, only provide the refinement"; each run overwrites the same temporary file
New per run(Opt-out) skills/<技能名称>/SKILL.refined.YYYYMMDD.md Use when the user requests "keep a separate file for this refinement"; each run creates a new refinement file

User override: if the user specifies a path or policy, follow it. Otherwise usedirect overwrite。

Limits (Restrictions)

Hard Boundaries

  • Default overwrite but must be auditable: The default policy is to directly overwrite the source SKILL.md, but the frontmatter's versionmust be updated in sync, and a complete change summary must be provided in the output to ensure auditability.
  • Respect explicit "draft mode" requests: If the user explicitly requests "do not modify the original file", "only generate a refined draft", etc., then the source must not be overwrittenSKILL.md, and only a temporary or newly created refined file may be written.
  • Do not change the intent: Optimization must preserve the core purpose of the skill.
  • Minimize prose: Prefer lists and tables over long README-style text.
  • Multiple examples: Do not keep only one "happy path" example; include at least one challenging or edge-case example.

Skill Boundaries (Avoid Overlap)

Do not do these (other skills can handle them)：

  • Create a new skill from scratch: Generate the initial skill structure and content → use "Skill Creator" (e.g., anthropics/skills)
  • Project documentation: Generate README → use generate-standard-readme; generate AGENTS.md → use generate-agent-entry
  • Text decontextualization: Remove PII or sensitive information → use decontextualize-text

When to stop and hand off：

  • The user says "looks good", "approved", "commit this" → refinement is complete, hand off to the user for version control
  • The user asks "How do I create a new skill?" → hand off to the Skill Creator documentation

Self-Check

Core success criteria (all criteria must be met)

  • Structural compatibility: The skill follows the standard template (YAML, purpose, use cases, behavior, inputs and outputs, limits, self-check, examples)
  • Clear logic: The input → behavior → output chain is clear and explicit
  • Defined constraints: The limits section covers common failure modes in the domain
  • Comprehensive examples: Provide at least 2 examples, including an edge case or challenging scenario
  • Documented changes: The diff summary lists all changes along with section, description, and reason
  • Suggested version: Provide a SemVer suggestion and explain the rationale

Process quality checks

  • Self-hosting: Can this skill successfully act on itself (refine itself)?
  • Clarity: Can an agent without domain context reproduce the behavioral results?
  • Compliance: Are all required sections and metadata fields present?
  • Intent preservation: Does the refined skill preserve the core purpose of the original skill?
  • Precision: Are the verbs specific and explicit (not vague terms like "handle")?
  • Interaction strategy(Spec §4.3): Does the behavior have default or choice-based interaction (if applicable)?
  • Triggers(optional): For high-discoverability skills, is the use of "triggers" recommended?

Acceptance tests

Can an AI agent consistently apply this refined skill across different environments without ambiguity?

If no: the skill needs further refinement. Review the "Behavior" section to ensure clarity and add more specific instructions.

If yes: refinement is complete. Provide the user with a summary of the differences and a version recommendation.

Example (example)

Before

Name: Spell Check This skill checks spelling. Input: multilingual text. Output: corrected text.

After

Name: Polish-Text-Spelling Description: Context-aware spelling and terminology correction for multilingual documents. Tags: [writing, quality control] Version: 1.1.0

Skill: Spelling and Terminology

Purpose: Identify and fix low-level spelling errors and terminology inconsistencies without changing the author's intent or tone

Behavior

  1. Detect the language.
  2. If the text is long, build a terminology list.
  3. Distinguish between "typos" and "intentional style".

Constraints: Do not change proper nouns or specific abbreviations unless they are clearly erroneous

Example 2: Edge case — ambiguous draft

  • Input: A skill draft whose purpose is to "help users handle files", with no use cases or constraints.
  • Expected: Determine the intent (replace "handle" with a specific verb: parse, convert, merge, etc.); add use cases and constraints (e.g., do not overwrite source code; do not modify binary files); add at least one edge example (e.g., empty file, very large file, permission denied).