Skill: haseo-ai/oc-skill-creator (version 1.0.0)

--- name: skill-creator description: > Create, edit, improve, tidy, review, audit, or restructure OpenClaw AgentSkills and SKILL.md files. Optimized for OpenClaw's architecture: sub-agents, context fork, skill auto-loading, and references/. Covers the full lifecycle: analyze existing work → extract patterns → design skill → write SKILL.md → test → iterate. Keywords: skill, create skill, skill creator, SKILL.md, 스킬, 스킬 만들기, 스킬 생성, 스킬 개선, 스킬 수정, 스킬 검토, 스킬 작성, スキル, スキル作成, スキル生成, スキル作成, 技能创建, 创建技能, 生成技能, 改进技能. --- # OpenClaw Skill Creator Create, improve, and maintain OpenClaw AgentSkills. This guide covers the full lifecycle from pattern extraction through testing. ## Why This Skill Exists OpenClaw skills are not just simple prompt files. Skills designed for OpenClaw's architecture — 3-layer loading (description → body → references), sub-agent context injection, Phase 0 analysis — significantly improve agent quality. This skill systematizes those design principles and provides validated examples across 5 types (pipeline, single-task, tool integration, code generation, document conversion). ### Language Policy - **SKILL.md body**: Always write in **English** — this ensures the skill works across all language environments - **references/**: English by default. Localized copies may be provided as `filename.ko.md`, `filename.ja.md`, `filename.zh.md` - **description Keywords**: Include keywords in all target languages (English, Korean, Japanese, Chinese) - **Generated skills**: Follow the same policy — English body, multilingual keywords ## Key Strengths 1. **OpenClaw-native patterns** — Optimized for OpenClaw architecture: sub-agent context fork, references/ lazy loading, Phase 0 structural analysis 2. **5 validated types** — examples/ includes actual generated skills and case analyses for each type 3. **Style Guide-centric** — Skills that specify "what to preserve" and "what to compress" determine agent quality 4. **skill-audit integration** — Validate generated skills with skill-audit to get 0-100 scores and improvement recommendations 5. **Bundled skill porting** — Checklist for porting existing Codex-based bundled skills to OpenClaw patterns ## OpenClaw Skill Anatomy ``` skill-name/ ├── SKILL.md # Required. Frontmatter + instructions. ├── references/ # Optional. Loaded on demand by the agent. │ ├── output-format.md # Output specifications │ └── subagent-prompt-templates.md # Sub-agent prompt templates ├── scripts/ # Optional. Executable code (Python/Bash/etc.) │ ├── extract_epub.py │ └── extract_pdf.py ├── assets/ # Optional. Files used in output, not loaded into context. │ └── template.html └── examples/ # Optional. Example files for reference. ``` **DO NOT create:** README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, LICENSE, or similar auxiliary documentation. ## Frontmatter (Required) ```yaml --- name: skill-name description: > What this skill does and when it should trigger. Include keywords in multiple languages. Keywords: keyword1, keyword2, 키워드1, 키워드2. --- ``` - **`name`**: lowercase, hyphens only. Under 64 chars. Prefer short, verb-led names. - **`description`**: This is the **primary triggering mechanism**. OpenClaw reads this to decide when to load the skill. Include: - What the skill does - When to use it (triggers, contexts) - Keywords in all relevant languages (localized + English) - Do NOT put "when to use" info in the body — it's only loaded AFTER triggering. ## Loading Architecture OpenClaw loads skills in three layers: 1. **Metadata** (name + description) — Always in context. ~100 words per skill. 2. **SKILL.md body** — Loaded when the skill triggers. Keep under 500 lines. 3. **references/** — Loaded on demand when the agent decides it's needed. **Implication:** Every word in `description` is always costing tokens. Be concise. Every word in SKILL.md costs tokens when the skill triggers. Keep it lean. --- ## Skill Creation: 5-Step Process ### Step 1: Analyze "Well-Done" Results Before writing anything, analyze examples of **the agent performing the task well without a skill**. Ask: - What structure did the output have? - What did the agent **preserve** (examples, metaphors, quotes, data)? - What did the agent **compress** (repetition, verbose explanations)? - What **judgments** did the agent make (grouping, prioritization, restructuring)? - Why did it make those judgments? > **This analysis becomes the Style Guide.** This is the most important step. > A skill that only specifies format but not style produces dry, mediocre results. ### Step 2: Analyze "Failed" Results (if available) If sub-agents or previous skill versions produced bad results, identify exactly what went wrong: | Symptom | Likely Cause | |---------|-------------| | Output is dry/bland | Missing style guide — no "what to preserve" rules | | Flow is disconnected | Chunks processed independently — missing Phase 0 context injection | | Lots of duplication | Missing merge/restructure instructions | | Inconsistent style | No style rules in sub-agent prompts | | Sub-agent ignores instructions | Sub-agent prompt lacks context from Phase 0 | > **Every failure maps to a specific instruction to add to the skill.** ### Step 3: Write Style Guide First Write the Style Guide **before** the workflow. The workflow is "what order" — the Style Guide is "how to judge." ```markdown ## Style Guide ### Essence - What is the core of this task? (e.g., "Summarization is restructuring, not compression.") - What perspective should the agent take? ### Preservation Criteria (NEVER discard) - Specific examples with "why" ### Compression Criteria (what to reduce) - Specific examples with "why" ### Style Rules - Tone, sentence length, formatting conventions - Rules specific to this context ``` ### Step 4: Structure the Workflow Build the workflow around the Style Guide: ```markdown ## Workflow ### Phase 0: [Analysis Step] (★ Most Important) What to analyze before starting, and where that information gets used. ### Phase 1~N: [Execution Steps] Each step's specific instructions. ### Phase N+1: [Validation Step] How to verify the output meets quality standards. ``` **Key principles:** - **Phase 0 first** — analyze the full input before dividing into chunks or delegating - **Context injection for sub-agents** — sub-agents have NO context from the main session. Phase 0 results must be explicitly injected into sub-agent prompts. - **Validation step** — check output length, structure, and quality ### Step 5: Split into References (if needed) If SKILL.md approaches 500 lines, split: | Content type | Where to put it | |-------------|----------------| | Output structure/specifications | `references/output-format.md` | | Sub-agent prompt templates | `references/subagent-prompt-templates.md` | | Domain knowledge (APIs, schemas) | `references/domain.md` | | Examples | `references/examples.md` | Always link references from SKILL.md with a description of **when to read them**. --- ## Sub-Agent Design Patterns Sub-agents are the #1 source of skill quality degradation. The root cause is always the same: **the sub-agent lacks context that the main agent has.** ### Pattern A: Context Injection Always include in sub-agent prompts: 1. **Full context** — "This chunk is part of [overall structure]. It covers [topic]." 2. **Specific preservation list** — "In this chunk, preserve: [metaphor, quote, example]" 3. **Judgment criteria** — 3-4 lines from Style Guide 4. **Output format** — How to format the result ### Pattern B: Template with Fill-in-the-Blanks Don't copy templates verbatim. Use `[ ]` placeholders filled from Phase 0: ```markdown Sub-agent prompt template (fill `[ ]` from Phase 0 results): ## Context [Overall structure from Phase 0] [This chunk's position in the whole] ## Preserve (this chunk only) [Specific items from Phase 0] ## Instructions [Depth/format/style rules] --- [Chunk text] --- ``` **If Phase 0 didn't produce `[ ]` values, the template can't be filled. The sub-agent becomes a context-free "text compressor." This is why Phase 0 is mandatory.** ### Pattern C: Sequential Pipeline When multiple depth levels exist (e.g., 1x and 5x), use sequential dependency: ``` depth=1x: Analyze → Chunk → Summarize → Merge → summary.md depth=5x: Analyze → Chunk → Summarize → Merge → summary.md → Use summary.md as skeleton → Expand → summary_5x.md ``` **Why sequential?** The simpler output provides structure for the complex one. Starting with the complex version means each chunk is independently summarized, losing overall flow. ### Pattern D: Merge ≠ Concatenate When merging multiple chunk results: 1. Never just concatenate 2. Restructure according to Phase 0's topic flow 3. Remove duplicates (keep the most detailed version) 4. Derive overall takeaways (not just chunk summaries) --- ## Skill File Organization Rules ### Keep SKILL.md Lean - **Under 500 lines** — split into references/ if longer - **Only in SKILL.md**: Workflow phases, Style Guide summary, parameter tables, reference links - **In references/**: Detailed specs, prompt templates, domain knowledge, examples ### Reference File Best Practices - **One level deep** — all reference files link directly from SKILL.md, not from other references - **Table of contents** — for reference files over 100 lines - **Never duplicate** — information lives in either SKILL.md OR a reference file, never both ### Workspace Skills vs Bundled Skills | | Workspace (`~/.openclaw/workspace/skills/`) | Bundled (`/app/skills/`) | |---|---|---| | Persistence | Survives container restarts | Reset on container restart | | Scope | User-specific, project-specific | Shared, system-wide | | When to use | Custom workflows, domain knowledge | Universal tools (weather, discord, etc.) | | Source of truth | **This directory** for new custom skills | Reference only, don't modify | **Always create custom skills in workspace. Never modify bundled skills.** --- ## Skill Improvement & Auditing ### Audit Checklist For any skill, check: **Triggering** - [ ] `description` clearly explains when to trigger? - [ ] Keywords in relevant languages? - [ ] No "when to use" sections in body (should be in description)? **Style Guide** - [ ] "What to preserve" with specific examples? - [ ] "What to compress" with specific examples? - [ ] Style rules explicit? **Workflow** - [ ] Phase 0 (analysis) comes first? - [ ] Sub-agent context injection specified? - [ ] Validation/quality check step exists? **Sub-agent Integration** - [ ] Prompt templates have `[ ]` placeholders filled from Phase 0? - [ ] Clear warning about what happens without context injection? **File Organization** - [ ] SKILL.md under 500 lines? - [ ] Long content split to references/? - [ ] Each reference file describes when to read it? ### Common Anti-Patterns | Anti-Pattern | Problem | Fix | |-------------|---------|-----| | Format-only, no style | Dry, mediocre output | Add Style Guide | | Sub-agent without context | Disconnected chunks | Add Phase 0 + context injection | | Simple concatenation | Duplication, no flow | Add restructure instructions | | Arbitrary chunk boundaries | Content cut mid-section | "Cut only at section/chapter boundaries" | | Parallel depth generation | Inconsistent structures | Sequential pipeline (simple → complex) | | Template used verbatim | Context-free instructions | Fill `[ ]` from Phase 0 results | | "When to use" in body | Never read (body loads after trigger) | Move to description | --- ## References - `references/openclaw-vs-codex.md` — Differences from the bundled Codex skill-creator and porting checklist - `examples/summarize.md` — Validation example: summarize skill (sub-agent pipeline type) - `examples/changelog.md` — Validation example: changelog skill (doc conversion type) - `examples/scaffold.md` — Validation example: scaffold skill (code generation type) - `examples/screenshot-capture.md` — Validation example: screenshot-capture skill (tool integration type) - `examples/unit-converter.md` — Validation example: unit-converter skill (single-task type) - `examples/skill-audit.md` — Validation example: skill-audit (meta validation tool)

