Skill Creator
This skill provides Chinese guidance for creating effective skills.
About Skills
Skills are modular, self-contained packages that extend AI capabilities by providing specialized knowledge, workflows, and tools. Think of them as "starter kits" for specific domains or tasks—they transform AI from a general-purpose agent into a specialized agent equipped with procedural knowledge that models don't fully possess.
What Skills Provide
- Specialized Workflows - Domain-specific multi-step procedures
- Tool Integrations - Instructions for handling specific file formats or APIs
- Domain Expertise - Company-specific knowledge, patterns, business logic
- Bundled Resources - Scripts, references, and assets for complex and repetitive tasks
Core Principles
Brevity is Key
Context window is a shared resource. Skills share the context window with everything the AI needs: system prompts, conversation history, metadata from other skills, and the actual user request.
Default Assumption: AI is already intelligent. Only add context that the AI doesn't already have. Challenge every piece of information: "Does the AI really need this explanation?" and "Is this paragraph worth its token cost?"
Prefer concise examples over lengthy explanations.
Set Appropriate Degrees of Freedom
Match the level of specificity to the fragility and variability of the task:
High Freedom (Text-based Instructions): Use when multiple methods work, decisions depend on context, or heuristic guidance is appropriate.
Medium Freedom (Pseudocode or Scripts with Parameters): Use when there's a preferred pattern, some variation is acceptable, or configuration affects behavior.
Low Freedom (Specific Scripts, Few Parameters): Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
Treat the AI like exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
Skill Anatomy
Each skill consists of a required SKILL.md file and optional bundled resources. For detailed directory structure specifications, refer to
, which defines the complete structural requirements for skills in JSON format, including mandatory and optional components.
SKILL.md (Required)
Each SKILL.md consists of:
- Frontmatter (YAML): Contains and fields. These are the only fields read by AI to determine when to use the skill, so it's crucial to clearly and comprehensively describe what the skill is and when to use it.
- Body (Markdown): Instructions and guidance for using the skill. Only loaded (if any) after the skill is triggered.
Bundled Resources (Optional)
Scripts ()
Executable code (Python/Bash/etc.) for tasks requiring deterministic reliability or repeated rewriting.
- When to Include: When rewriting the same code repeatedly or deterministic reliability is needed
- Example: for PDF rotation tasks
- Benefits: Token-efficient, deterministic, can execute without loading into context window
- Note: Scripts may still need to be read by AI for patching or environment-specific adjustments
References ()
Documents and references designed to be loaded into context as needed to inform AI's processes and thinking, including sample code, templates, and detailed examples.
- When to Include: For documents the AI should reference while working, including sample code and templates
- Examples: for financial patterns, for company NDA templates, for company policies, for API specifications,
references/code_examples.md
- Use Cases: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides, sample code, template code
- Benefits: Keeps SKILL.md lean, only loaded when AI determines it's needed
- Best Practice: If a file is large (>10k words), include grep search patterns in SKILL.md
- Avoid Duplication: Information should be in either SKILL.md or one of the reference files, not both. Prefer reference files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without occupying the context window. Only keep basic procedural instructions and workflow guidance in SKILL.md; move detailed references, patterns, and examples to reference files.
What Not to Include in Skills
Skills should only contain necessary files that directly support their functionality. Do not create unrelated documentation or auxiliary files, including:
- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md
- etc.
Skills should only include the information AI agents need to complete the task at hand. It should not contain auxiliary context about the creation process, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files only adds confusion.
Progressive Disclosure Design Principles
Skills use a three-level loading system to manage context efficiently:
- Metadata (name + description) - Always in context (~100 words)
- SKILL.md Body - When the skill is triggered (<5k words)
- Bundled Resources - As needed by AI (unlimited, since scripts can execute without being read into the context window)
Progressive Disclosure Patterns
Keep the SKILL.md body basic and under 500 lines to minimize context bloat. When approaching this limit, split content into separate files. When splitting content into other files, it's critical to reference them from SKILL.md and clearly describe when to read them, to ensure the skill's reader knows they exist and when to use them.
Key Principle: When a skill supports multiple variants, frameworks, or options, only keep core workflows and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configurations) to separate reference files.
Pattern 1: High-level Guide with References
markdown
# PDF Processing
## Quick Start
Use pdfplumber to extract text:
[Code Example]
## Advanced Features
- **Form Filling**: See [FORMS.md](FORMS.md) for complete guide
- **API Reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
AI only loads FORMS.md, REFERENCE.md, or EXAMPLES.md when needed.
Pattern 2: Domain-specific Organization
For skills with multiple domains, organize content by domain to avoid loading irrelevant context:
bigquery-skill/
├── SKILL.md (Overview and Navigation)
└── reference/
├── finance.md (Revenue, Billing Metrics)
├── sales.md (Opportunities, Pipeline)
├── product.md (API Usage, Features)
└── marketing.md (Campaigns, Attribution)
When users ask about sales metrics, AI only reads sales.md.
Similarly, for skills supporting multiple frameworks or variants, organize by variant:
cloud-deploy/
├── SKILL.md (Workflow + Provider Selection)
└── references/
├── aws.md (AWS Deployment Patterns)
├── gcp.md (GCP Deployment Patterns)
└── azure.md (Azure Deployment Patterns)
When users select AWS, AI only reads aws.md.
Pattern 3: Conditional Details
Show basic content, link to advanced content:
markdown
# DOCX Processing
## Create Document
Use docx-js to create new documents. See [DOCX-JS.md](DOCX-JS.md).
## Edit Document
For simple edits, modify XML directly.
**For Track Changes**: See [REDLINING.md](REDLINING.md)
**For OOXML Details**: See [OOXML.md](OOXML.md)
AI only reads REDLINING.md or OOXML.md when users need these features.
Important Guidelines:
- Avoid Deeply Nested References - Keep references one level deep from SKILL.md. All reference files should be linked directly from SKILL.md.
- Structure Longer Reference Files - For files over 100 lines, include a table of contents at the top so AI can see the full scope when previewing.
Skill Creation Process
Skill creation involves these steps:
- Understand the skill through concrete examples
- Plan reusable skill content (scripts, references, assets)
- Initialize the skill (See
references/skill-initialization-guide.md
- Edit the skill (Implement resources and write SKILL.md)
- Validate the skill (See
references/skill-validation-guide.md
- Package the skill (See
references/skill-packaging-guide.md
- Iterate based on actual usage
Follow these steps in order, skipping only when there's a clear reason.
Step 1: Understand the Skill through Concrete Examples
Skip this step only if the usage patterns of the skill are already clearly understood. It's still valuable even when working with existing skills.
To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from direct user examples or generated examples validated through user feedback.
For example, when building an image editor skill, relevant questions include:
- "What features should the image editor skill support? Editing, rotation, or others?"
- "Can you give some examples of how this skill will be used?"
- "I can imagine users asking things like 'Remove red-eye from this image' or 'Rotate this image'. Are there other ways you envision this skill being used?"
- "What should users say to trigger this skill?"
To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important ones, and follow up as needed for better results.
End this step when there's a clear understanding of the features the skill should support.
Step 2: Plan Reusable Skill Content
To turn concrete examples into an effective skill, analyze each example by:
- Considering how to execute the example from scratch
- Identifying scripts, references, and assets that would be useful for repeated execution of these workflows
Example: When building a
skill to handle queries like "Help me rotate this PDF", analysis shows:
- Rotating PDFs requires rewriting the same code every time
- A script would be helpful to store in the skill
Example: When designing a
skill for queries like "Build a to-do app for me" or "Build a step-tracking dashboard for me", analysis shows:
- Writing frontend webapps requires the same HTML/React boilerplate every time
- A
references/code-examples.md
Example: When building a
skill to handle queries like "How many users logged in today?", analysis shows:
- Querying BigQuery requires rediscovering table schemas and relationships every time
- A file recording table schemas would be helpful to store in the skill
To build the skill's content, analyze each concrete example to create a list of reusable resources to include: scripts, references, and assets.
Step 3: Initialize the Skill
At this point, it's time to actually create the skill.
Skip this step only if the skill being developed already exists and needs iteration or packaging. In that case, proceed to the next step.
When creating a new skill from scratch, follow the detailed steps in
references/skill-initialization-guide.md
. This guide provides complete instructions for creating the skill directory structure, generating the SKILL.md template, and setting up initial resource directories.
Step 4: Edit the Skill
When editing a (newly generated or existing) skill, remember that the skill is being used by another AI instance. Include information that is beneficial and non-obvious to the AI. Consider what procedural knowledge, domain-specific details, or reusable assets will help another AI instance perform these tasks more effectively.
Learn Proven Design Patterns
Consult these helpful guides based on your skill needs:
- Multi-step Processes: See for sequential workflows and conditional logic
- Specific Output Formats or Quality Standards: See
references/output-patterns.md
- Skill Structure Anatomy: See for complete directory structure specifications
These files contain established best practices for effective skill design.
Start with Reusable Skill Content
To begin implementation, start with the reusable resources identified above:
and
files. Note that this step may require user input. For example, when implementing a
skill, users may need to provide documents or sample code to be stored in
.
Added scripts must be tested by actually running them to ensure there are no errors and the output meets expectations. If there are many similar scripts, only test representative samples to ensure confidence in their effectiveness while balancing completion time.
Any unnecessary example files and directories should be deleted. The initialization process creates example files in
and
to demonstrate the structure, but most skills won't need all of them.
Update SKILL.md
Writing Guideline: Always use imperative/infinitive form.
Frontmatter
Write the YAML frontmatter with
and
:
- : Skill name
- : This is the main trigger mechanism for your skill, helping AI understand when to use it.
- Include both what the skill does and specific triggers/contexts for when to use it.
- Include all "when to use" information here—not in the body. The body is only loaded after triggering, so a "when to use this skill" section in the body is useless to AI.
- Example description for a skill: "Comprehensive document creation, editing, and analysis, supporting track changes, comments, format preservation, and text extraction. Use when AI needs to handle professional documents (.docx files) for: (1) creating new documents, (2) modifying or editing content, (3) handling track changes, (4) adding comments, or any other document tasks"
Do not include any other fields in the YAML frontmatter.
Body
Write instructions for using the skill and its bundled resources.
Important: All generated skills should have their SKILL.md written in Chinese, including descriptions and body content, to match users' language preferences.
Step 5: Validate the Skill
Once skill development is complete, validate its structure and content before packaging or distribution. Follow the detailed checklist in
references/skill-validation-guide.md
to ensure the skill meets all standards and works properly.
Step 6: Package the Skill
After passing validation, package the skill into a distributable .skill file. Follow the steps in
references/skill-packaging-guide.md
to create a ZIP-format package file for easy distribution and installation.
Step 7: Iterate
After testing the skill, users may request improvements. This usually happens shortly after using the skill, with fresh context on the skill's performance.
Iteration Workflow:
- Use the skill on actual tasks
- Note struggles or inefficiencies
- Identify how SKILL.md or bundled resources should be updated
- Implement changes and test again