writing-skills

Writing Skills — Intelligent Agent Skill Creation Guide

Skill Overview

Writing Skills is the dispatch hub for creating intelligent agent skills. It provides decision trees, templates, and standards to help developers create, update, or optimize AI intelligent agent skills.

Use Cases

Create New Skills — Choose the appropriate architecture template (Tier 1–3) based on the skill’s complexity, ranging from simple single-file skills to large platform-level skills.

Optimize Existing Skills — Fix issues such as skills being ignored by AI, users being unable to discover them, or descriptions not triggering. Use CSO search optimization and de-contradiction techniques.

Skill Compliance Validation — Check metadata configuration, naming conventions, and directory structure to ensure skills meet writing standards.

Core Functions

Decision Tree Navigation

Use a quick decision tree to determine the correct workflow path: create a new skill and choose a Tier 1–3 architecture; modularize or apply CSO optimization to existing skills; use standard documentation for compliance checks.

Skill Template Library

Provides four skill templates: Technical (how-to guides), Reference (documentation), Disciplined (rules), and Pattern-based (design patterns). Each template includes a standard structure and best practices.

CSO Search Optimization

“SEO for Large Language Models,” guiding how to write skill descriptions and trigger keywords to ensure the skill can be correctly discovered and triggered.

Frequently Asked Questions

How do I choose a skill architecture template?

Select based on complexity:

Simple single-file skills (<200 lines) use Tier 1 architecture.

Multi-concept complex skills (200–1000 lines) use Tier 2 extended architecture.

Large platforms (10+ products) use Tier 3 platform architecture.

Why doesn’t the skill description trigger?

Check whether the description starts with "Use when...", whether it includes specific trigger keywords, and whether the metadata.triggers field contains 3+ keywords. Improve the description writing using the CSO (search optimization) guide.

Where should the SKILL.md file be placed?

A fully uppercase SKILL.md file must be placed under the skill directory. For complex skills, you may place supplementary documents in the references/ directory. The filename must exactly match the skill directory’s name field.