mirror of
https://github.com/zhayujie/chatgpt-on-wechat.git
synced 2026-07-19 12:47:25 +08:00
feat(skill): multi-provider image generation with auto-fallback
- Add Gemini, Seedream (Volcengine Ark), Qwen (DashScope), MiniMax providers to image-generation skill with universal sequential fallback: OpenAI → Gemini → Seedream → Qwen → MiniMax → LinkAI - Each provider filters unsupported size tiers to valid values (e.g. Seedream 1K→2K, Qwen 3K→2K, Gemini 3K→2K) - Pinned model only tries its native provider; auto-routing uses each provider's default model - Support skill-namespaced config (config.skill.image-generation.model → SKILL_IMAGE_GENERATION_MODEL env var) - Add image lightbox (click-to-enlarge) in web console - Add docs for built-in skills (skill-creator, knowledge-wiki, image-generation) under docs/skills/
This commit is contained in:
zhayujie
180
docs/en/skills/skill-creator.mdx
Normal file
180
docs/en/skills/skill-creator.mdx
Normal file
@@ -0,0 +1,180 @@
|
||||
---
|
||||
title: skill-creator - Skill Creator
|
||||
description: Create, install, and update skills — standardises SKILL.md format and directory structure
|
||||
---
|
||||
|
||||
`skill-creator` is a "meta-skill" that helps the Agent create, install, and update other skills, ensuring every skill follows a consistent `SKILL.md` format and directory layout.
|
||||
|
||||
## When It Triggers
|
||||
|
||||
- The user wants to install a skill from a URL or remote repository
|
||||
- The user wants to create a brand-new skill from scratch
|
||||
- An existing skill needs upgrading or restructuring
|
||||
|
||||
## What Is a Skill?
|
||||
|
||||
A skill is a reusable instruction set plus optional scripts and assets. It injects domain expertise into the Agent so it can handle specific tasks like a specialist.
|
||||
|
||||
A skill typically contains:
|
||||
|
||||
1. **Specialised workflow** — step-by-step instructions for a category of tasks
|
||||
2. **Tool usage** — how to call a particular API or process a particular file format
|
||||
3. **Domain knowledge** — team conventions, business rules, data schemas, etc.
|
||||
4. **Attached resources** — scripts, reference docs, templates, etc.
|
||||
|
||||
<Note>
|
||||
**Core principle: less is more.** Only write what the Agent wouldn't figure out on its own. For every line you add, ask yourself: is it worth the tokens?
|
||||
</Note>
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md # Required: skill definition
|
||||
│ ├── YAML frontmatter (name / description are mandatory)
|
||||
│ └── Markdown body (instructions + examples)
|
||||
└── Optional resources
|
||||
├── scripts/ # Executable scripts (Python / Bash, etc.)
|
||||
├── references/ # Large reference docs the Agent reads on demand
|
||||
└── assets/ # Templates, icons, etc. used directly in output
|
||||
```
|
||||
|
||||
## SKILL.md Specification
|
||||
|
||||
Frontmatter fields in the SKILL.md header:
|
||||
|
||||
| Field | Description |
|
||||
| --- | --- |
|
||||
| `name` | Skill name — lowercase with hyphens, must match the directory name |
|
||||
| `description` | **The most important field.** Clearly state what the skill does and when to use it. The Agent reads this to decide whether to invoke it. All trigger-related descriptions go here, not in the body |
|
||||
| `metadata.cowagent.requires.bins` | System CLI tools that must be installed |
|
||||
| `metadata.cowagent.requires.env` | Required environment variables (all must be present) |
|
||||
| `metadata.cowagent.requires.anyEnv` | Multiple API keys — at least one must be set |
|
||||
| `metadata.cowagent.requires.anyBins` | Multiple tools — at least one must be installed |
|
||||
| `metadata.cowagent.always` | Set to `true` to always load, skipping dependency checks |
|
||||
| `metadata.cowagent.emoji` | Display emoji (optional) |
|
||||
| `metadata.cowagent.os` | OS restriction, e.g. `["darwin", "linux"]` |
|
||||
|
||||
<Note>
|
||||
The `category` field does not need to be set manually — the system automatically sets it to `skill`.
|
||||
</Note>
|
||||
|
||||
Two ways to declare API key dependencies:
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
cowagent:
|
||||
requires:
|
||||
env: ["MYAPI_KEY"] # Must be present
|
||||
```
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
cowagent:
|
||||
requires:
|
||||
anyEnv: ["OPENAI_API_KEY", "LINKAI_API_KEY"] # At least one
|
||||
```
|
||||
|
||||
**Skills are auto-enabled/disabled based on dependencies**: they activate when all required environment variables are present and deactivate when any are missing — no need for manual `/skill enable`.
|
||||
|
||||
## Resource Directories
|
||||
|
||||
| Directory | What goes here | What does NOT go here |
|
||||
| --- | --- | --- |
|
||||
| `scripts/` | Code that needs to run repeatedly, or scripts that produce deterministic results | Demo-only code snippets |
|
||||
| `references/` | Documents **over 500 lines** that genuinely won't fit in SKILL.md (e.g. a full DB schema) | General API docs, tutorials, examples |
|
||||
| `assets/` | Files that appear in the final output (templates, icons, boilerplate, etc.) | Explanatory documentation |
|
||||
|
||||
<Warning>
|
||||
**In principle, everything goes in `SKILL.md`** — only split into resource directories when it truly won't fit.
|
||||
|
||||
Do not add `README.md`, `CHANGELOG.md`, or `INSTALLATION_GUIDE.md` to a skill — put everything in `SKILL.md`. Resource directories should only contain scripts that actually run or assets that are actually used.
|
||||
</Warning>
|
||||
|
||||
## Installing External Skills
|
||||
|
||||
After installation, the skill lands in `<workspace>/skills/<name>/`.
|
||||
|
||||
| Source | How to install |
|
||||
| --- | --- |
|
||||
| URL (single file) | curl / web_fetch |
|
||||
| URL (zip archive) | Download and extract |
|
||||
| Local SKILL.md | Read directly |
|
||||
| Local zip archive | Extract |
|
||||
|
||||
Installation steps:
|
||||
|
||||
1. Locate the `SKILL.md` (may be at the root or in a subdirectory of the archive)
|
||||
2. Read the `name` from the frontmatter
|
||||
3. Copy the **entire skill directory** (including `SKILL.md`, `scripts/`, `assets/`, etc.) to `<workspace>/skills/<name>/`
|
||||
4. If the archive contains an `INSTALL.md` or similar setup script, run it — but the final result must still reside under `<workspace>/skills/<name>/`
|
||||
|
||||
## Creating a Skill from Scratch
|
||||
|
||||
Recommended order:
|
||||
|
||||
1. **Clarify requirements** — ask the user for a few concrete use cases (don't ask too many at once)
|
||||
2. **Plan the structure** — does this skill need scripts? Reference docs? Template assets?
|
||||
3. **Scaffold** — use the init script:
|
||||
|
||||
```bash
|
||||
scripts/init_skill.py <skill-name> --path <workspace>/skills [--resources scripts,references,assets] [--examples]
|
||||
```
|
||||
|
||||
4. **Fill in content** — write SKILL.md, add scripts and resources. Always test scripts after writing them
|
||||
5. **Validate** (optional):
|
||||
|
||||
```bash
|
||||
scripts/quick_validate.py <workspace>/skills/<skill-name>
|
||||
```
|
||||
|
||||
6. **Iterate** — keep improving based on real-world usage feedback
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
- Use only lowercase letters, digits, and hyphens. Normalise user-given names, e.g. `Plan Mode` → `plan-mode`
|
||||
- Maximum 64 characters
|
||||
- Keep it short, start with a verb, make it self-explanatory
|
||||
- Use tool names as prefixes when appropriate, e.g. `gh-address-comments`, `linear-address-issue`
|
||||
- The directory name and the `name` field must match exactly
|
||||
|
||||
## Three-Level Loading
|
||||
|
||||
Skills are not loaded into context all at once — they use a three-level progressive loading mechanism:
|
||||
|
||||
1. **Metadata** (`name` + `description`) — always in context (~100 words). The Agent uses this to decide whether to invoke the skill
|
||||
2. **SKILL.md body** — loaded only when the skill is activated; keep it under 500 lines
|
||||
3. **Resource files** — read on demand by the Agent
|
||||
|
||||
For skills with multiple variants (e.g. multi-cloud deployment), organise like this:
|
||||
|
||||
```
|
||||
cloud-deploy/
|
||||
├── SKILL.md # Main workflow and provider selection logic
|
||||
└── references/
|
||||
├── aws.md
|
||||
├── gcp.md
|
||||
└── azure.md
|
||||
```
|
||||
|
||||
When the user picks AWS, the Agent only reads `aws.md` — no need to load all three providers.
|
||||
|
||||
## Common Design Patterns
|
||||
|
||||
**Step-by-step**: numbered steps with corresponding scripts.
|
||||
|
||||
```markdown
|
||||
1. Analyse form structure (run analyze_form.py)
|
||||
2. Generate field mappings (edit fields.json)
|
||||
3. Auto-fill the form (run fill_form.py)
|
||||
```
|
||||
|
||||
**Branching**: different flows based on user intent.
|
||||
|
||||
```markdown
|
||||
1. Determine operation type:
|
||||
**Creating new content?** → follow the "Create" workflow
|
||||
**Editing existing content?** → follow the "Edit" workflow
|
||||
```
|
||||
|
||||
**Template-based**: when output format has strict requirements, include a template in SKILL.md for the Agent to follow.
|
||||
Reference in New Issue
Block a user