path: references/openclaw-vs-codex.md
content: # OpenClaw vs Codex Skill Creator

> Documents the differences between the bundled Codex skill-creator (`/app/skills/skill-creator/`) and the new OpenClaw-native skill-creator. Use this reference when creating new OpenClaw skills or porting existing Codex skills.

## Architecture Differences

| | Codex (CLI Coding Agent) | OpenClaw (Multi-Agent) |
|---|---|---|
| Execution | Single CLI session | Main + sub-agents (spawn/fork) |
| Context | All context exists within the session | Sub-agents start with **empty** context |
| Skill loading | description → body → scripts (sequential) | description(always) → body(on trigger) → references(on demand) |
| Skill storage | Single location | workspace(persists across restarts) vs bundled(resets on update) |
| Prompt injection | Unnecessary (single context) | **Required** (explicit injection into sub-agents) |
| Packaging | `package_skill.py` creates `.skill` file | No packaging — folder structure is recognized directly |

## 5 Key Differences

### 1. Sub-Agent Context Injection

**Codex**: All work happens in one session, so context sharing is natural.

**OpenClaw**: When you spawn a sub-agent, its context is **empty**. The main agent must explicitly inject information gathered during Phase 0 into the sub-agent's prompt.

Codex skills have no concept of this. In OpenClaw, it's the most important pattern.

