Skill Designer: High-Quality Skill Design Guide

The Problem: Skill Design as "Ad-Hoc Writing"

A common pitfall in creating AI skills is jumping straight into writing SKILL.md and scripts. This leads to a vague design process, loose structure, hard-to-reuse outputs, and frequent gaps in functional boundaries, trigger conditions, and input/output contracts. The resulting skill may fail to work stably or behave inconsistently across scenarios.

skill-designer is not a code generator; it is a meta-skill providing a systematic design methodology. It forges vague ideas into a comprehensive "skill blueprint" through a fixed sequence of ten building blocks (B01–B10). This blueprint becomes the single source of truth for subsequent development (e.g., handoff to skill-creator).

Core Workflow: Constructing the Skill Blueprint

The design follows a fixed main pipeline where each step produces a block file, collectively forming the blueprint:

• Start & Path Selection: Phase 0 clarifies the platform, entry point (create/improve), and channel (lightweight MVP ~30min or full ~2h). Immediately run scripts/init_blueprint.py to persist the blueprint to disk, preventing reliance on session memory.
• Ten Building Blocks (B01-B10):
  1. B01 Conditions: Use the "four准入 questions" to determine if the skill is worth building.
  2. B02 Facts: Define the target user persona and use case scenarios. Check for ecosystem overlap.
  3. B03 Viewpoints: Select a design prescription based on interaction and content patterns, providing rationale.
  4. B04 Problems: List all pending requirements and define the decision-maker.
  5. B05 Analysis: Define input/output contracts and assess potential risks.
  6. B06 Decisions: Make a solution choice (e.g., split or merge) and agree on output file conventions.
  7. B07 Plan: Draft a construction map: directory skeleton and execution sequence. Generate a visual map with scripts/visualize_blueprint.py.
  8. B08 Action: Validate with real-world scenarios, comparing performance with and without the skill.
  9. B09 Results: Pass the quality gate. IQS (blueprint completeness) is machine-calculated by check_blueprint.py. BR-5 five-dimension readiness is human-evaluated. Generate a summary visualization with scripts/b09_summary.py.
  10. B10 Retrospective: Summarize failures into generic, reusable rules. Promote these rules to a cross-task experience library (lessons.md).

The process is supported by helper scripts (e.g., check_blueprint.py for resumption and gap checking), but degrades gracefully to pure conversational guidance if scripts are unavailable.

Applicability & Key Disciplines

• What It Is: A design guide and blueprint builder. It guides the creation of a design document (blueprint), not the direct coding of the skill. Once finalized, the blueprint must be handed off to other tools (like skill-creator) for implementation.
• What It Is Not: It is not for installing, recommending, or scheduling existing skills, nor for writing one-off scripts or casual concept discussions.
• Critical Disciplines:
• Hard Block: The skill's trigger words and name must be confirmed by the user; the AI cannot fill them in.
• Decision Ownership: The designer provides drafts and rationale, but key decisions—requirement validation, design pattern selection, scoring confirmation—are always made by the user.
• Blueprint as Single Source of Truth: Any subsequent development that deviates from the blueprint should trigger a correction back to the blueprint, not be silently accepted.

This guide aims to shift skill design from "inspiration-driven" to "structure-driven," ensuring the output consists of linkable, reusable, and measurable capability modules.