SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscreate-skill

create-skill

Writing & research

View repository

Updated 10-15 20:34

About this skill

Create Skill (this repository's conventions)

1) Directory structure and naming

One directory per skill, with the directory name matching the frontmatter's name exactly the same：

  • name Constraints:
    • Only lowercase letters/digits/hyphens allowed:a-z、0-9、-
    • cannot start with - or end with it
    • cannot contain consecutive --

Recommended structure:

skills/<skill-name>/
  SKILL.md
  scripts/        # 可选：可执行工具
  references/     # 可选：按需阅读的资料
  assets/         # 可选：模板/静态文件

2) SKILL.md (required)

2.1 Frontmatter (required: name / description)

---
name: your-skill-name
description: 用一句话说明“做什么 + 何时使用（包含关键词）”。
---

Other fields can be added as needed; this repository does not mandate them, but keeping it concise is recommended.

description Requirements:

  • Non-empty
  • Must cover both "what it does" + "when to use it"
  • Include as many keywords as possible that users would actually say (to improve trigger hit rate)

2.2 Body (write only the shortest usable workflow)

The body should only keep the information that lets the user (human or AI) start executing directly. Put lengthy background/materials in references/, and put templates/static files in assets/。

Recommended order (keep or omit as needed):

  1. One-sentence description (what this is / what it solves)
  2. Quick start (shortest copyable example)
  3. Common scenarios/commands (3-7 is appropriate)
  4. Output conventions (e.g. for machine-readable output, specify --json and other conventions)
  5. How to look up uncommon parameters (--help + reference pointers)
  6. Resources (pointing to scripts/references/templates)

Minimal skeleton (copy and rename):

---
name: your-skill-name
description: 做什么；何时使用（关键词）。
---

一句话说明。

## Quick start

```bash
cd skills/your-skill-name && ./scripts/your_tool.py --help
```

## 常用场景
- `./scripts/your_tool.py ...`

## 冷门参数怎么查
- `./scripts/your_tool.py --help`
- 需要字段细节时读：见 [api.md](references/api.md)

## 资源
- [tool.py](scripts/tool.py)

3) scripts/ (optional)

If a workflow needs "deterministic execution" or is frequently repeated, prefer writing it as an executable script and placing it in scripts/, and provide copyable commands in SKILL.md .

This repository's conventions for Python scripts (must be stated clearly in SKILL.md):

  • Uniformly execute directly via ./scripts/... (do not use uv run python ... / python ...）
  • workdir convention: by default use the directory where the current SKILL.md is located as the workdir; if example commands need cd, state it clearly (usually cd skills/<skill-name>）
  • When referencing scripts/resource files in SKILL.md , prefer using Markdown URLs (the link text should be only the filename as much as possible)

Key points of the Python script specification:

  • Run mode: must use uv script mode (shebang is #!/usr/bin/env -S uv run --script）。
  • Initialization: for new scripts use uv init --script scripts/foo.py(generates the shebang and an empty /// script metadata block).
  • Dependency declaration (strong constraint)：
    • The script header's /// script metadata block is the only place for dependency declarations.
    • Manually editing the dependency block is prohibited; adding/removing dependencies must be done via uv add --script ... / uv remove --script ... .
    • After removing a dependency reference, if it is confirmed no longer used, that dependency should also be removed.
  • CLI form：
    • For command-line arguments, prefer Typer.
    • For discrete optional values (such as format、view、profile、column , etc.), prefer using Enum or Literal for type annotation, rather than describing the optional values only in the help text; this way Typer can automatically in --help displays candidate values, improving readability and discoverability.
    • Trade-off recommendation: for a small number of one-off enum values, prefer using Literal; when reuse, centralized management, or a larger number of values is needed, prefer using Enum。
    • For output prompts/tables, prefer rich (improves readability).
    • For data models and parameter validation, prefer pydantic (failure messages are clear and easy to locate).
    • Use lowercase for the Typer application instance variable name app。
    • If there is only one command, prefer using typer.run(main), avoiding tool.py foo <arg> which adds an extra layer of subcommands.
  • Maintainability: Every module, function, and type should include a brief Chinese docstring.
  • Quality checks: After completion, it is recommended to run:
    • uv run ruff check <path>
    • uv run ruff format <path>

Common uv --script workflows (used to create/maintain script dependencies):

# 在 skill 目录内新建脚本（会生成 shebang 与 /// script 依赖块）
uv init --script scripts/foo.py

# 给脚本添加依赖（会更新脚本头部 dependencies；不要手工改依赖块）
uv add --script scripts/foo.py typer rich

# 从脚本移除依赖
uv remove --script scripts/foo.py rich

# 赋予可执行权限并运行
chmod +x scripts/foo.py
./scripts/foo.py --help

4) references/ and assets/ (optional)

  • references/: Store long materials to be read on demand (protocols/API fields/glossaries). In SKILL.md , clearly state "when you need to read which file".
  • assets/: Store templates/static files. In SKILL.md , give the shortest explanation of "how to use this file".

Reference rules (recommended):

  • Use relative paths for links or paths (relative to skills/<skill-name>/）
  • Aim for "one hop away":SKILL.md points directly to the target file, avoiding multi-level chained references
  • For link text, write only the file name as much as possible (put the path in the link target)

Example (Markdown link syntax):

见 [api.md](references/api.md)
运行 [tool.py](scripts/tool.py)

5) Content length (tokens)

  • SKILL.md Recommended body text < 5000 tokens
  • You can use token_count.py to count tokens (scripts and parameters do not depend on workdir, as long as paths are written correctly):
cd skills/<skill-name>
../../scripts/token_count.py SKILL.md

6) Pre-submission self-check list

  • Directory name == SKILL.md 's name
  • frontmatter contains at least name / description, and description clearly states "what it does + when to use it (keywords)"
  • SKILL.md has a copyable Quick start (if it depends on the working directory or environment variables, this must be clearly stated in the example)
  • If there are scripts: the example uses ./scripts/... directly (do not use uv run python/python）
  • If there are scripts: dependencies are declared only in /// script (do not manually edit the dependency block); modules/functions/types have brief Chinese docstrings
  • If there are scripts: it is recommended to run ruff (uv run ruff check ... / uv run ruff format ...）
  • references//assets/ references are clear, and SKILL.md can reach the target file in one hop
  • SKILL.md token count is within the recommended range