```
Codex:   "Summarize this text" → OK (context already present)
OpenClaw: "Summarize this text" → FAIL (sub-agent has no context)

OpenClaw correct approach:
"This text is sections 1–5 of the 'OOO User Manual'.
The full document has 27 sections in 5 parts. This chunk covers 'New Design Methodology'.
Preserve the following: [analogies], [quotes], [case studies]..."
```

### 2. Style Guide First

**Codex**: "Concise is key" — focus on saving context window. Assumes the agent is already smart enough.

**OpenClaw**: Without a style guide, sub-agents become "text compressors." **Judgment criteria** are mandatory.

Codex skills focus on format (structure, length), but OpenClaw skills must also include judgment criteria (what to preserve, which tone, which perspective).

### 3. Phase 0 (Analysis Stage) Required

**Codex**: The agent naturally analyzes while working.

**OpenClaw**: A pipeline where the main agent analyzes in Phase 0, then injects results into sub-agent prompts, is required.

Without Phase 0:
- Each chunk is processed independently (overall flow is lost)
- Duplicate content appears across chunks
- Author's voice (analogies, quotes) gets dropped

### 4. Sequential Pipeline

**Codex**: Multiple outputs can be generated in parallel; the agent naturally merges them.

**OpenClaw**: Complex outputs should be expanded sequentially from simple to complex.

Example: summary depth 1x + 5x
- Codex: can generate in parallel (agent merges)
- OpenClaw: 1x → 5x sequential (1x structure serves as the skeleton for 5x)

### 5. No Packaging Needed

**Codex**: `package_skill.py` creates a `.skill` file (essentially a zip) for distribution.

**OpenClaw**: Recognizes folder structure directly. Only `SKILL.md` is needed for a skill to work.

No packaging scripts, validation scripts, or init scripts required.

## Porting Checklist: Codex Skill → OpenClaw Skill

When porting a Codex skill to OpenClaw:

