---name: hello-worlddescription: "Use when user asks to create a hello-world project in any language. Supports Python, JavaScript, Go, and Rust. Handles project setup, basic file structure, and a runnable entry point."---# Hello World Skill## Supported Languages| Language | Entry File | Run Command ||----------|-----------|-------------|| Python | main.py | python3 main.py || JavaScript | index.js | node index.js || Go | main.go | go run main.go || Rust | main.rs | cargo run |## Workflow1. Detect language from user request (default: Python if unspecified).2. Create entry file with print/hello-world logic.3. If Go or Rust, also create go.mod / Cargo.toml.4. Print the run command for the user.## Scripts- `scripts/validate_project.py ` — Checks that the generated project has correct structure.
4.3 创建脚本
# scripts/validate_project.py#!/usr/bin/env python3"""Validate that a hello-world project has the expected structure."""import sysfrom pathlib import PathREQUIRED_FILES = { "python": ["main.py"], "javascript": ["index.js"], "go": ["main.go", "go.mod"], "rust": ["main.rs", "Cargo.toml"],}def validate(lang: str, project_dir: str) -> bool: files = REQUIRED_FILES.get(lang) if not files: print(f"Unknown language: {lang}") return False base = Path(project_dir) ok = True for f in files: if not (base / f).exists(): print(f"Missing: {f}") ok = False if ok: print(f"Project structure OK for {lang}") return okif __name__ == "__main__": if len(sys.argv) != 3: print("Usage: validate_project.py ") sys.exit(1) success = validate(sys.argv[1], sys.argv[2]) sys.exit(0 if success else 1)
# ❌ 太模糊description: "A skill for working with documents"# ❌ 缺少触发条件description: "Create and edit DOCX files"# ✅ 完整description: "Comprehensive document creation, editing, and analysis with support fortracked changes, comments, formatting preservation, and text extraction. Use whenCodex needs to work with professional documents (.docx files) for: (1) Creating newdocuments, (2) Modifying or editing content, (3) Working with tracked changes,(4) Adding comments, or any other document tasks"
5.2 Body 编写原则
用祈使句
# ❌ 描述式This skill allows you to rotate PDF pages.# ✅ 指令式Rotate PDF pages using the rotation script.
只写 Codex 不知道的东西
# ❌ 废话连篇（Codex 知道 Python 怎么写）## Python BasicsPython is a programming language created by Guido van Rossum...Use `def` to define functions. Use `for` to iterate...# ✅ 只写领域特定知识## Internal SchemaThe `orders` table has a `status` column with values:`pending`, `shipped`, `delivered`, `returned`.Join with `customers` on `customer_id`.
## API ReferenceFor detailed endpoint documentation, see `references/api_docs.md`.To find a specific endpoint: `grep -n "endpoint_name" references/api_docs.md`
interface: display_name: "My Skill Name" # UI 列表显示名 short_description: "Help with X tasks" # 25-64 字符的简短描述 icon_small: "./assets/small.png" # 小图标（可选） icon_large: "./assets/large.svg" # 大图标（可选） brand_color: "#3B82F6" # UI 强调色（可选） default_prompt: "Use $my-skill to help with ..." # 默认提示（可选）dependencies: tools: - type: "mcp" value: "github" description: "GitHub MCP server" transport: "streamable_http" url: "https://api.githubcopilot.com/mcp/"policy: allow_implicit_invocation: true # false 则只允许 $skill 手动触发
用脚本自动生成
python3 ~/.codex/skills/.system/skill-creator/scripts/generate_openai_yaml.py ~/.codex/skills/my-skill --interface display_name="My Skill" --interface short_description="Help with my skill tasks"
8. 中级技巧：渐进式披露设计
这是写出高效 Skill 的核心设计模式。
模式一：高层指南 + 引用文件
# PDF Processing## Quick startExtract text with pdfplumber:[code example]## Advanced features- **Form filling**: See references/forms.md for complete guide- **API reference**: See references/api_docs.md for all methods- **Examples**: See references/examples.md for common patterns
# DOCX Processing## Creating documentsUse docx-js for new documents. See references/docx-js.md.## Editing documentsFor simple edits, modify the XML directly.**For tracked changes**: See references/redlining.md**For OOXML details**: See references/ooxml.md
关键原则
引用文件从 SKILL.md 出发只跳一层，不要深层嵌套
超过 100 行的引用文件，顶部加目录（Table of Contents）
SKILL.md 不超过 500 行，超过就拆
9. 中级技巧：自由度控制
根据任务的脆弱性和可变性，匹配不同的自由度：
高自由度（文本指令）
适用场景： 多种方法都可行，决策依赖上下文，启发式引导即可。
## Code Review GuidelinesFocus on security, performance, and maintainability.Use your judgment for severity levels.Suggest improvements when patterns are suboptimal.
中自由度（伪代码/带参数脚本）
适用场景： 有推荐模式，允许一定变体，配置影响行为。
## Data Pipeline1. Read source data with `scripts/ingest.py --source --format `2. Validate schema against `references/schema.md`3. Transform using the patterns in `references/transform_guide.md`4. Load to target with `scripts/load.py --target
--mode `
低自由度（特定脚本，少量参数）
适用场景： 操作脆弱易错，一致性关键，必须按特定顺序执行。
## PDF Rotation (MUST follow this exact sequence)1. Run: `python3 scripts/rotate_pdf.py
类比： 窄桥+悬崖需要明确护栏（低自由度），开阔草地可以自由探索（高自由度）。
10. 进阶：Forward-Testing
Forward-testing 是验证 Skill 是否真正有效的关键手段。
什么是 Forward-Testing
让子代&理（subagent）假装是普通用户，用你的 Skill 完成真实任务，从而测试：
Skill 能否被正确触发
指令是否足够清晰
输出是否符合预期
怎么做
正确方式：
Use $skill-name at /path/to/skill-name to solve problem y
错误方式：
Review the skill at /path/to/skill-name; pretend a user asks you to...
---name: chart-generatordescription: "Generate publication-quality charts. Use when user asks to create any data visualization, chart, or graph from data."---# Chart Generator## Workflow1. Determine chart type from user request (bar, line, scatter, heatmap, etc.)2. Generate chart with matplotlib/plotly using `scripts/generate_chart.py`3. Render to PNG and visually verify4. If verification fails, fix and re-render5. Deliver final PNG## Quality Checks (Mandatory)After EVERY chart generation:- Verify no overlapping labels- Confirm axis labels are readable at target size- Check color contrast meets WCAG AA- Ensure title and legend are visible## Scripts- `scripts/generate_chart.py --type --data --output `- `scripts/verify_chart.py ` — Automated quality check
模式二：环境感知 Skill
---name: deploy-helperdescription: "Deploy applications to cloud providers. Use when user asks to deploy, ship, or release an application. Supports AWS, GCP, Azure."---# Deploy Helper## Pre-flight ChecksBefore any deployment:1. Verify target environment credentials exist2. Check that build artifacts are up to date3. Confirm deployment target matches user's intent (staging vs production)## Provider Selection| Provider | Config File | Credentials ||----------|------------|-------------|| AWS | aws-config.yaml | AWS_PROFILE env || GCP | gcp-config.yaml | GOOGLE_APPLICATION_CREDENTIALS || Azure | azure-config.yaml | AZURE credentials |Load provider-specific details from `references/.md`.## Safety Rules- NEVER deploy to production without explicit user confirmation- ALWAYS preview changes before executing- If deployment fails, rollback and explain what went wrong
模式三：带上下文积累的长流程
---name: code-migrationdescription: "Migrate codebases between frameworks or languages. Use when user asks to migrate, convert, or transform an existing codebase."---# Code Migration Skill## Phase 1: AnalysisScan the source codebase and produce `migration-report.md`:- File count and structure- Dependencies inventory- Complexity estimate## Phase 2: PlanningBased on the report, create a migration plan in `migration-plan.md`:- Ordered list of files to convert- Dependency graph- Risk assessment per file## Phase 3: ExecutionConvert files following the plan. After each batch:- Run available tests- Update migration-plan.md with progress- If error rate > 10%, pause and reassess## Phase 4: Verification- Run full test suite- Compare coverage metrics before/after- Generate final migration summary
---name: notion-knowledge-capturedescription: "Capture conversations and decisions into structured Notion pages. Use when turning chats/notes into wiki entries, how-tos, decisions, or FAQs with proper linking."---# Notion Knowledge Capture## When to CaptureCapture knowledge when the conversation contains:- A decision that should be持久化- A how-to that will be repeated- An FAQ that multiple people ask- A meeting outcome that affects others## Workflow1. Identify the type of knowledge (decision / how-to / FAQ / meeting-notes)2. Load the appropriate template from `assets/templates/`3. Fill in the template with conversation content4. Determine where it belongs in the Notion hierarchy (see `references/linking_rules.md`)5. Create the page via Notion MCP## Quality Standards- Title must be specific and searchable (not "Meeting Notes" but "Q3 Planning: API Rate Limiting Decision")- Every entry must have: author, date, status, related pages- Decisions must include: context, options considered, rationale, follow-ups
