diff --git a/docs/.vuepress/notes/en/guide.ts b/docs/.vuepress/notes/en/guide.ts
index 66aa93beb..5b741552d 100644
--- a/docs/.vuepress/notes/en/guide.ts
+++ b/docs/.vuepress/notes/en/guide.ts
@@ -128,5 +128,15 @@ export const Guide: ThemeNote = defineNoteConfig({
                 "web_collection"
             ]
         },
+        {
+            text: "DataFlow Skills",
+            collapsed: false,
+            icon: 'carbon:skill-level-advanced',
+            prefix: 'skills',
+            items: [
+                "dataflow-operator-builder",
+                "prompt-template-builder",
+            ]
+        },
     ],
 })
diff --git a/docs/.vuepress/notes/zh/guide.ts b/docs/.vuepress/notes/zh/guide.ts
index ab6dd9042..1642ef920 100644
--- a/docs/.vuepress/notes/zh/guide.ts
+++ b/docs/.vuepress/notes/zh/guide.ts
@@ -127,6 +127,16 @@ export const Guide: ThemeNote = defineNoteConfig({
                 "web_collection"
             ]
         },
+        {
+            text: "DataFlow Skills",
+            collapsed: false,
+            icon: 'carbon:skill-level-advanced',
+            prefix: 'skills',
+            items: [
+                "dataflow-operator-builder",
+                "prompt-template-builder",
+            ]
+        },
         // {
         //     text: '写作',
         //     icon: 'fluent-mdl2:edit-create',
