SuperAPI AI Directory

skill-creator-yashu

General & other

View repository

Updated 10-16 08:46

About this skill

🎯 Trigger Mapping

User input trigger words AI action
"create skill" / "new skill" / "add skill" / "initialize skill" Execute according to [Create Mode]

Create Mode

Execution steps

Step Action Specific command/operation
1 Ask for requirements Run AskUserQuestion to ask the user about the skill's functionality, use cases, and trigger conditions
2 Initialize directory Run RunCommand to execute python scripts/init_skill.py <skill-name> --path <output-dir>
3 Read and edit SKILL Run Read to read the generated SKILL.md, run SearchReplace to fill in the functionality description and trigger conditions
4 Validate structure Run RunCommand to execute python scripts/quick_validate.py <skill-directory>

Output result

Example output on success:

✅ Skill '{skill-name}' 创建成功

📁 目录结构:
.trae/skills/{skill-name}/
├── SKILL.md          # 技能文档(已填充模板)
├── scripts/          # 脚本目录
│   └── example.py    # 示例脚本
└── references/       # 参考文档目录
    └── README.md     # 参考说明

📝 下一步:
运行 `Read` 读取 SKILL.md,根据用户需求编辑功能描述和触发条件

Example output on failure:

❌ Skill 创建失败

错误原因:{具体错误信息}
解决建议:{针对性解决方案}

Error handling

Error scenario Error manifestation Handling method
Directory already exists mkdir error: directory already exists Run LS to check the directory contents; if empty, continue; if it has contents, ask the user whether to overwrite
Script execution failed Python returns a non-zero exit code Check the Python version and dependency installation, and retry execution
Insufficient permissions File write denied Check directory permissions and suggest the user change the output directory
Invalid skill name Contains uppercase letters or special characters Prompt the user to change it to kebab-case format (e.g. my-skill)

Core principles

Concise is Key

The context window is a shared resource. Skills share the context window with the system prompt, conversation history, metadata of other skills, and the user request.

Default assumption: the AI is already very smart. Only add information the AI does not have. Question every piece of information: "Does the AI really need this explanation?" "Is this text worth its token cost?"

Prefer concise examples over lengthy explanations.

Set the appropriate degree of freedom

Match the appropriate level of detail according to the fragility and variability of the task:

Degree of freedom Applicable scenario Form
High degree of freedom Multiple methods are valid, decisions depend on context, heuristic guidance method Text-based instructions
Medium degree of freedom A preferred pattern exists, some variation is allowed, configuration affects behavior Pseudocode or scripts with parameters
Low degree of freedom Operations are fragile and error-prone, consistency is critical, a specific sequence must be followed Specific scripts, few parameters

AI-Friendly

Skills are for AI use, it must be ensured that AI can accurately understand and execute them. The created skill must meet the following AI-friendliness standards:

Check item Requirement Description
Clear description Must The description in frontmatter must include the functionality and trigger conditions
Explicit instructions Must Use imperative sentences (run, execute, call, etc.) rather than vague suggestions
Specific examples Must Provide code examples or user request examples; AI needs to know exactly how to do it
Decision logic Recommended For complex tasks, provide conditional judgments or a decision tree to help AI make the correct choice
Output format Must Clearly state what content the skill should output
Error handling Recommended Explain exceptional situations and boundary handling
Avoid long paragraphs Recommended Paragraphs exceeding 500 characters are difficult to extract key information from; use lists or tables
File reference description Must Referenced files must have Markdown link descriptions

Optimization tips:

  • Imagine you are AI: after reading the skill, can you know: when to use it? How to use it? What to output?
  • Use specific rather than abstract vocabulary
  • Provide clear operational steps rather than vague guidance
  • Provide a decision process for complex scenarios

Key points of the Agent Skills specification

Directory structure

skill-name/
├── SKILL.md          # 必需:技能文档
├── scripts/          # 可选:可执行代码
├── references/       # 可选:参考文档
└── assets/           # 可选:模板、资源

Files that should not be included: README.md, INSTALLATION_GUIDE.md, CHANGELOG.md, and other auxiliary documents.

SKILL.md format

Required frontmatter metadata:

---
name: skill-name
description: 功能描述。何时使用:当用户说/需要/遇到...时
---

name field rules

  • 1-64 characters, can only contain lowercase letters, numbers, and hyphens
  • Cannot start or end with a hyphen, and cannot contain consecutive hyphens --
  • Must match the parent directory name

description field rules

  • 1-1024 characters
  • Must contain two parts, separated by 何时使用: :
    1. Functional description - what this skill does
    2. When to use - what the user says to trigger this skill
  • All trigger condition information should be placed in the description - do not place it in the body

Good examples:

description: 分析并优化其他 Skill 的文档质量问题,包括 frontmatter 格式、渐进式披露结构等检查。何时使用:当用户说"优化这个 skill"、"检查 skill 质量"、"review skill"时。

Bad examples:

# ❌ 缺少"何时使用"部分
description: 分析并优化 Skill 的文档质量问题