- [ ] **Check if sub-agents are needed** — If the skill does chunking or parallel processing, verify Phase 0 + context injection patterns exist
- [ ] **Style Guide present?** — If not, add one. Format specs alone aren't enough for sub-agents to produce quality output
- [ ] **Add Phase 0** — Is there an analysis stage before work begins?
- [ ] **Prompt templates with `[ ]` placeholders** — Verify placeholders are filled with Phase 0 results
- [ ] **Merge instructions** — Explicitly prevent simple concatenation of multi-chunk outputs
- [ ] **Remove `package_skill.py` references** — Not needed in OpenClaw
- [ ] **Remove `init_skill.py` references** — Not needed in OpenClaw
- [ ] **Trigger keywords in description** — Include both English and localized keywords
- [ ] **Move "When to use" from body to description** — OpenClaw loads body only after trigger

## Patterns to Keep from Codex

The following are good patterns that work in both environments:

1. **Progressive Disclosure** — Keep SKILL.md under 500 lines; move details to references/
2. **"Concise is key" principle** — Don't re-explain what the agent already knows
3. **Degrees of Freedom** — Adjust specificity based on task fragility (high/medium/low)
4. **Single-level reference depth** — Don't reference another references/ from within references/
5. **Improve after use** — Use the skill, observe failures, fix, repeat


path: references/openclaw-vs-codex.ja.md
content: # OpenClaw vs Codex Skill Creator

> バンドルされたCodexスキルクリエイター（`/app/skills/skill-creator/`）と、新しいOpenClawネイティブスキルクリエイターの違いを文書化します。新しいOpenClawスキルの作成や、既存のCodexスキルの移植時にこのリファレンスを使用してください。

## アーキテクチャの違い

| | Codex (CLI コーディングエージェント) | OpenClaw (マルチエージェント) |
|---|---|---|
| 実行 | 単一CLIセッション | メイン + sub-agent (spawn/fork) |
| コンテキスト | すべてのコンテキストがセッション内に存在 | sub-agentは**空の**コンテキストで開始 |
| スキル読み込み | description → body → scripts (順次) | description(常時) → body(トリガー時) → references(オンデマンド) |
| スキル保存先 | 単一の場所 | workspace(再起動間で維持) vs bundled(アップデート時に初期化) |
| プロンプト注入 | 不要 (単一コンテキスト) | **必須** (sub-agentへの明示的注入) |
| パッケージング | `package_skill.py`が`.skill`ファイルを作成 | パッケージング不要 — フォルダ構造を直接認識 |

## 5つの主要な違い

### 1. Sub-Agent コンテキスト注入

**Codex**: すべての作業が1つのセッションで行われるため、コンテキスト共有が自然です。

**OpenClaw**: sub-agentをspawnすると、コンテキストが**空**になります。メインエージェントがPhase 0で収集した情報をsub-agentのプロンプトに明示的に注入する必要があります。

Codexスキルにはこの概念がありません。OpenClawでは最も重要なパターンです。

```
Codex:   "このテキストを要約して" → OK (コンテキストが既に存在)
OpenClaw: "このテキストを要約して" → FAIL (sub-agentにコンテキストがない)

OpenClawの正しいアプローチ:
"このテキストは「OOOユーザーマニュアル」のセクション1〜5です。
ドキュメント全体は5パート27セクションです。このチャンクは「新しい設計手法」を扱っています。
以下を保持してください：[比喩]、[引用]、[ケーススタディ]..."
```

### 2. Style Guide 優先

**Codex**: "簡潔さが鍵" — コンテキストウィンドウの節約に集中します。エージェントが既に十分に賢いと仮定します。

**OpenClaw**: Style Guideがないと、sub-agentは「テキスト圧縮機」になります。**判断基準**が必須です。

Codexスキルは形式（構造、長さ）に集中しますが、OpenClawスキルは判断基準（何を保持するか、どのトーンで、どの視点で）も含める必要があります。

### 3. Phase 0 (分析段階) が必須

**Codex**: エージェントが作業しながら自然に分析します。

**OpenClaw**: メインエージェントがPhase 0で分析し、結果をsub-agentプロンプトに注入するパイプラインが必要です。

Phase 0がないと：
- 各チャンクが独立して処理されます（全体の流れが失われます）
- チャンク間で重複コンテンツが現れます
- 著者の声（比喩、引用）が欠落します

### 4. 順次パイプライン

**Codex**: 複数の出力を並列で生成でき、エージェントが自然にマージします。

**OpenClaw**: 複雑な出力は、単純から複雑へ順次拡張する必要があります。

例：要約の深さ 1x + 5x
- Codex: 並列生成可能（エージェントがマージ）
- OpenClaw: 1x → 5x 順次（1xの構造が5xの骨組みとして機能）

### 5. パッケージング不要

**Codex**: `package_skill.py`が配布用の`.skill`ファイル（実質的にzip）を作成します。

**OpenClaw**: フォルダ構造を直接認識します。スキルが機能するために`SKILL.md`だけで十分です。

パッケージングスクリプト、検証スクリプト、initスクリプトは不要です。

## 移植チェックリスト：Codexスキル → OpenClawスキル

