Create or update skills. Use when designing, structuring, or packaging skills with scripts, references, and assets. COW simplified version - skills are used locally in workspace.
npxskills add zhayujie/chatgpt-on-wechat--skill skill-creatorLoading…
This skill provides guidance for creating effective skills using the existing tool system.
Skills are modular, self-contained packages that extend the agent's capabilities by providing specialized knowledge, workflows, and tools. They transform a general-purpose agent into a specialized agent equipped with procedural knowledge.
Concise is Key: Only add context the agent doesn't already have. Challenge each piece of information: "Does this justify its token cost?" Prefer concise examples over verbose explanations.
Every skill consists of a required SKILL.md file and optional bundled resources:
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter metadata (required)
│ │ ├── name: (required)
│ │ └── description: (required)
│ └── Markdown instructions (required)
└── Bundled Resources (optional)
├── scripts/ - Executable code (Python/Bash/etc.)
├── references/ - Documentation intended to be loaded into context as needed
└── assets/ - Files used in output (templates, icons, fonts, etc.)
Frontmatter (YAML) - Required fields:
weather-api, pdf-editor)"PDF document processing with rotation, merging, splitting, and text extraction. Use when user needs to: (1) Rotate PDF pages, (2) Merge multiple PDFs, (3) Split PDF files, (4) Extract text from PDFs."Body (Markdown) - Loaded after skill triggers:
scripts/ - When to include:
references/ - When to include:
assets/ - When to include:
Important: Most skills don't need all three. Choose based on actual needs.
Do NOT create auxiliary documentation files:
Critical Rule: Only create files that the agent will actually execute (scripts) or that are too large for SKILL.md (references). Documentation, examples, and guides ALL belong in SKILL.md.
Install target directory: <workspace>/skills/<name>/ (the <workspace> is from the "工作空间" section).
| Source | Action |
|---|---|
| URL (single file) | Fetch content via curl or web_fetch |
| URL (zip/archive) | Download and extract to a temp directory |
| Local file (SKILL.md) | Read directly |
| Local archive (zip) | Extract to a temp directory |
name from YAML frontmatterreferences/, scripts/, assets/, etc.) into <workspace>/skills/<name>/<workspace>/skills/<name>/plan-mode).gh-address-comments, linear-address-issue).Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
For example, when building an image-editor skill, relevant questions include:
To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
Conclude this step when there is a clear sense of the functionality the skill should support.
To turn concrete examples into an effective skill, analyze each example by:
Planning Checklist:
Example: When building a pdf-editor skill to handle queries like "Help me rotate this PDF," the analysis shows:
scripts/rotate_pdf.py script would be helpful to store in the skillreferences/api-docs.md - put API info in SKILL.md insteadExample: When designing a frontend-webapp-builder skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
assets/hello-world/ template containing the boilerplate HTML/React project files would be helpful to store in the skillreferences/usage-examples.md - put examples in SKILL.md insteadExample: When building a big-query skill to handle queries like "How many users have logged in today?" the analysis shows:
references/schema.md file documenting the table schemas would be helpful to store in the skill (ONLY because schemas are very large)references/query-examples.md - put examples in SKILL.md insteadTo establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets. Default to putting everything in SKILL.md unless there's a compelling reason to separate it.
At this point, it is time to actually create the skill.
Skip this step only if the skill being developed already exists, and iteration is needed. In this case, continue to the next step.
When creating a new skill from scratch, always run the init_skill.py script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.
Usage:
scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]
Examples:
scripts/init_skill.py my-skill --path <workspace>/skills
scripts/init_skill.py my-skill --path <workspace>/skills --resources scripts,references
scripts/init_skill.py my-skill --path <workspace>/skills --resources scripts --examples
Where <workspace> is your workspace directory shown in the "工作空间" section of the system prompt.
The script:
--resources--examples is setAfter initialization, customize the SKILL.md and add resources as needed. If you used --examples, replace or delete placeholder files.
Important: Always create skills in workspace skills directory (<workspace>/skills), NOT in project directory. Check the "工作空间" section for the actual workspace path.
When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of the agent to use. Include information that would be beneficial and non-obvious to the agent. Consider what procedural knowledge, domain-specific details, or reusable assets would help another agent instance execute these tasks more effectively.
Workflow patterns — For complex tasks, break operations into sequential steps or conditional branches:
# Sequential: list numbered steps with scripts
1. Analyze the form (run analyze_form.py)
2. Create field mapping (edit fields.json)
3. Fill the form (run fill_form.py)
# Conditional: guide through decision points
1. Determine the modification type:
**Creating new content?** → Follow "Creation workflow"
**Editing existing content?** → Follow "Editing workflow"
Output patterns — When consistent output format matters, provide a template or input/output examples in SKILL.md so the agent can follow the desired style.
To begin implementation, start with the reusable resources identified above: scripts/, references/, and assets/ files. Note that this step may require user input. For example, when implementing a brand-guidelines skill, the user may need to provide brand assets or templates to store in assets/, or documentation to store in references/.
Available Base Tools:
The agent has access to these core tools that you can leverage in your skill:
Minimize Dependencies:
Important Guidelines:
Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.
If you used --examples, delete any placeholder files that are not needed for the skill. Only create resource directories that are actually required.
Writing Guidelines: Always use imperative/infinitive form.
Write the YAML frontmatter with name, description, and optional metadata:
name: The skill namedescription: This is the primary triggering mechanism for your skill, and helps the agent understand when to use the skill.
docx skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when the agent needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"metadata: (Optional) Specify requirements and configuration
requires.bins: Required binaries (e.g., ["curl", "jq"])requires.env: Required environment variables — all must be set (e.g., ["MYAPI_KEY"])requires.anyEnv: Alternative environment variables — at least one must be set (e.g., ["OPENAI_API_KEY", "LINKAI_API_KEY"])requires.anyBins: Alternative binaries — at least one must be presentalways: Set to true to always load regardless of requirementsemoji: Skill icon (optional)category — it defaults to skill and is managed by the systemAPI Key Requirements:
If your skill needs a single API key, declare it in requires.env:
---
name: my-search
description: Search using MyAPI
metadata:
requires:
bins: ["curl"]
env: ["MYAPI_KEY"]
---
If your skill supports multiple API key providers (e.g., OpenAI or LinkAI), use requires.anyEnv:
---
name: my-vision
description: Analyze images using Vision API
metadata:
requires:
bins: ["curl"]
anyEnv: ["OPENAI_API_KEY", "LINKAI_API_KEY"]
---
Auto-enable rule: Skills are automatically enabled when required environment variables are set, and automatically disabled when missing. No manual configuration needed.
Write instructions for using the skill and its bundled resources.
If your skill requires an API key, include setup instructions in the body:
## Setup
This skill requires an API key from [Service Name].
1. Visit https://service.com to get an API key
2. Configure it using: `env_config(action="set", key="SERVICE_API_KEY", value="your-key")`
3. Or manually add to `~/cow/.env`: `SERVICE_API_KEY=your-key`
4. Restart the agent for changes to take effect
## Usage
...
The bash script should check for the key and provide helpful error messages:
#!/usr/bin/env bash
if [ -z "${SERVICE_API_KEY:-}" ]; then
echo "Error: SERVICE_API_KEY not set"
echo "Please configure your API key first (see SKILL.md)"
exit 1
fi
curl -H "Authorization: Bearer $SERVICE_API_KEY" ...
Script Path Convention:
When writing SKILL.md instructions, remember that:
<available_skills> with a <base_dir> path<base_dir>/scripts/script_name.shExample instruction in SKILL.md:
## Usage
Scripts are in this skill's base directory (shown in skill listing).
bash "<base_dir>/scripts/my_script.sh" <args>
Validate skill format:
scripts/quick_validate.py <path/to/skill-folder>
Example:
scripts/quick_validate.py <workspace>/skills/weather-api
Validation checks:
Note: Validation is optional in COW. Mainly useful for troubleshooting format issues.
Improve based on real usage:
Skills use three-level loading:
Best practices:
references/ filesPattern: For skills with multiple variants/frameworks:
Example:
cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
├── aws.md
├── gcp.md
└── azure.md
When user chooses AWS, agent only reads aws.md.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).