diff --git a/docs/en/notes/guide/skills/dataflow-operator-builder.md b/docs/en/notes/guide/skills/dataflow-operator-builder.md
new file mode 100644
index 000000000..ceaa9c1b3
--- /dev/null
+++ b/docs/en/notes/guide/skills/dataflow-operator-builder.md
@@ -0,0 +1,262 @@
+---
+title: Operator Builder — Operator Scaffold Generator
+createTime: 2026/04/06 00:00:00
+permalink: /en/guide/skills/dataflow-operator-builder/
+---
+
+Video tutorial: [Build DataFlow Operator](https://files.catbox.moe/uzk3ag.mp4)
+
+## 1. Overview
+
+**Operator Builder (`dataflow-operator-builder`)** is a Claude Code Skill that generates a complete, production-grade scaffold for custom DataFlow operators in one step. It targets developers who frequently create new operators, automating the repetitive workflow of "define spec → generate code → register → test."
+
+The Skill can:
+
+1. **Spec Validation**: Statically check the operator spec before code generation, catching common issues such as registration conflicts, contract violations, and naming errors early.
+2. **Skeleton Generation**: Produce standardized operator implementation code based on the operator type (`generate` / `filter` / `refine` / `eval`).
+3. **CLI Entry Generation**: Automatically create a standalone command-line entry script under the `cli/` directory for batch processing and independent testing.
+4. **Test File Generation**: Generate three categories of test baselines — `unit` / `registry` / `smoke` — ready to plug into CI.
+5. **Safe Write**: Preview the file plan via `--dry-run` first, then write only after confirmation, with multiple overwrite strategies available.
+
+## 2. Core Features
+
+### 2.1 Two Working Modes
+
+The Skill offers two startup methods to fit different scenarios:
+
+- **Interactive Interview (Mode A)**: Invoke `/dataflow-operator-builder` directly. The Agent collects all spec information through two rounds of batch questions — no files need to be prepared in advance. Ideal for first-time use or when you are unsure about the parameters.
+- **Direct Spec (Mode B)**: Provide a JSON spec file and skip the interview to generate immediately. Best when you already have a clear spec or need to create operators in bulk.
+
+### 2.2 Two-Stage Output
+
+To ensure safety and auditability, the generation process is split into two stages:
+
+1. **Dry-run Stage**: Outputs the complete file creation/update plan, listing every file path and its status (CREATE / UPDATE), without writing anything.
+2. **Generation Stage**: Actual file writes are executed only after confirmation, with an optional validation pass (`basic` or `full`) to verify correctness.
+
+### 2.3 Multi-Level Validation
+
+After generation, validation can be run at three levels:
+
+| Validation Level | Checks Performed | Recommended Use |
+|------------------|------------------|-----------------|
+| `none` | No validation | Quick prototyping |
+| `basic` | Module importable + class registered + test files exist | Day-to-day development |
+| `full` | `basic` + run smoke tests + inspect output artifacts | Before formal submission (recommended) |
+
+## 3. Workflow
+
+The full execution flow of the Skill is as follows:
+
+1. **Load Reference Rules**: Read internal constraint documents (operator contracts, registration rules, CLI conventions, acceptance checklists, etc.).
+2. **Select Mode**: Choose interactive interview or direct Spec mode based on user input.
+3. **Build Spec JSON**: Normalize the collected information into a spec JSON object.
+4. **Dry-run Preview**: Display the file plan, listing files to be created or updated.
+5. **Confirm Write Strategy**: Present the overwrite strategy and require explicit user confirmation (`y/N`).
+6. **Generate Files**: Execute the actual code generation and file writes.
+7. **Run Validation**: Execute validation at the selected level.
+8. **Output Report**: Summarize the generated file paths, validation results, and suggested follow-up commands.
+
+## 4. Usage Guide
+
+### 4.1 Adding the Skill
+
+**Prerequisites**: Claude Code CLI must already be installed. Refer to the [Claude Code official documentation](https://code.claude.com/docs/en) or the [DataFlow-Skills README](https://github.com/haolpku/DataFlow-Skills) for installation instructions.
+
+Clone the repository and copy the Skill directory into Claude Code's skills folder:
+
+```bash
+git clone https://github.com/haolpku/DataFlow-Skills.git
+
+# Project-level (available only in the current project)
+cp -r DataFlow-Skills/dataflow-operator-builder .claude/skills/dataflow-operator-builder
+
+# Or user-level (available across all projects)
+cp -r DataFlow-Skills/dataflow-operator-builder ~/.claude/skills/dataflow-operator-builder
+```
+
+Claude Code automatically discovers Skills from `.claude/skills/<skill-name>/SKILL.md`. Once the copy is complete, the `/dataflow-operator-builder` command becomes available in Claude Code.
+
+### 4.2 Mode A: Interactive Interview
+
+Invoke directly inside Claude Code:
+
+```
+/dataflow-operator-builder
+```
+
+The Agent collects all required information through **two rounds of batch questions**. Each question comes with recommended options and a brief rationale — simply choose or fill in your answers.
+
+#### Round 1: Structural Fields
+
+This round determines the operator's "skeleton" information:
+
+| Question | Description | Recommendation | Maps to Spec Field |
+|----------|-------------|----------------|-------------------|
+| Operator type | `generate` / `filter` / `refine` / `eval` | `generate` (most common) | `operator_type` |
+| Operator identifier | Class name + module file name | Fill in as needed | `operator_class_name`, `operator_module_name` |
+| Repository location | Package name + output root directory | Fill in as needed | `package_name` + `--output-root` |
+| LLM dependency | Whether the operator needs to call a large model | Choose `yes` for generate/refine/eval types | `uses_llm` |
+| CLI module name | File name for the command-line entry | `<module_name>_cli` (default) | `cli_module_name` |
+
+#### Round 2: Implementation Details
+
+This round determines runtime behavior:
+
+| Question | Description | Recommendation | Maps to Spec Field |
+|----------|-------------|----------------|-------------------|
+| Input/output fields | Column names in the dataframe | Specify explicitly | `input_key`, `output_key` |
+| Description language | Language support for `get_desc()` | Bilingual (Chinese & English) | Generation preference |
+| Extra CLI arguments | Whether custom command-line arguments are needed | Use defaults only | Extension notes |
+| Test prefix | Prefix for test file names | Same as module name | `test_file_prefix` |
+| Overwrite strategy | How to handle existing files | `ask-each` (safest) | `overwrite_strategy` |
+| Validation level | Validation rigor after generation | `full` (recommended) | `validation_level` |
+
+After both rounds are answered, the Agent automatically builds the spec and enters the generation flow. Follow-up questions are only asked when a high-impact field is missing or conflicts are detected.
+
+### 4.3 Mode B: Direct Spec
+
+If you already have a clear operator spec, you can skip the interview and pass the spec file directly:
+
+```
+/dataflow-operator-builder --spec path/to/spec.json --output-root path/to/repo
+```
+
+#### Spec JSON Field Reference
+
+**Required fields:**
+
+| Field | Type | Description | Example |
+|-------|------|-------------|---------|
+| `package_name` | string | Package the operator belongs to | `"dataflow_ext_demo"` |
+| `operator_type` | string | Operator type: `generate` / `filter` / `refine` / `eval` | `"filter"` |
+| `operator_class_name` | string | Operator class name (PascalCase) | `"DemoQualityFilter"` |
+| `operator_module_name` | string | Operator module file name (snake_case, without .py) | `"demo_quality_filter"` |
+| `input_key` | string | Input data column name | `"raw_text"` |
+| `output_key` | string | Output data column name | `"is_valid"` |
+| `uses_llm` | boolean | Whether an LLM service is required | `false` |
+
+**Optional fields:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `cli_module_name` | string | `<operator_module_name>_cli` | CLI entry file name |
+| `test_file_prefix` | string | `<operator_module_name>` | Prefix for test file names |
+| `overwrite_strategy` | string | `"ask-each"` | Overwrite strategy: `ask-each` / `overwrite-all` / `skip-existing` |
+| `validation_level` | string | `"full"` | Validation level: `none` / `basic` / `full` |
+
+**Full example:**
+
+```json
+{
+  "package_name": "dataflow_ext_demo",
+  "operator_type": "filter",
+  "operator_class_name": "DemoQualityFilter",
+  "operator_module_name": "demo_quality_filter",
+  "input_key": "raw_text",
+  "output_key": "is_valid",
+  "uses_llm": false,
+  "cli_module_name": "demo_quality_filter_cli",
+  "test_file_prefix": "demo_quality_filter",
+  "overwrite_strategy": "ask-each",
+  "validation_level": "full"
+}
+```
+
+### 4.4 Viewing the Output
+
+#### Generated Artifacts
+
+| Artifact | Path | Description |
+|----------|------|-------------|
+| Operator implementation | `<package>/<module_name>.py` | Class definition, `run()` method signature, and `OPERATOR_REGISTRY` registration entry |
+| CLI entry | `cli/<cli_module_name>.py` | Standalone command-line batch script, invoked via `--input-file` / `--output-file` |
+| Unit tests | `tests/unit/test_<prefix>.py` | Basic functionality tests |
+| Registry tests | `tests/registry/test_<prefix>_registry.py` | Verifies the operator is correctly registered in `OPERATOR_REGISTRY` |
+| Smoke tests | `tests/smoke/test_<prefix>_smoke.py` | End-to-end minimal acceptance using a temporary `FileStorage` for a full run |
+
+#### Generated Operator Skeleton
+
+All generated operators follow a uniform structure:
+
+```python
+from dataflow.operators.base import BaseOperator
+from dataflow.utils.storage import FileStorage
+
+class DemoQualityFilter(BaseOperator):
+    def __init__(self, threshold: float = 0.5):
+        self.threshold = threshold
+
+    def run(self, storage: FileStorage) -> FileStorage:
+        # Implement filtering logic here
+        ...
+        return storage
+
+# Registration entry (auto-generated by the Skill)
+OPERATOR_REGISTRY.register("DemoQualityFilter", DemoQualityFilter)
+```
+
+**Key rules:**
+- Must inherit from `BaseOperator` and implement the `run()` method
+- `run()` accepts and returns a `FileStorage` instance to maintain chainable passing
+- Must register via `OPERATOR_REGISTRY` so the operator can be discovered by Pipelines
+- The CLI entry invokes `run()` directly through `--input-file` / `--output-file` arguments, decoupled from the Pipeline context
+- `get_desc(lang)` must support bilingual output (`zh` / `en`)
+
+#### Common CLI Arguments
+
+| Argument | Description | Possible Values |
+|----------|-------------|-----------------|
+| `--dry-run` | Show the file plan only; do not write any files | — |
+| `--overwrite` | Control overwrite behavior for existing files | `ask-each` (confirm one by one) / `overwrite-all` (overwrite everything) / `skip-existing` (skip existing files) |
+| `--validation-level` | Validation rigor after generation | `none` / `basic` / `full` |
+| `--log-dir` | Path for storing run logs | Custom path |
+| `--no-log` | Disable run logging | — |
+
+## 5. Mode Comparison and Recommendations
+
+| Dimension | Interactive Interview (Mode A) | Direct Spec (Mode B) |
+|-----------|-------------------------------|---------------------|
+| Best for | First-time use, uncertain parameters | Spec already defined, bulk creation |
+| Invocation | `/dataflow-operator-builder` | `/dataflow-operator-builder --spec spec.json` |
+| Learning curve | Low — step-by-step guidance | Medium — requires familiarity with spec format |
+| Flexibility | High — each field can be adjusted individually | High — programmable and scriptable |
+| Efficiency | Requires answering two rounds of questions | Single submission, faster |
+| Reproducibility | Lower — depends on the conversation | High — spec file can be version-controlled |
+
+**Recommendations:**
+- If this is your first time or you are unsure about the parameters → choose **Mode A**
+- If you have used it before and saved a spec, or need to generate multiple operators in bulk → choose **Mode B**
+- For team collaboration, it is recommended to version-control the spec file and standardize on **Mode B**
+
+## 6. Notes and FAQ
+
+### 6.1 Important Notes
+
+**Registration must be complete**: The generated operator must be registered via the `@OPERATOR_REGISTRY.register()` decorator; otherwise the Pipeline will not be able to discover it. If the registry test fails, first check whether the decorator is present and whether the module is correctly imported.
+
+**`storage.step()` must not be omitted**: When invoking an operator from the CLI or a Pipeline, you must pass `storage=storage.step()` rather than the raw `storage`. Omitting `step()` will cause the operator to read empty data or write output files to unexpected paths.
+
+**Input fields must align**: `input_key` must be an existing column name in the input dataframe. If you encounter a `KeyError` at runtime, check whether the `input_key` in the spec matches the actual data column name.
+
+**Review the overwrite strategy**: When working in a repository with existing code, always inspect the file list during the dry-run stage. The `ask-each` strategy is recommended so you can confirm each file individually — overwrite or skip.
+
+**Use `full` validation level**: The `full` level actually runs smoke tests and inspects output artifacts, catching most issues before submission. Only downgrade to `none` or `basic` during rapid prototyping.
+
+### 6.2 FAQ
+
+**Q: The operator cannot be found in `OPERATOR_REGISTRY` after generation?**
+
+A: This is usually caused by one of the following: (1) the `@OPERATOR_REGISTRY.register()` decorator is missing; (2) the operator module is not imported (check the `TYPE_CHECKING` block in `__init__.py`); (3) the class name is misspelled. Running the registry test (`test_<prefix>_registry.py`) can pinpoint the issue quickly.
+
+**Q: Smoke tests pass but CLI execution fails?**
+
+A: Check whether the CLI entry script correctly calls `storage.step()`, and whether the file pointed to by `--input-file` exists and is in the correct format (JSONL). The CLI and operator logic should remain decoupled — if the CLI contains operator-internal logic, the separation of concerns is broken.
+
+**Q: Errors when processing LLM responses (empty output, unexpected format)?**
+
+A: If the operator uses an LLM (`uses_llm: true`), you need to add defensive handling for model return values in `run()`. The generated skeleton includes helper methods (e.g., `_generate_text`, `_score_with_llm`); you should handle `None`, empty strings, and unexpected formats as fallbacks within those methods.
+
+**Q: `--overwrite-all` accidentally overwrote existing files?**
+
+A: The Skill displays the file plan and asks for confirmation before writing. If files were indeed overwritten by mistake, recover them via `git checkout`. Prevention measures: (1) always run `--dry-run` first; (2) use the `ask-each` or `skip-existing` strategy.
diff --git a/docs/en/notes/guide/skills/prompt-template-builder.md b/docs/en/notes/guide/skills/prompt-template-builder.md
new file mode 100644
index 000000000..101af7d14
--- /dev/null
+++ b/docs/en/notes/guide/skills/prompt-template-builder.md
@@ -0,0 +1,294 @@
+---
+title: Prompt Template Builder — Prompt Template Generator
+createTime: 2026/04/06 00:00:00
+permalink: /en/guide/skills/prompt-template-builder/
+---
+
+Video tutorial: [DataFlow Prompt Template Builder](https://files.catbox.moe/d1pdr9.mp4)
+
+## 1. Overview
+
+**Prompt Template Builder (`prompt-template-builder`)** is a Claude Code Skill for building or revising `prompt_template` classes for existing DataFlow operators. It addresses the core problem of "operator logic reuse + prompt customization" — when you want to apply the same operator to different business scenarios, you only need to create a new prompt template instead of rewriting the operator code.
+
+This Skill can:
+
+1. **Operator Interface Alignment**: Automatically inspect the target operator's constructor parameters and `run()` signature, ensuring the generated template fully conforms to the operator contract.
+2. **Automatic Template Type Selection**: Automatically choose the appropriate template style (`DIYPromptABC` or `FormatStrPrompt`) based on the target operator type.
+3. **Two-Stage Auditable Output**: First output a decision JSON (Stage 1), then the complete deliverables (Stage 2), facilitating code review and traceability.
+4. **Static Acceptance Gating**: Perform quality checks via a structured acceptance checklist to ensure the template is ready for delivery.
+5. **Targeted Revision**: If the result is unsatisfactory, accept feedback for targeted modifications and re-run acceptance checks.
+
+## 2. Core Features
+
+### 2.1 Operator Contract Alignment
+
+This is the most important feature of the Skill. Before generating a prompt template, the Skill verifies the following:
+
+- Whether the parameter signature of `build_prompt` matches how the target operator calls `prompt_template.build_prompt(...)`
+- Whether the `prompt_template` type matches the template type expected by the operator
+- Whether all variables referenced in the template come from explicit parameters or constants (no undeclared variables)
+
+If the target operator requires `DIYPromptABC` but you mistakenly use `FormatStrPrompt`, the Skill will catch this issue during the Stage 1 phase.
+
+### 2.2 Two-Stage Output
+
+Generated results are strictly divided into two stages:
+
+**Stage 1 (Decision JSON)** — Before writing any code, a structured decision record is produced:
+
+- `prompt_template_type_aligned`: The selected template type and rationale
+- `strategy`: Template design strategy (e.g., "single-field generation using system+user dual-layer prompts")
+- `argument_mapping`: Mapping from parameter names to their business meanings
+- `output_contract`: Output format constraints (e.g., "Chinese, no more than 80 characters")
+- `static_checks`: List of static check items to be verified
+
+**Stage 2 (Final Deliverables)** — Contains five parts:
+
+1. Template / configuration code
+2. Integration code snippet (ready to copy into a Pipeline)
+3. Example walkthrough (normal case + edge case)
+4. Static acceptance results
+5. Residual risk statement
+
+### 2.3 Supported Template Types
+
+| Template Type | Applicable Operators | Characteristics |
+|---------------|---------------------|-----------------|
+| `DIYPromptABC` | `PromptedGenerator`, `PromptedFilter`, `PromptedRefiner`, etc. | Fully customizable system/user prompts with field interpolation; maximum flexibility |
+| `FormatStrPrompt` | `FormatStrPromptedGenerator` | Uses Python f-string style templates; suitable for fixed-format scenarios with multi-field concatenation |
+
+**How to choose:**
+- If the target operator name starts with `FormatStr` (e.g., `FormatStrPromptedGenerator`), you must use `FormatStrPrompt`
+- For other operators with the `Prompted` prefix (e.g., `PromptedGenerator`, `PromptedFilter`), use `DIYPromptABC`
+- The binding between template type and operator contract is strict — **mixing is not allowed**
+
+## 3. Workflow
+
+The complete execution flow of the Skill is as follows:
+
+1. **Load Reference Rules and Parse Input**: Read internal reference documents (input schema, output contract, acceptance checklist, etc.) and parse user-provided information.
+2. **Select Mode**: Choose between interactive interview or direct Spec mode based on user input.
+3. **Parse Operator Contract**: Confirm the interface definition of the target operator `OP_NAME` and determine which template type to use.
+4. **Build Template Draft**: Generate prompt template code based on the operator contract and user requirements.
+5. **Output Stage 1 Decision JSON**: Present the template strategy, argument mapping, output contract, and static check items.
+6. **Output Stage 2 Final Deliverables**: Output template code, integration snippet, example walkthrough, and acceptance results.
+7. **Run Static Acceptance**: Verify each item in the acceptance checklist one by one.
+8. **Receive Feedback and Revise** (optional): If the user is unsatisfied, perform targeted modifications and repeat Stage 1 / Stage 2.
+
+## 4. Usage Guide
+
+### 4.1 Adding the Skill
+
+**Prerequisites**: Claude Code CLI must be installed. For installation instructions, refer to the [Claude Code official documentation](https://code.claude.com/docs/en) or the [DataFlow-Skills README](https://github.com/haolpku/DataFlow-Skills).
+
+Clone the repository and copy the Skill directory into Claude Code's skills folder:
+
+```bash
+git clone https://github.com/haolpku/DataFlow-Skills.git
+
+# Project-level (available only for the current project)
+cp -r DataFlow-Skills/prompt-template-builder .claude/skills/prompt-template-builder
+
+# Or user-level (available for all projects)
+cp -r DataFlow-Skills/prompt-template-builder ~/.claude/skills/prompt-template-builder
+```
+
+Claude Code automatically discovers Skills from `.claude/skills/<skill-name>/SKILL.md`. Once copied, the `/prompt-template-builder` command will be available in Claude Code.
+
+### 4.2 Mode A: Interactive Interview
+
+Invoke directly in Claude Code:
+
+```
+/prompt-template-builder
+```
+
+The Agent will collect all necessary information through **two rounds of batch questions**. Each question includes recommended options and rationale.
+
+#### Round 1: Structural Fields
+
+Determine "what to do" and "for whom":
+
+| Question | Description | Recommendation | Mapped Field |
+|----------|-------------|----------------|--------------|
+| Task Type | New / Rewrite / Iterative optimization | New (most stable for first version) | `Task Mode` |
+| Target Operator | Specify `OP_NAME` | Specify a single operator (avoid scope creep) | `OP_NAME` |
+| Output Constraint Strength | Strong / Medium / Light constraints | Strong constraint schema (improves parsability) | `Expected Output` |
+| Tone & Style | Professional & concise / Didactic / Strict audit | Professional & concise | `Tone/Style` |
+| Constraint Source | Business rules / Examples / Reference cases | Business rules first | `Constraints` |
+
+#### Round 2: Implementation Fields
+
+Determine the "how" details:
+
+| Question | Description | Recommendation | Mapped Field |
+|----------|-------------|----------------|--------------|
+| `build_prompt` Parameters | Parameter list for the template function | Explicitly list all parameters (avoid variable drift) | `Arguments` |
+| Output Format Details | JSON / Text paragraph / List | JSON + explicit field types | `Expected Output` |
+| Sample Coverage | Normal + edge / Normal only / Multiple edge | 1 normal + 1 edge | `Sample Cases` |
+| Acceptance Focus | Interface consistency / Copy quality / Structural completeness | Interface consistency first | `Validation Focus` |
+
+After both rounds are answered, the generation process starts automatically. Follow-up questions are only asked when `Target` or `OP_NAME` is missing, parameter-to-template-variable mappings conflict, or output constraints are contradictory.
+
+### 4.3 Mode B: Direct Spec
+
+If you already have a clear prompt requirement, you can skip the interview:
+
+```
+/prompt-template-builder --spec path/to/prompt_spec.json
+```
+
+#### Spec JSON Field Descriptions
+
+**Required fields:**
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `Target` | Business objective description | `"生成简洁的电商商品卖点"` |
+| `OP_NAME` | Target operator class name | `"PromptedGenerator"` |
+
+**Recommended fields:**
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `Constraints` | Business constraint conditions | `"语气专业；中文不超过80字"` |
+| `Expected Output` | Output format requirements | `"单行纯文本"` |
+| `Arguments` | Prompt parameter list | `["product_name", "category"]` |
+| `Sample Cases` | 1–3 input/expected output pairs | See example below |
+| `Tone/Style` | Tone and style | `"专业简洁"` |
+| `Validation Focus` | Acceptance focus area | `"接口一致性"` |
+
+**Complete example:**
+
+```json
+{
+  "Target": "生成简洁的电商商品卖点",
+  "OP_NAME": "PromptedGenerator",
+  "Constraints": "语气专业；中文不超过80字",
+  "Expected Output": "单行纯文本",
+  "Arguments": ["product_name", "category"],
+  "Sample Cases": [
+    {"product_name": "降噪耳机", "category": "电子产品"}
+  ],
+  "Tone/Style": "专业简洁",
+  "Validation Focus": "接口一致性"
+}
+```
+
+### 4.4 Viewing the Output
+
+#### Stage 1: Decision JSON
+
+A structured decision record is output first for team review:
+
+```json
+{
+  "prompt_template_type_aligned": "DIYPromptABC",
+  "strategy": "单字段生成，使用 system+user 双层提示词",
+  "argument_mapping": {
+    "product_name": "商品名",
+    "category": "品类"
+  },
+  "output_contract": "中文，不超过 80 字，以卖点句式结尾",
+  "static_checks": [
+    "无多余占位符",
+    "语气符合专业定义",
+    "字数约束可在 Stage 2 walkthrough 中核验"
+  ]
+}
+```
+
+**Key rules:**
+- `prompt_template_type_aligned` must match the target operator's contract
+- Every item in `static_checks` must be verified one by one during the Stage 2 acceptance walkthrough
+- `argument_mapping` must fully correspond to the `Arguments` field with no omissions
+
+#### Stage 2: Final Deliverables
+
+Using e-commerce selling point generation as an example, Stage 2 includes the following:
+
+**1. Prompt Design Code:**
+
+```python
+system_prompt = (
+    "你是电商文案助手。"  # You are an e-commerce copywriting assistant.
+    "语气专业，最多80字，不使用夸张承诺。"  # Professional tone, max 80 chars, no exaggerated claims.
+    "只返回一行中文文本，不要 JSON，不要额外解释。"  # Return one line of Chinese text only, no JSON, no extra explanation.
+)
+user_prompt = "请基于输入内容生成一句电商卖点描述："  # Generate a one-line e-commerce selling point based on the input:
+```
+
+**2. Integration Code Snippet:**
+
+```python
+self.generator = PromptedGenerator(
+    llm_serving=self.llm_serving,
+    system_prompt=system_prompt,
+    user_prompt=user_prompt,
+)
+```
+
+**3. Example Walkthrough:**
+- Normal case: `降噪耳机/电子产品` → Outputs a professional selling point within 80 characters
+- Edge case: `product_name` is empty → Output should indicate insufficient information; no fabricated content generated
+
+**4. Static Acceptance Results:**
+- `input_completeness` ✓
+- `operator_interface_aligned` ✓
+- `prompt_template_type_aligned` ✓
+- `no_invented_params` ✓
+- `output_schema_explicit` ✓
+
+**5. Residual Risks:** None (this is a simple scenario)
+
+## 5. Mode Comparison and Selection Guide
+
+| Dimension | Interactive Interview (Mode A) | Direct Spec (Mode B) |
+|-----------|-------------------------------|----------------------|
+| Best for | First-time use, unclear requirements | Clear requirements, team collaboration |
+| How to start | `/prompt-template-builder` | `/prompt-template-builder --spec spec.json` |
+| Learning curve | Low, step-by-step guidance | Medium, requires understanding the spec format |
+| Efficiency | Requires answering two rounds of questions | One-shot submission, faster |
+| Reproducibility | Lower | High, spec files can be version-controlled |
+| Iterative revision | Supports conversational feedback | Modify the spec and re-run |
+
+**Selection advice:**
+- If you're unsure which operator to use or how to write constraints → choose **Mode A**, the Agent will guide you step by step
+- If you already have a spec from a previous run and only need minor tweaks → choose **Mode B**
+- When rolling out across a team, it's recommended to version-control spec files and standardize on **Mode B** for consistency
+
+## 6. Notes and FAQ
+
+### 6.1 Key Considerations
+
+**Template types must not be mixed**: `prompt_template_type_aligned` must strictly match the target operator's contract. For example, `PromptedGenerator` should use `DIYPromptABC`, while `FormatStrPromptedGenerator` must use `FormatStrPrompt`. Mixing them will cause runtime type errors or the operator failing to recognize the template.
+
+**`build_prompt` parameters must be aligned**: The parameter signature of the template's `build_prompt` method must exactly match the parameters passed when the operator calls it (name, count, type). Mismatches will cause a `TypeError`. The Skill lists all parameter mappings in the Stage 1 `argument_mapping` — review them carefully.
+
+**Output format must be explicit**: Avoid vague descriptions like "try to output JSON" in the prompt. You must explicitly define field names, types, and value ranges for the output. Vague output requirements lead to unstable model output that is difficult to parse.
+
+**Template variables must not appear out of thin air**: Variables referenced in `build_prompt` must come from function parameters or class constants. If the template contains a variable not declared in the parameter list, formatting will raise a `NameError` or produce empty values.
+
+**v1 uses static acceptance**: The current version uses a "static acceptance + example walkthrough" loop and does not automatically run subprocess tests. This means acceptance results are based on code structure checks, not runtime behavior. If you need runtime verification, you must manually integrate the generated code into a Pipeline and execute it.
+
+### 6.2 FAQ
+
+**Q: Getting a `TypeError` at runtime saying `build_prompt` parameters don't match?**
+
+A: This is the most common issue. The root cause is a mismatch between the `build_prompt` parameter signature and the operator call site. Solution: (1) Check the target operator's source code or documentation for how `prompt_template.build_prompt(...)` is called; (2) Verify that `argument_mapping` in Stage 1 fully covers all parameters; (3) Use the Skill's targeted revision feature to fix the signature.
+
+**Q: Model output is unstable and the format keeps drifting?**
+
+A: This is usually because the output format constraints in the prompt are not strict enough. Check the following: (1) Does the prompt explicitly define the output schema (field names, types)? (2) Does it use strong constraint statements like "return only XXX, no extra explanation"? (3) Does it include a format example of the expected output at the end of the prompt?
+
+**Q: The generated template code looks correct, but the operator doesn't recognize it?**
+
+A: Check whether the template type matches the operator. If you used `DIYPromptABC` but the target operator expects `FormatStrPrompt` (or vice versa), the operator will ignore it or throw an error. Review the `prompt_template_type_aligned` field in Stage 1 to confirm the match.
+
+**Q: I want to adjust the strategy after Stage 1 is output — how?**
+
+A: Simply provide your feedback to the Agent. The Skill supports targeted revision after receiving feedback — it will preserve unchanged parts, modify only the issues you pointed out, then re-output Stage 1 and Stage 2 and re-run static acceptance.
+
+**Q: A business requirement needs multiple prompt classes — should I split or merge?**
+
+A: As a general principle, try to accomplish the task with a single template class. Split only when the semantic responsibilities are significantly different (e.g., one for generation and one for filtering). If the Stage 1 strategy explanation cannot justify the need for splitting, it should be merged. Over-splitting increases maintenance costs.
diff --git a/docs/zh/notes/guide/skills/dataflow-operator-builder.md b/docs/zh/notes/guide/skills/dataflow-operator-builder.md
new file mode 100644
index 000000000..8bf70fa55
--- /dev/null
+++ b/docs/zh/notes/guide/skills/dataflow-operator-builder.md
@@ -0,0 +1,262 @@
+---
+title: Operator Builder — 算子脚手架生成
+createTime: 2026/04/06 00:00:00
+permalink: /zh/guide/skills/dataflow-operator-builder/
+---
+
+视频教程：[Build DataFlow Operator](https://files.catbox.moe/uzk3ag.mp4)
+
+## 1. 概述
+
+**Operator Builder (`dataflow-operator-builder`)** 是一个 Claude Code Skill，用于一键生成生产级 DataFlow 自定义算子的完整脚手架。它面向需要频繁创建新算子的开发者，将"定义规格 → 生成代码 → 注册 → 测试"这一重复流程自动化。
+
+该 Skill 能够：
+
+1. **规格校验**：在生成代码前，对算子规格（spec）进行静态检查，提前暴露注册、契约、命名等常见问题。
+2. **骨架生成**：根据算子类型（`generate` / `filter` / `refine` / `eval`），生成标准化的算子实现代码。
+3. **CLI 入口生成**：在 `cli/` 目录下自动创建独立的命令行入口脚本，便于批处理和独立测试。
+4. **测试文件生成**：同步生成 `unit` / `registry` / `smoke` 三类测试基线，可直接接入 CI。
+5. **安全写入**：先通过 `--dry-run` 预览文件计划，确认后再写入，支持多种覆盖策略。
+
+## 2. 核心特性
+
+### 2.1 两种工作模式
+
+Skill 提供两种启动方式，适配不同场景：
+
+- **交互式采访（Mode A）**：直接调用 `/dataflow-operator-builder`，Agent 通过两轮批量提问自动采集规格信息，无需提前准备任何文件。适合首次使用或不确定参数的场景。
+- **直接指定 Spec（Mode B）**：提供一个 JSON 格式的 spec 文件，跳过采访直接生成。适合已有明确规格或需要批量创建的场景。
+
+### 2.2 两阶段输出
+
+为保证安全性和可审查性，生成过程分为两个阶段：
+
+1. **Dry-run 阶段**：输出完整的文件创建/更新计划，列出所有将生成的文件路径和状态（CREATE / UPDATE），不写入任何文件。
+2. **生成阶段**：确认后才执行实际文件写入，并可选择运行校验（`basic` 或 `full`）验证生成结果的正确性。
+
+### 2.3 多层级校验
+
+生成完成后可执行校验，分为三个级别：
+
+| 校验级别 | 检查内容 | 适用场景 |
+|----------|----------|----------|
+| `none` | 不校验 | 快速原型 |
+| `basic` | 模块可导入 + 类已注册 + 测试文件存在 | 日常开发 |
+| `full` | `basic` + 运行冒烟测试 + 检查输出产物 | 正式提交前（推荐） |
+
+## 3. 工作流
+
+Skill 的完整执行流程如下：
+
+1. **加载参考规则**：读取内部约束文档（算子契约、注册规则、CLI 规范、验收清单等）。
+2. **选择模式**：根据用户输入选择交互式采访或直接 Spec 模式。
+3. **构建 Spec JSON**：将采集到的信息标准化为 spec JSON 对象。
+4. **Dry-run 预览**：展示文件计划，列出将创建或更新的文件。
+5. **确认写入策略**：展示覆盖策略，要求用户显式确认（`y/N`）。
+6. **生成文件**：执行实际的代码生成与写入。
+7. **运行校验**：按选定级别执行校验。
+8. **输出报告**：汇总生成的文件路径、校验结果和后续建议命令。
+
+## 4. 使用指南
+
+### 4.1 添加 Skill
+
+**前置条件**：需要已安装 Claude Code CLI。安装方法请参考 [Claude Code 官方文档](https://code.claude.com/docs/zh-CN) 或 [DataFlow-Skills README](https://github.com/haolpku/DataFlow-Skills)。
+
+克隆仓库并将 Skill 目录复制到 Claude Code 的 skills 文件夹中：
+
+```bash
+git clone https://github.com/haolpku/DataFlow-Skills.git
+
+# 项目级（仅当前项目可用）
+cp -r DataFlow-Skills/dataflow-operator-builder .claude/skills/dataflow-operator-builder
+
+# 或个人级（所有项目可用）
+cp -r DataFlow-Skills/dataflow-operator-builder ~/.claude/skills/dataflow-operator-builder
+```
+
+Claude Code 从 `.claude/skills/<skill-name>/SKILL.md` 自动发现 Skills。复制完成后，在 Claude Code 中即可使用 `/dataflow-operator-builder` 命令。
+
+### 4.2 方式 A：交互式采访
+
+直接在 Claude Code 中调用：
+
+```
+/dataflow-operator-builder
+```
+
+Agent 会通过 **两轮批量提问** 采集全部必要信息。每个问题都附带推荐选项和简短理由，你只需选择或填写即可。
+
+#### 第 1 轮：结构字段
+
+这一轮确定算子的"骨架"信息：
+
+| 问题 | 说明 | 推荐 | 映射到 Spec 字段 |
+|------|------|------|------------------|
+| 算子类型 | `generate` / `filter` / `refine` / `eval` | `generate`（最常见） | `operator_type` |
+| 算子标识 | 类名 + 模块文件名 | 按需填写 | `operator_class_name`, `operator_module_name` |
+| 仓库位置 | 包名 + 输出根目录 | 按需填写 | `package_name` + `--output-root` |
+| LLM 依赖 | 算子是否需要调用大模型 | 生成/精炼/评估类选 `yes` | `uses_llm` |
+| CLI 模块名 | 命令行入口的文件名 | `<module_name>_cli`（默认） | `cli_module_name` |
+
+#### 第 2 轮：实现细节
+
+这一轮确定运行时行为：
+
+| 问题 | 说明 | 推荐 | 映射到 Spec 字段 |
+|------|------|------|------------------|
+| 输入/输出字段 | dataframe 中的列名 | 显式指定 | `input_key`, `output_key` |
+| 描述语言 | `get_desc()` 的语言支持 | 中英双语 | 生成偏好 |
+| 额外 CLI 参数 | 是否需要自定义命令行参数 | 仅使用默认参数 | 扩展备注 |
+| 测试前缀 | 测试文件名前缀 | 与模块名一致 | `test_file_prefix` |
+| 覆盖策略 | 已有文件的处理方式 | `ask-each`（最安全） | `overwrite_strategy` |
+| 校验级别 | 生成后的校验强度 | `full`（推荐） | `validation_level` |
+
+两轮提问全部回答后，Agent 会自动构建 spec 并进入生成流程。仅在高影响字段缺失或存在冲突时才会进行追问。
+
+### 4.3 方式 B：直接指定 Spec
+
+如果你已经有明确的算子规格，可以跳过采访，直接传入 spec 文件：
+
+```
+/dataflow-operator-builder --spec path/to/spec.json --output-root path/to/repo
+```
+
+#### Spec JSON 字段说明
+
+**必填字段：**
+
+| 字段 | 类型 | 说明 | 示例 |
+|------|------|------|------|
+| `package_name` | string | 算子所在包名 | `"dataflow_ext_demo"` |
+| `operator_type` | string | 算子类型：`generate` / `filter` / `refine` / `eval` | `"filter"` |
+| `operator_class_name` | string | 算子类名（PascalCase） | `"DemoQualityFilter"` |
+| `operator_module_name` | string | 算子模块文件名（snake_case，不含 .py） | `"demo_quality_filter"` |
+| `input_key` | string | 输入数据列名 | `"raw_text"` |
+| `output_key` | string | 输出数据列名 | `"is_valid"` |
+| `uses_llm` | boolean | 是否需要 LLM 服务 | `false` |
+
+**可选字段：**
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `cli_module_name` | string | `<operator_module_name>_cli` | CLI 入口文件名 |
+| `test_file_prefix` | string | `<operator_module_name>` | 测试文件名前缀 |
+| `overwrite_strategy` | string | `"ask-each"` | 覆盖策略：`ask-each` / `overwrite-all` / `skip-existing` |
+| `validation_level` | string | `"full"` | 校验级别：`none` / `basic` / `full` |
+
+**完整示例：**
+
+```json
+{
+  "package_name": "dataflow_ext_demo",
+  "operator_type": "filter",
+  "operator_class_name": "DemoQualityFilter",
+  "operator_module_name": "demo_quality_filter",
+  "input_key": "raw_text",
+  "output_key": "is_valid",
+  "uses_llm": false,
+  "cli_module_name": "demo_quality_filter_cli",
+  "test_file_prefix": "demo_quality_filter",
+  "overwrite_strategy": "ask-each",
+  "validation_level": "full"
+}
+```
+
+### 4.4 查看输出
+
+#### 生成物一览
+
+| 生成物 | 路径 | 说明 |
+|--------|------|------|
+| 算子实现 | `<package>/<module_name>.py` | 类定义、`run()` 方法签名与 `OPERATOR_REGISTRY` 注册入口 |
+| CLI 入口 | `cli/<cli_module_name>.py` | 独立命令行批处理脚本，通过 `--input-file` / `--output-file` 调用 |
+| 单元测试 | `tests/unit/test_<prefix>.py` | 基础功能测试 |
+| 注册测试 | `tests/registry/test_<prefix>_registry.py` | 验证算子已正确注册到 `OPERATOR_REGISTRY` |
+| 冒烟测试 | `tests/smoke/test_<prefix>_smoke.py` | 端到端最小验收，使用临时 `FileStorage` 执行一次完整流程 |
+
+#### 生成的算子骨架
+
+所有生成的算子均遵循统一结构：
+
+```python
+from dataflow.operators.base import BaseOperator
+from dataflow.utils.storage import FileStorage
+
+class DemoQualityFilter(BaseOperator):
+    def __init__(self, threshold: float = 0.5):
+        self.threshold = threshold
+
+    def run(self, storage: FileStorage) -> FileStorage:
+        # 在此实现过滤逻辑
+        ...
+        return storage
+
+# 注册入口（由 Skill 自动生成）
+OPERATOR_REGISTRY.register("DemoQualityFilter", DemoQualityFilter)
+```
+
+**核心规则：**
+- 必须继承 `BaseOperator` 并实现 `run()` 方法
+- `run()` 接受并返回 `FileStorage` 实例，保持链式传递
+- 必须通过 `OPERATOR_REGISTRY` 完成注册，方可被 Pipeline 发现
+- CLI 入口通过 `--input-file` / `--output-file` 参数直接调用 `run()`，与 Pipeline 上下文解耦
+- `get_desc(lang)` 需支持中英双语（`zh` / `en`）
+
+#### 常用命令行参数
+
+| 参数 | 说明 | 可选值 |
+|------|------|--------|
+| `--dry-run` | 只展示文件计划，不写入任何文件 | — |
+| `--overwrite` | 控制已有文件的覆盖行为 | `ask-each`（逐一确认）/ `overwrite-all`（全部覆盖）/ `skip-existing`（跳过已有） |
+| `--validation-level` | 生成后的校验强度 | `none` / `basic` / `full` |
+| `--log-dir` | 运行日志存储路径 | 自定义路径 |
+| `--no-log` | 禁用运行日志 | — |
+
+## 5. 模式对比与选择建议
+
+| 对比维度 | 交互式采访（Mode A） | 直接 Spec（Mode B） |
+|----------|---------------------|---------------------|
+| 适合场景 | 首次使用、不确定参数 | 规格已明确、批量创建 |
+| 启动方式 | `/dataflow-operator-builder` | `/dataflow-operator-builder --spec spec.json` |
+| 上手难度 | 低，逐步引导 | 中，需了解 spec 格式 |
+| 灵活性 | 高，每个字段可单独调整 | 高，可编程化、脚本化 |
+| 效率 | 需要回答两轮问题 | 一次性提交，更快 |
+| 可复现性 | 较低，依赖对话过程 | 高，spec 文件可版本管理 |
+
+**选择建议：**
+- 如果你是第一次使用，或者不确定该填什么参数 → 选 **Mode A**
+- 如果你已经用过一次并保存了 spec，或需要批量生成多个算子 → 选 **Mode B**
+- 团队协作场景下，建议将 spec 文件纳入版本管理，统一使用 **Mode B**
+
+## 6. 注意事项与常见问题
+
+### 6.1 关键注意事项
+
+**注册必须完整**：生成的算子必须通过 `@OPERATOR_REGISTRY.register()` 装饰器完成注册，否则 Pipeline 无法发现该算子。如果注册测试失败，首先检查装饰器是否存在，以及模块是否被正确导入。
+
+**`storage.step()` 不可省略**：在 CLI 或 Pipeline 中调用算子时，必须传入 `storage=storage.step()` 而非原始 `storage`。省略 `step()` 会导致算子读取空数据或输出文件不在预期路径。
+
+**输入字段必须对齐**：`input_key` 必须是输入 dataframe 中已有的列名。如果运行时报 `KeyError`，检查 spec 中的 `input_key` 是否与实际数据列名匹配。
+
+**覆盖策略需确认**：在已有代码的仓库中使用时，务必在 dry-run 阶段检查文件列表。推荐使用 `ask-each` 策略，逐一确认每个文件是覆盖还是跳过。
+
+**校验级别建议 `full`**：`full` 级别会实际运行冒烟测试并检查输出产物，能在提交前发现大部分问题。仅在快速原型阶段才降级为 `none` 或 `basic`。
+
+### 6.2 常见问题
+
+**Q：生成后发现算子在 `OPERATOR_REGISTRY` 中找不到？**
+
+A：通常是以下原因之一：(1) 缺少 `@OPERATOR_REGISTRY.register()` 装饰器；(2) 算子模块没有被导入（检查 `__init__.py` 中的 `TYPE_CHECKING` 块）；(3) 类名拼写不一致。运行注册测试（`test_<prefix>_registry.py`）可以快速定位。
+
+**Q：冒烟测试通过但 CLI 运行失败？**
+
+A：检查 CLI 入口脚本中是否正确调用了 `storage.step()`，以及 `--input-file` 指向的文件是否存在且格式正确（JSONL）。CLI 和算子逻辑应保持解耦——如果 CLI 中混入了算子内部逻辑，说明职责划分有问题。
+
+**Q：对 LLM 响应的处理报错（空输出、格式异常）？**
+
+A：如果算子使用了 LLM（`uses_llm: true`），需要在 `run()` 中对模型返回值做防御性处理。生成的骨架中包含辅助方法（如 `_generate_text`、`_score_with_llm`），应在这些方法中对 `None`、空字符串、非预期格式做兜底处理。
+
+**Q：`--overwrite-all` 误覆盖了已有文件怎么办？**
+
+A：Skill 会在写入前展示文件计划并要求确认。如果确实误覆盖了，建议通过 `git checkout` 恢复。预防措施：(1) 始终先执行 `--dry-run`；(2) 使用 `ask-each` 或 `skip-existing` 策略。
diff --git a/docs/zh/notes/guide/skills/prompt-template-builder.md b/docs/zh/notes/guide/skills/prompt-template-builder.md
new file mode 100644
index 000000000..1e37b960d
--- /dev/null
+++ b/docs/zh/notes/guide/skills/prompt-template-builder.md
@@ -0,0 +1,294 @@
+---
+title: Prompt Template Builder — 提示词模板生成
+createTime: 2026/04/06 00:00:00
+permalink: /zh/guide/skills/prompt-template-builder/
+---
+
+视频教程：[DataFlow Prompt Template Builder](https://files.catbox.moe/d1pdr9.mp4)
+
+## 1. 概述
+
+**Prompt Template Builder (`prompt-template-builder`)** 是一个 Claude Code Skill，用于为 DataFlow 已有算子构建或修订 `prompt_template`。它解决的核心问题是"算子逻辑复用 + 提示词定制"——当你想用同一个算子处理不同的业务场景时，只需定制新的 prompt 模板即可，无需重写算子代码。
+
+该 Skill 能够：
+
+1. **算子接口对齐**：自动检查目标算子的构造参数和 `run()` 签名，确保生成的模板与算子契约完全一致。
+2. **模板类型自动选择**：根据目标算子类型，自动选择合适的模板风格（`DIYPromptABC` 或 `FormatStrPrompt`）。
+3. **两阶段可审计输出**：先输出决策 JSON（Stage 1），再输出完整产物（Stage 2），方便代码评审与回溯。
+4. **静态验收门控**：通过结构化验收清单完成质量检查，确保模板可交付。
+5. **定向改写**：如果结果不满意，支持接收反馈后进行定向修改并重新验收。
+
+## 2. 核心特性
+
+### 2.1 算子契约对齐
+
+这是该 Skill 最重要的特性。生成 prompt 模板前，Skill 会确认以下内容：
+
+- `build_prompt` 的参数签名是否与目标算子调用 `prompt_template.build_prompt(...)` 的方式一致
+- `prompt_template` 类型是否与算子期望的模板类型匹配
+- 模板中引用的所有变量是否都来自显式参数或常量（无未声明变量）
+
+如果目标算子要求使用 `DIYPromptABC` 但你误用了 `FormatStrPrompt`，Skill 会在 Stage 1 阶段就捕获这个问题。
+
+### 2.2 两阶段输出
+
+生成结果严格分为两个阶段：
+
+**Stage 1（决策 JSON）**——在动手写代码之前，先输出一份结构化的决策记录：
+
+- `prompt_template_type_aligned`：选用的模板类型及理由
+- `strategy`：模板设计策略（如"单字段生成，使用 system+user 双层提示词"）
+- `argument_mapping`：参数名到业务含义的映射
+- `output_contract`：输出格式约束（如"中文，不超过 80 字"）
+- `static_checks`：待验证的静态检查项列表
+
+**Stage 2（最终产物）**——包含五个部分：
+
+1. 模板/配置代码
+2. 集成代码片段（直接可复制到 Pipeline 中）
+3. 示例走查（正常样例 + 边界样例）
+4. 静态验收结果
+5. 剩余风险说明
+
+### 2.3 支持的模板类型
+
+| 模板类型 | 适用算子 | 特点 |
+|----------|----------|------|
+| `DIYPromptABC` | `PromptedGenerator`、`PromptedFilter`、`PromptedRefiner` 等 | 完全自定义 system/user prompt，支持字段插值，灵活度最高 |
+| `FormatStrPrompt` | `FormatStrPromptedGenerator` | 使用 Python f-string 风格模板，适合多字段拼接的固定格式场景 |
+
+**如何选择：**
+- 如果目标算子名以 `FormatStr` 开头（如 `FormatStrPromptedGenerator`），必须使用 `FormatStrPrompt`
+- 其他带 `Prompted` 前缀的算子（如 `PromptedGenerator`、`PromptedFilter`），使用 `DIYPromptABC`
+- 模板类型与算子的契约是强绑定的，**不可混用**
+
+## 3. 工作流
+
+Skill 的完整执行流程如下：
+
+1. **加载参考规则并解析输入**：读取内部参考文档（输入 schema、输出契约、验收清单等），解析用户提供的信息。
+2. **选择模式**：根据用户输入选择交互式采访或直接 Spec 模式。
+3. **解析算子契约**：确认目标算子 `OP_NAME` 的接口定义，确定应使用的模板类型。
+4. **构建模板草稿**：基于算子契约和用户需求，生成 prompt 模板代码。
+5. **输出 Stage 1 决策 JSON**：展示模板策略、参数映射、输出契约和静态检查项。
+6. **输出 Stage 2 完整产物**：输出模板代码、集成片段、示例走查和验收结果。
+7. **运行静态验收**：逐项核验 acceptance-checklist 中的检查项。
+8. **接收反馈并改写**（可选）：如果用户不满意，执行定向修改并重复 Stage 1/Stage 2。
+
+## 4. 使用指南
+
+### 4.1 添加 Skill
+
+**前置条件**：需要已安装 Claude Code CLI。安装方法请参考 [Claude Code 官方文档](https://code.claude.com/docs/zh-CN) 或 [DataFlow-Skills README](https://github.com/haolpku/DataFlow-Skills)。
+
+克隆仓库并将 Skill 目录复制到 Claude Code 的 skills 文件夹中：
+
+```bash
+git clone https://github.com/haolpku/DataFlow-Skills.git
+
+# 项目级（仅当前项目可用）
+cp -r DataFlow-Skills/prompt-template-builder .claude/skills/prompt-template-builder
+
+# 或个人级（所有项目可用）
+cp -r DataFlow-Skills/prompt-template-builder ~/.claude/skills/prompt-template-builder
+```
+
+Claude Code 从 `.claude/skills/<skill-name>/SKILL.md` 自动发现 Skills。复制完成后，在 Claude Code 中即可使用 `/prompt-template-builder` 命令。
+
+### 4.2 方式 A：交互式采访
+
+直接在 Claude Code 中调用：
+
+```
+/prompt-template-builder
+```
+
+Agent 会通过 **两轮批量提问** 采集全部必要信息。每个问题附带推荐选项和理由。
+
+#### 第 1 轮：结构字段
+
+确定"做什么"和"给谁做"：
+
+| 问题 | 说明 | 推荐 | 映射字段 |
+|------|------|------|----------|
+| 任务类型 | 新建 / 改写 / 迭代优化 | 新建（首版最稳） | `Task Mode` |
+| 目标算子 | 指定 `OP_NAME` | 指定单一算子（避免职责扩散） | `OP_NAME` |
+| 输出约束强度 | 强约束 / 中约束 / 轻约束 | 强约束 schema（提升可解析性） | `Expected Output` |
+| 风格与语气 | 专业简洁 / 教学解释型 / 严格审计型 | 专业简洁 | `Tone/Style` |
+| 约束来源 | 业务规则 / 样例 / 参考案例 | 业务规则优先 | `Constraints` |
+
+#### 第 2 轮：实现字段
+
+确定"怎么做"的细节：
+
+| 问题 | 说明 | 推荐 | 映射字段 |
+|------|------|------|----------|
+| `build_prompt` 入参 | 模板函数的参数列表 | 显式列出全部参数（避免变量漂移） | `Arguments` |
+| 输出格式细节 | JSON / 文本段落 / 列表 | JSON + 明确字段类型 | `Expected Output` |
+| 样例覆盖 | 正常 + 边界 / 仅正常 / 多边界 | 1 正常 + 1 边界 | `Sample Cases` |
+| 验收重点 | 接口一致性 / 文案质量 / 结构完整 | 接口一致性优先 | `Validation Focus` |
+
+两轮提问回答完毕后自动进入生成流程。仅在 `Target` 或 `OP_NAME` 缺失、参数与模板变量映射冲突、输出约束互相矛盾时才会追问。
+
+### 4.3 方式 B：直接指定 Spec
+
+如果你已经有明确的 prompt 需求，可以跳过采访：
+
+```
+/prompt-template-builder --spec path/to/prompt_spec.json
+```
+
+#### Spec JSON 字段说明
+
+**必填字段：**
+
+| 字段 | 说明 | 示例 |
+|------|------|------|
+| `Target` | 业务目标描述 | `"生成简洁的电商商品卖点"` |
+| `OP_NAME` | 目标算子类名 | `"PromptedGenerator"` |
+
+**建议补充字段：**
+
+| 字段 | 说明 | 示例 |
+|------|------|------|
+| `Constraints` | 业务约束条件 | `"语气专业；中文不超过80字"` |
+| `Expected Output` | 输出格式要求 | `"单行纯文本"` |
+| `Arguments` | prompt 参数列表 | `["product_name", "category"]` |
+| `Sample Cases` | 1-3 条输入/预期输出 | 见下方示例 |
+| `Tone/Style` | 语气风格 | `"专业简洁"` |
+| `Validation Focus` | 验收关注点 | `"接口一致性"` |
+
+**完整示例：**
+
+```json
+{
+  "Target": "生成简洁的电商商品卖点",
+  "OP_NAME": "PromptedGenerator",
+  "Constraints": "语气专业；中文不超过80字",
+  "Expected Output": "单行纯文本",
+  "Arguments": ["product_name", "category"],
+  "Sample Cases": [
+    {"product_name": "降噪耳机", "category": "电子产品"}
+  ],
+  "Tone/Style": "专业简洁",
+  "Validation Focus": "接口一致性"
+}
+```
+
+### 4.4 查看输出
+
+#### Stage 1：决策 JSON
+
+首先输出一份结构化的决策记录，供团队评审：
+
+```json
+{
+  "prompt_template_type_aligned": "DIYPromptABC",
+  "strategy": "单字段生成，使用 system+user 双层提示词",
+  "argument_mapping": {
+    "product_name": "商品名",
+    "category": "品类"
+  },
+  "output_contract": "中文，不超过 80 字，以卖点句式结尾",
+  "static_checks": [
+    "无多余占位符",
+    "语气符合专业定义",
+    "字数约束可在 Stage 2 walkthrough 中核验"
+  ]
+}
+```
+
+**核心规则：**
+- `prompt_template_type_aligned` 必须与目标算子的契约匹配
+- `static_checks` 中每一项必须在 Stage 2 的验收走查中逐一核验
+- `argument_mapping` 需与 `Arguments` 字段完全对应，不可遗漏
+
+#### Stage 2：最终产物
+
+以电商卖点生成为例，Stage 2 包含以下内容：
+
+**1. Prompt 设计代码：**
+
+```python
+system_prompt = (
+    "你是电商文案助手。"
+    "语气专业，最多80字，不使用夸张承诺。"
+    "只返回一行中文文本，不要 JSON，不要额外解释。"
+)
+user_prompt = "请基于输入内容生成一句电商卖点描述："
+```
+
+**2. 集成代码片段：**
+
+```python
+self.generator = PromptedGenerator(
+    llm_serving=self.llm_serving,
+    system_prompt=system_prompt,
+    user_prompt=user_prompt,
+)
+```
+
+**3. 示例走查：**
+- 正常样例：`降噪耳机/电子产品` → 输出一条 80 字内的专业卖点文案
+- 边界样例：`product_name` 为空 → 输出应提示信息不足，不生成虚假内容
+
+**4. 静态验收结果：**
+- `input_completeness` ✓
+- `operator_interface_aligned` ✓
+- `prompt_template_type_aligned` ✓
+- `no_invented_params` ✓
+- `output_schema_explicit` ✓
+
+**5. 剩余风险：** 无（本例为简单场景）
+
+## 5. 模式对比与选择建议
+
+| 对比维度 | 交互式采访（Mode A） | 直接 Spec（Mode B） |
+|----------|---------------------|---------------------|
+| 适合场景 | 首次使用、需求不明确 | 需求已明确、团队协作 |
+| 启动方式 | `/prompt-template-builder` | `/prompt-template-builder --spec spec.json` |
+| 上手难度 | 低，逐步引导 | 中，需了解 spec 格式 |
+| 效率 | 需要回答两轮问题 | 一次性提交，更快 |
+| 可复现性 | 较低 | 高，spec 可版本管理 |
+| 迭代改写 | 支持对话式反馈改写 | 修改 spec 后重新运行 |
+
+**选择建议：**
+- 如果你不确定该用哪个算子或怎么写约束 → 选 **Mode A**，Agent 会引导你一步步明确
+- 如果你已经有上次生成的 spec，只需微调后复用 → 选 **Mode B**
+- 团队内推广时，建议将 spec 文件纳入版本管理，统一用 **Mode B** 保持一致性
+
+## 6. 注意事项与常见问题
+
+### 6.1 关键注意事项
+
+**模板类型不可混用**：`prompt_template_type_aligned` 必须与目标算子的契约严格匹配。例如 `PromptedGenerator` 应使用 `DIYPromptABC`，而 `FormatStrPromptedGenerator` 必须使用 `FormatStrPrompt`。混用会导致运行时报类型错误或算子不识别模板。
+
+**`build_prompt` 参数必须对齐**：模板的 `build_prompt` 方法的参数签名必须与算子调用时传入的参数完全一致（名称、数量、类型）。不一致会导致 `TypeError`。Skill 会在 Stage 1 的 `argument_mapping` 中列出所有参数映射，请仔细确认。
+
+**输出格式必须明确**：不要在 prompt 中写"尽量输出 JSON"这样的模糊描述。必须明确定义输出的字段名、类型、取值范围。模糊的输出要求会导致模型输出不稳定，难以解析。
+
+**模板变量不可"凭空出现"**：`build_prompt` 中引用的变量必须来自函数参数或类常量。如果模板中出现了未在参数列表中声明的变量，格式化时会报 `NameError` 或产生空值。
+
+**v1 为静态验收**：当前版本使用"静态验收 + 示例走查"闭环，不会自动运行子进程测试。这意味着验收结果是基于代码结构检查而非运行时行为。如果需要运行时验证，需手动将生成的代码集成到 Pipeline 中执行。
+
+### 6.2 常见问题
+
+**Q：运行时报 `TypeError`，提示 `build_prompt` 参数不匹配？**
+
+A：这是最常见的问题。根因是 `build_prompt` 的参数签名与算子调用点不一致。解决方法：(1) 确认目标算子的源码或文档中 `prompt_template.build_prompt(...)` 的调用方式；(2) 检查 Stage 1 中的 `argument_mapping` 是否完整覆盖了所有参数；(3) 使用 Skill 的定向改写功能修正签名。
+
+**Q：模型输出不稳定，格式总是漂移？**
+
+A：通常是 prompt 中的输出格式约束不够严格。检查以下几点：(1) 是否在 prompt 中明确定义了输出 schema（字段名、类型）；(2) 是否使用了"只返回 XXX，不要额外解释"之类的强约束语句；(3) 是否在 prompt 末尾给出了预期输出的格式示例。
+
+**Q：生成的模板代码看似正确，但算子不识别？**
+
+A：检查模板类型是否与算子匹配。如果使用了 `DIYPromptABC` 但目标算子期望 `FormatStrPrompt`（或反之），算子会忽略或报错。查看 Stage 1 中的 `prompt_template_type_aligned` 字段确认匹配关系。
+
+**Q：Stage 1 输出后想调整策略，怎么做？**
+
+A：直接向 Agent 反馈你的修改意见。Skill 支持接收反馈后进行定向改写——它会保留未变更的部分，只修改你指出的问题，然后重新输出 Stage 1 和 Stage 2 并重新运行静态验收。
+
+**Q：一个业务需求需要多个 prompt 类，该拆分还是合并？**
+
+A：原则上应尽量用一个模板类完成。仅在语义职责显著不同时才拆分（例如一个用于生成、一个用于过滤）。如果 Stage 1 的策略解释无法给出拆分的必要性理由，说明应该合并。过度拆分会增加维护成本。