CodexスキルをOpenClawに移植する際：

- [ ] **sub-agentが必要か確認** — スキルがチャンキングや並列処理を行う場合、Phase 0 + コンテキスト注入パターンが存在するか確認
- [ ] **Style Guideはあるか？** — なければ追加してください。形式仕様だけではsub-agentが高品質な出力を生成できません
- [ ] **Phase 0を追加** — 作業開始前に分析段階があるか？
- [ ] **`[ ]`プレースホルダー付きプロンプトテンプレート** — プレースホルダーがPhase 0の結果で埋められているか確認
- [ ] **マージ指示** — マルチチャンク出力の単純な連結を明示的に防止
- [ ] **`package_skill.py`参照の削除** — OpenClawでは不要
- [ ] **`init_skill.py`参照の削除** — OpenClawでは不要
- [ ] **descriptionにトリガーキーワード** — 英語とローカライズされたキーワードの両方を含める
- [ ] **「使用タイミング」をbodyからdescriptionへ移動** — OpenClawはトリガー後にのみbodyを読み込みます

## Codexから維持すべきパターン

以下は両環境でうまく機能する良いパターンです：

1. **Progressive Disclosure** — SKILL.mdを500行以下に維持し、詳細はreferences/に移動
2. **"簡潔さが鍵"原則** — エージェントが既に知っていることを再説明しない
3. **自由度の調整** — タスクの脆弱性（高/中/低）に応じて具体性を調整
4. **単一レベル参照深度** — references/内から他のreferences/を参照しない
5. **使用後の改善** — スキルを使用し、失敗を観察し、修正し、繰り返す


path: references/openclaw-vs-codex.ko.md
content: # OpenClaw vs Codex 스킬 크리에이터

> 번들 포함된 Codex 스킬 크리에이터(`/app/skills/skill-creator/`)와 새로운 OpenClaw 네이티브 스킬 크리에이터의 차이점을 문서화합니다. 새로운 OpenClaw 스킬을 생성하거나 기존 Codex 스킬을 포팅할 때 이 참고 자료를 사용하세요.

## 아키텍처 차이

| | Codex (CLI 코딩 에이전트) | OpenClaw (멀티 에이전트) |
|---|---|---|
| 실행 | 단일 CLI 세션 | 메인 + sub-agent (spawn/fork) |
| 컨텍스트 | 모든 컨텍스트가 세션 내에 존재 | sub-agent는 **빈** 컨텍스트로 시작 |
| 스킬 로딩 | description → body → scripts (순차적) | description(항상) → body(트리거 시) → references(요청 시) |
| 스킬 저장소 | 단일 위치 | workspace(재시작 간 유지) vs bundled(업데이트 시 초기화) |
| 프롬프트 주입 | 불필요 (단일 컨텍스트) | **필수** (sub-agent에 명시적 주입) |
| 패키징 | `package_skill.py`이 `.skill` 파일 생성 | 패키징 불필요 — 폴더 구조를 직접 인식 |

## 5가지 핵심 차이

### 1. Sub-Agent 컨텍스트 주입

**Codex**: 모든 작업이 하나의 세션에서 이루어지므로 컨텍스트 공유가 자연스럽습니다.

**OpenClaw**: sub-agent를 spawn하면 컨텍스트가 **비어 있습니다**. 메인 에이전트가 Phase 0에서 수집한 정보를 sub-agent 프롬프트에 명시적으로 주입해야 합니다.

Codex 스킬에는 이 개념이 없습니다. OpenClaw에서는 가장 중요한 패턴입니다.

```
Codex:   "이 텍스트를 요약해줘" → OK (컨텍스트가 이미 존재)
OpenClaw: "이 텍스트를 요약해줘" → FAIL (sub-agent에 컨텍스트가 없음)

OpenClaw 올바른 접근:
"이 텍스트는 'OOO 사용자 매뉴얼'의 섹션 1~5입니다.
전체 문서는 5개 파트에 27개 섹션이 있습니다. 이 청크는 '새로운 설계 방법론'을 다룹니다.
다음을 보존하세요: [비유], [인용구], [사례 연구]..."
```

### 2. Style Guide 우선

**Codex**: "간결함이 핵심" — 컨텍스트 윈도우 절약에 집중합니다. 에이전트가 이미 충분히 똑똑하다고 가정합니다.

**OpenClaw**: Style Guide가 없으면 sub-agent는 "텍스트 압축기"가 됩니다. **판단 기준**이 필수입니다.

Codex 스킬은 형식(구조, 길이)에 집중하지만, OpenClaw 스킬은 판단 기준(무엇을 보존할지, 어떤 어조로, 어떤 관점에서)도 포함해야 합니다.

### 3. Phase 0 (분석 단계) 필수

**Codex**: 에이전트가 작업하면서 자연스럽게 분석합니다.

**OpenClaw**: 메인 에이전트가 Phase 0에서 분석한 뒤, 결과를 sub-agent 프롬프트에 주입하는 파이프라인이 필요합니다.