# ❌ 使用"触发条件"而非"何时使用"
description: 分析 Skill 质量问题。触发条件:用户说优化 skill 时

Progressive disclosure design

Skills use a three-level loading system to efficiently manage context:

  1. Metadata(name + description) - always in context (about 100 words)
  2. SKILL.md body - loaded when the skill is triggered (recommended < 5000 words, < 500 lines)
  3. Bundled resources - loaded by AI on demand

Key principles: When a skill supports multiple variants, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details to separate reference files.

Progressive disclosure pattern

Pattern 1: Advanced guide + reference

## 快速开始

[核心代码示例]

## 高级功能

- **表单填写**:参见 [FORMS.md](references/FORMS.md) 完整指南
- **API 参考**:参见 [REFERENCE.md](references/REFERENCE.md)

Pattern 2: Organized by domain

skill-name/
├── SKILL.md (概览和导航)
└── references/
    ├── finance.md
    ├── sales.md
    └── product.md

Important guidelines:

  • Avoid deep nested references; keep referenced files within the first-level subdirectory of SKILL.md
  • Avoid duplication: information should exist only in SKILL.md or the reference files, not both

SKILL.md structure patterns

Choose the structure that best fits the skill's purpose:

Pattern Applicable scenarios Structure
Workflow-based Sequential process ## 概览 → ## 工作流程决策树 → ## 步骤 1...
Task-based Tool collection ## 概览 → ## 快速开始 → ## 任务类别 1...
Reference/guide Standard or specification ## 概览 → ## 指南 → ## 规范
Capability-based Integrated system ## 概览 → ## 核心能力 → ### 1. 功能...

Patterns can be mixed and matched.

Skill creation process

Perform the following steps in order:

Skill creation process

Perform the following steps in order:

Step Action to perform Specific command/operation
1 Ask about functional requirements Run AskUserQuestion Ask about the skill's functionality, usage examples, and trigger conditions
2 Plan reusable resources Analyze requirements and determine the needed scripts, references, and assets
3 Initialize the Skill directory Run RunCommand Execute python scripts/init_skill.py <skill-name> --path <output-directory>
4 Read SKILL.md Run Read Read the generated .trae/skills/{skill-name}/SKILL.md
5 Edit the functionality description Run SearchReplace Fill in the description, trigger conditions, and execution steps
6 Create scripts If scripts are needed, run Write Create to the scripts/ directory
7 Create reference documents If reference documents are needed, run Write Create to the references/ directory
8 Validate the structure Run RunCommand Execute python scripts/quick_validate.py <skill-directory>
9 Test and iterate Based on the validation results, run SearchReplace Fix issues

Workflow patterns

For detailed workflow patterns (sequential, conditional, decision tree, loop, error handling), see Workflow patterns documentation。

Output patterns

For detailed output patterns (templates, examples, checklists), see Output patterns documentation。

Bundled resources

scripts/

Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or repeated rewriting.

  • When to include: when the same code is repeatedly rewritten or deterministic reliability is required
  • Benefits: Token-efficient, deterministic, can be executed without loading into context
  • AI-friendly principles: The input and output of the code should be AI-friendly
    • Input: support command-line arguments, environment variables, or structured data (JSON/YAML); avoid interactive prompts
    • Output: use structured formats (JSON/YAML/tables) with explicit field names; avoid natural language descriptions that require parsing
    • Error handling: return standard exit codes, output error messages to stderr, and output successful results to stdout

references/

Documentation and reference materials, intended to be loaded into context as needed.

  • When to include: Detailed documentation that AI should refer to when working
  • Benefits: Keep SKILL.md concise, loading only when needed

assets/

Files not intended to be loaded into context, but used in the output produced by AI.

  • When to include: Files that the skill needs to use in the final output (templates, images, etc.)
  • Benefits: Separate output resources from documentation

Utility scripts

Script Purpose Command
init_skill.py Initialize a new skill python scripts/init_skill.py <skill-name> --path <output-dir>
skill_templates.py Template definition module Called by init_skill.py, contains SKILL.md and example file templates
quick_validate.py Quick validation python scripts/quick_validate.py <skill-directory>
create-skill.py Create a complete skill python scripts/create-skill.py <skill-name>

Create an example

User input: "Create a skill for handling PDFs"

Execution steps:

Step Execution action Specific command/operation
1 Ask about the scenario Run AskUserQuestion to ask about the specific usage scenario (extracting text, filling forms, merging, etc.)
2 Plan the content Analyze the requirements and determine that a Python script is needed to handle PDFs
3 Initialize the directory Run RunCommand to execute python scripts/init_skill.py pdf-processor --path ./skills
4 Read SKILL.md Run Read to read ./skills/pdf-processor/SKILL.md
5 Edit the description Run SearchReplace to fill in the description as "Handle PDF files. When to use: when the user says to handle a PDF"
6 Create the processing script Run Write to create scripts/pdf_extractor.py
7 Validate the structure Run RunCommand to execute python scripts/quick_validate.py ./skills/pdf-processor