Phase 0이 없으면:
- 각 청크가 독립적으로 처리됩니다 (전체 흐름이 상실됨)
- 청크 간 중복 콘텐츠가 나타납니다
- 저자의 목소리(비유, 인용구)가 누락됩니다

### 4. 순차적 파이프라인

**Codex**: 여러 출력을 병렬로 생성할 수 있으며, 에이전트가 자연스럽게 병합합니다.

**OpenClaw**: 복잡한 출력은 단순에서 복잡으로 순차적으로 확장해야 합니다.

예: 요약 깊이 1x + 5x
- Codex: 병렬 생성 가능 (에이전트가 병합)
- OpenClaw: 1x → 5x 순차적 (1x 구조가 5x의 뼈대 역할)

### 5. 패키징 불필요

**Codex**: `package_skill.py`이 배포용 `.skill` 파일(사실상 zip)을 생성합니다.

**OpenClaw**: 폴더 구조를 직접 인식합니다. 스킬이 작동하는 데 `SKILL.md`만 있으면 됩니다.

패키징 스크립트, 검증 스크립트, init 스크립트가 필요하지 않습니다.

## 포팅 체크리스트: Codex 스킬 → OpenClaw 스킬

Codex 스킬을 OpenClaw로 포팅할 때:

- [ ] **sub-agent 필요 여부 확인** — 스킬이 청킹이나 병렬 처리를 수행하는 경우, Phase 0 + 컨텍스트 주입 패턴이 있는지 확인
- [ ] **Style Guide 있는지?** — 없으면 추가하세요. 형식 스펙만으로는 sub-agent가 고품질 출력을 생성하기 부족합니다
- [ ] **Phase 0 추가** — 작업 시작 전 분석 단계가 있는지?
- [ ] **`[ ]` 플레이스홀더가 있는 프롬프트 템플릿** — 플레이스홀더가 Phase 0 결과로 채워지는지 확인
- [ ] **병합 지침** — 다중 청크 출력의 단순 연결을 명시적으로 방지
- [ ] **`package_skill.py` 참조 제거** — OpenClaw에서 불필요
- [ ] **`init_skill.py` 참조 제거** — OpenClaw에서 불필요
- [ ] **description에 트리거 키워드** — 영어 및 현지화된 키워드 모두 포함
- [ ] **"사용 시점"을 body에서 description으로 이동** — OpenClaw는 트리거 후에만 body를 로드합니다

## Codex에서 유지할 패턴

다음은 두 환경 모두에서 잘 작동하는 좋은 패턴입니다:

1. **Progressive Disclosure** — SKILL.md를 500줄 이하로 유지하고, 세부 사항은 references/로 이동
2. **"간결함이 핵심" 원칙** — 에이전트가 이미 아는 것을 다시 설명하지 마세요
3. **자유도 조절** — 작업의 취약성(높음/중간/낮음)에 따라 구체성을 조정
4. **단일 레벨 참조 깊이** — references/ 내에서 다른 references/를 참조하지 마세요
5. **사용 후 개선** — 스킬을 사용하고, 실패를 관찰하고, 수정하고, 반복


path: references/openclaw-vs-codex.zh.md
content: # OpenClaw vs Codex Skill Creator

> 记录了打包的 Codex skill-creator（`/app/skills/skill-creator/`）与新的 OpenClaw 原生 skill-creator 之间的差异。在创建新的 OpenClaw 技能或移植现有 Codex 技能时，请参考此文档。

## 架构差异

| | Codex（CLI 编码代理） | OpenClaw（多代理） |
|---|---|---|
| 执行 | 单个 CLI 会话 | 主代理 + sub-agent（spawn/fork） |
| 上下文 | 所有上下文存在于会话内 | sub-agent 以**空**上下文启动 |
| 技能加载 | description → body → scripts（顺序） | description（始终） → body（触发时） → references（按需） |
| 技能存储 | 单一位置 | workspace（重启间保持）vs bundled（更新时重置） |
| 提示注入 | 不需要（单一上下文） | **必需**（显式注入到 sub-agent） |
| 打包 | `package_skill.py` 创建 `.skill` 文件 | 不需要打包 — 直接识别文件夹结构 |

## 5 个关键差异

### 1. Sub-Agent 上下文注入

**Codex**：所有工作在一个会话中进行，上下文共享是自然的。

**OpenClaw**：当你 spawn 一个 sub-agent 时，它的上下文是**空的**。主代理必须将 Phase 0 中收集的信息显式注入到 sub-agent 的提示中。

Codex 技能没有这个概念。在 OpenClaw 中，这是最重要的模式。

```
Codex:   "总结这段文本" → OK（上下文已存在）
OpenClaw: "总结这段文本" → FAIL（sub-agent 没有上下文）

OpenClaw 正确方法：
"这段文本是《OOO 用户手册》的第 1-5 节。
完整文档共 5 个部分 27 个小节。此片段涵盖'新设计方法'。
请保留以下内容：[类比]、[引文]、[案例研究]..."
```

### 2. Style Guide 优先

**Codex**："简洁是关键" — 专注于节省上下文窗口。假设代理已经足够聪明。

**OpenClaw**：没有 Style Guide，sub-agent 会变成"文本压缩器"。**判断标准**是必需的。

Codex 技能专注于格式（结构、长度），但 OpenClaw 技能还必须包含判断标准（保留什么、使用什么语气、从什么角度）。

### 3. Phase 0（分析阶段）必需

**Codex**：代理在工作中自然进行分析。

**OpenClaw**：需要主代理在 Phase 0 中分析，然后将结果注入 sub-agent 提示的流水线。

没有 Phase 0 时：
- 每个片段独立处理（整体流程丢失）
- 片段间出现重复内容
- 作者的声音（类比、引文）被丢弃

### 4. 顺序流水线

**Codex**：可以并行生成多个输出，代理自然合并。

**OpenClaw**：复杂输出应从简单到复杂顺序展开。

示例：摘要深度 1x + 5x
- Codex：可以并行生成（代理合并）
- OpenClaw：1x → 5x 顺序（1x 结构作为 5x 的骨架）

### 5. 不需要打包

**Codex**：`package_skill.py` 创建 `.skill` 文件（本质上是 zip）用于分发。

**OpenClaw**：直接识别文件夹结构。技能只需要 `SKILL.md` 就能工作。

不需要打包脚本、验证脚本或 init 脚本。

## 移植清单：Codex 技能 → OpenClaw 技能

将 Codex 技能移植到 OpenClaw 时：

- [ ] **检查是否需要 sub-agent** — 如果技能进行分块或并行处理，确认 Phase 0 + 上下文注入模式是否存在
- [ ] **Style Guide 是否存在？** — 如果没有，请添加。仅靠格式规范不足以让 sub-agent 产生高质量输出
- [ ] **添加 Phase 0** — 工作开始前是否有分析阶段？
- [ ] **带有 `[ ]` 占位符的提示模板** — 确认占位符被 Phase 0 结果填充
- [ ] **合并指令** — 明确防止多片段输出的简单拼接
- [ ] **移除 `package_skill.py` 引用** — OpenClaw 中不需要
- [ ] **移除 `init_skill.py` 引用** — OpenClaw 中不需要
- [ ] **description 中包含触发关键词** — 同时包含英文和本地化关键词
- [ ] **将"使用时机"从 body 移到 description** — OpenClaw 只在触发后才加载 body

## 从 Codex 保留的模式

以下是在两种环境中都能良好工作的优秀模式：

1. **Progressive Disclosure** — 保持 SKILL.md 在 500 行以下，将细节移到 references/
2. **"简洁是关键"原则** — 不要重新解释代理已经知道的内容
3. **自由度调整** — 根据任务的脆弱性（高/中/低）调整具体程度
4. **单层引用深度** — 不要在 references/ 内引用其他 references/
5. **使用后改进** — 使用技能，观察失败，修复，重复


path: examples/scaffold.md
content: # Example: scaffold (Code Generation)

Generates project structures, config files, and boilerplate.

## Characteristics
- Phase 0: requirements analysis (framework, language, package manager)
- No sub-agents (single generation)
- Style Guide: partial target (code preservation criteria)
- Core: framework-specific templates, existing file preservation

## skill-audit Score: 80.9 (B)
N/A: E → A(24%), B(18%), C(24%), D(18%), F(16%)

## Skill Structure
```
scaffold/
├── SKILL.md                              # 133 lines — structure + Phase 0 + config templates
└── references/
    └── framework-templates.md             # Next.js, Express, CLI, Docker templates
```

## Lessons Learned
- Preservation Criteria is key for code-gen ("never overwrite existing files")
- Phase 0 works well as "requirements analysis" here
- Separating templates into references/ makes SKILL.md flexible (easy to add new frameworks)


path: examples/unit-converter.md
content: # Example: unit-converter (Single Task)

The simplest skill type — no sub-agents, single execution, parameter parsing only.

## Characteristics
- No Phase 0 (simple lookup)
- No sub-agents
- Style Guide: N/A
- Core: natural language unit expression parsing + conversion table

## skill-audit Score: 75.9 (B-)
N/A: C+E → A(30%), B(20%), D(20%), F(30%)

## Skill Structure
```
unit-converter/
├── SKILL.md                              # 142 lines — conversion table + parsing rules
└── references/
    └── conversion-factors.md             # NIST-sourced exact conversion factors
```

## Lessons Learned
- Single-task skills can work with SKILL.md alone (references are optional)
- The conversion table itself acts as a "Style Guide" — accuracy criteria are inherent
- Low Workflow(D) score is natural — Phase 0 would be over-engineering for this type


path: examples/screenshot-capture.md
content: # Example: screenshot-capture (Tool Integration)

Combines OpenClaw tools (browser, nodes, image) to produce a result.

## Characteristics
- Phase 0: source detection (URL vs Node vs current browser)
- No sub-agents (direct tool calls)
- Style Guide: N/A
- Core: tool combination patterns, error fallback chains

## skill-audit Score: 78.0 (B)
N/A: C+E → A(30%), B(20%), D(20%), F(30%)

## Skill Structure
```
screenshot-capture/
├── SKILL.md                              # 108 lines — capture methods + error handling
└── references/
    └── browser-automation-notes.md       # stale refs, SPA, Cloudflare workarounds
```

## Lessons Learned
- Tool-integration skills hinge on "which tool, when" — decision logic is the core
- Error fallback chains matter (Cloudflare → web_fetch → firecrawl)
- Moving tool-specific caveats to references/ keeps SKILL.md clean


path: examples/changelog.md
content: # Example: changelog (Doc Conversion)

Transforms source data (git commits) into structured output (CHANGELOG.md).

## Characteristics
- Phase 0: repo analysis (commit range, version inference)
- No sub-agents (single pipeline)
- Style Guide: target (commit message preservation/compression criteria)
- Core: conventional commit parsing, category grouping, semver bump suggestion

## skill-audit Score: 85.1 (B+)
N/A: E → A(24%), B(18%), C(24%), D(18%), F(16%)

## Skill Structure
```
changelog/
├── SKILL.md                              # 126 lines — pipeline + commit parsing rules
└── references/
    └── conventional-commits.md           # Conventional Commits v1.0.0 summary
```

## Lessons Learned
- Style Guide connects naturally to parsing criteria (preserve original commit messages, compress similar ones)
- Clear phase numbering (Phase 0–4) raises Workflow(D) scores
- Good example of how to apply Style Guide to "partial target" skills


path: examples/skill-audit.md
content: # Example: skill-audit (Meta Validation Tool)

A meta-tool that evaluates other skills. Unique type, categorized separately.

## Characteristics
- No Phase 0 (simple Read → Score → Report)
- Sub-agents: optional (parallel when many targets)
- Style Guide: N/A, Sub-Agent Design: N/A
- Core: multi-dimensional scoring, N/A weight redistribution, batch mode

## Skill Structure
```
skill-audit/
├── SKILL.md                              # 6-dimension rubric + output format
└── references/
    ├── scoring-rubric.md                 # Detailed examples per dimension
    └── audits/                           # Completed audit reports
```

## Lessons Learned
- Meta-tools can self-audit — enabling quality loop checks
- N/A redistribution logic is critical — must cover 3 cases: C only, E only, C+E
- Differentiation from spec-based tools lies in quality scoring (Style Guide, Phase 0, sub-agent design), not structural validation


path: examples/summarize.md
content: # Example: summarize (Sub-Agent Pipeline)

The summarize skill was the first skill validated using skill-creator's 5-step process.

## Why This Skill Was Created

Existing summarization skills were locked into project-specific depth terminology (1x/5x) and didn't match real user requests ("make it short", "200 chars", "by chapter", "use emojis"). A universal summarization skill was needed.

## skill-creator Process Applied

### Step 1: Analyze "Good Results"
- Extracted patterns: Style Guide, Phase 0, sub-agent context injection
- Collected 30+ natural language request patterns from actual usage

### Step 2: Analyze "Failed Results"
- Existing limitations: depth=1x/5x only, no per-language length control, no style variants
- These limitations became the new skill's requirements

### Step 3: Write Style Guide
- Defined essence: "information restructuring", not "text compression"
- Specified preservation/compression criteria
- Defined 7 style-specific writing rules

### Step 4: Structure Workflow
- Natural language parser (Phase 0) → parameter mapping → chunk → sub-agent → merge → output

### Step 5: Split References
- `parameter-mapping.md` — 30+ natural language request → parameter mapping table
- `subagent-templates.md` — Per-style sub-agent instructions
- `output-format.md` — Per-style output specifications

## Validation Results

5 test cases:

| TC | Request | length | style | Result |
|----|---------|--------|-------|--------|
| 1 | "summarize briefly" | short | brief | ✅ 8 bullets |
| 2 | "summarize by chapter" | auto | chapter | ✅ 8 section headings |
| 3 | "use lots of emojis" | auto | emoji-rich | ✅ 25+ emojis |
| 4 | "Korean, under 200 chars" | 200 | brief | ✅ 186 chars |
| 5 | "don't miss anything" | full | comprehensive | ⚠️→fixed |

### Issue Found & Fixed
- **chapter vs comprehensive ambiguity** → chapter = 2-3 sentences per section; comprehensive = restructured prose (not copy), all important content preserved

## Final Structure

```
summarize/
├── SKILL.md                              # Minimal — delegates to references
└── references/
    ├── parameter-mapping.md              # Natural language → parameter mapping
    ├── subagent-templates.md             # Sub-agent prompt templates per style
    └── output-format.md                  # Output specs per style
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)