---
name: x-ipe-meta-skill-creator
description: Guide for creating effective X-IPE skills with templates, testing, and validation. Use when creating a new skill or updating an existing skill for the X-IPE framework. Triggers on requests like "create skill", "new skill", "add task-based skill", "update skill".
---

# X-IPE Skill Creator

## Purpose

Guide for creating effective X-IPE skills by:
1. Identifying skill type and selecting appropriate template
2. Gathering concrete usage examples
3. Creating skill with sub-agent DAG workflow
4. Validating against acceptance criteria
5. Merging to production or iterating on failures

---

## About X-IPE Skills

Skills are modular, self-contained packages that extend AI Agent capabilities by providing specialized knowledge, workflows, and tools.

### What Skills Provide

1. **Specialized workflows** - Multi-step procedures for specific domains
2. **Tool integrations** - Instructions for working with specific file formats or APIs
3. **Domain expertise** - Project-specific knowledge, schemas, business logic
4. **Bundled resources** - Templates, references, and scripts for complex tasks

### Skill Types

| Type | Purpose | Naming Convention | SKILL.md Template | skill-meta.md Template |
|------|---------|-------------------|-------------------|------------------------|
| x-ipe-task-based | Belong to end-to-end project lifecycle workflows | `x-ipe-task-based-{name}` | [x-ipe-task-based.md](.github/skills/x-ipe-meta-skill-creator/templates/x-ipe-task-based.md) | [skill-meta-x-ipe-task-based.md](.github/skills/x-ipe-meta-skill-creator/templates/skill-meta-x-ipe-task-based.md) |
| x-ipe-task-category | Category orchestration when related tasks complete | `x-ipe+{category}+{name}` (`all` for cross-category) | [x-ipe-workflow-orchestration.md](.github/skills/x-ipe-meta-skill-creator/templates/x-ipe-workflow-orchestration.md) | [skill-meta-x-ipe-task-category.md](.github/skills/x-ipe-meta-skill-creator/templates/skill-meta-x-ipe-task-category.md) |
| x-ipe-tool | Utility functions and tool integrations | `x-ipe-tool-{name}` | [x-ipe-tool.md](.github/skills/x-ipe-meta-skill-creator/templates/x-ipe-tool.md) | [skill-meta-x-ipe-tool.md](.github/skills/x-ipe-meta-skill-creator/templates/skill-meta-x-ipe-tool.md) |
| x-ipe-workflow-orchestration | Multi-skill coordination | `x-ipe-workflow-{name}` | [x-ipe-workflow-orchestration.md](.github/skills/x-ipe-meta-skill-creator/templates/x-ipe-workflow-orchestration.md) | [skill-meta-x-ipe-task-based.md](.github/skills/x-ipe-meta-skill-creator/templates/skill-meta-x-ipe-task-based.md) |
| x-ipe-meta | Creates/manages skills | `x-ipe-meta-{name}` | [x-ipe-meta.md](.github/skills/x-ipe-meta-skill-creator/templates/x-ipe-meta.md) | [skill-meta-x-ipe-meta.md](.github/skills/x-ipe-meta-skill-creator/templates/skill-meta-x-ipe-meta.md) |
| x-ipe-dao | Human representative skills (道 backbone as CORE) | `x-ipe-dao-{name}` | [x-ipe-dao.md](.github/skills/x-ipe-meta-skill-creator/templates/x-ipe-dao.md) | [skill-meta-x-ipe-dao.md](.github/skills/x-ipe-meta-skill-creator/templates/skill-meta-x-ipe-dao.md) |

---

## Important Notes

BLOCKING: **NEVER directly edit files in `.github/skills/{skill-name}/`.**
All skill modifications MUST go through the candidate workflow:
1. Edit in `x-ipe-docs/skill-meta/{skill-name}/candidate/`
2. Validate via reflection + tests (Rounds 2–3)
3. Merge candidate → `.github/skills/{skill-name}/` only after validation

BLOCKING: Read [skill-general-guidelines-v2.md](.github/skills/x-ipe-meta-skill-creator/references/skill-general-guidelines-v2.md) for core principles and patterns before creating skills.

CRITICAL: SKILL.md body must stay under 500 lines. Move examples to references/.

CRITICAL: DoR ≤ 5 checkpoints, DoD ≤ 10 checkpoints. If over limit, keep only the most critical checks and merge related ones.

MANDATORY: All 6 skill types have complete templates in the templates/ folder.

CRITICAL: Each step MUST have exactly ONE `<action>` block containing ALL actions. Do NOT split actions into separate blocks (e.g., `<branch>`). Conditional logic (IF/THEN/ELSE) belongs inline within the `<action>` numbered list.

CRITICAL: Before populating skill content, check `x-ipe-docs/skill-meta/{related-skill}/x-ipe-meta-lesson-learned.md` for lessons from similar skills. Apply relevant lessons to avoid repeating known mistakes. Reference: [12. reference-production-patterns.md](.github/skills/x-ipe-meta-skill-creator/references/12.%20reference-production-patterns.md)

---

## Input Parameters

```yaml
input:
  skill_name: "{skill-name}"  # lowercase, hyphens, 1-64 chars
  skill_type: x-ipe-task-based | x-ipe-task-category | x-ipe-tool | x-ipe-workflow-orchestration | x-ipe-meta | x-ipe-dao
  user_request: "{description of what skill should do}"
  examples: []  # Concrete usage examples (optional)
```

---

## Definition of Ready

```xml
<definition_of_ready>
  <checkpoint required="true">
    <name>Skill Type Identified</name>
    <verification>One of: x-ipe-task-based, x-ipe-task-category, x-ipe-tool, x-ipe-workflow-orchestration, x-ipe-meta, x-ipe-dao</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Skill Name Compliant</name>
    <verification>Matches naming convention: x-ipe-{type}-{name} (lowercase, hyphens only, 1-64 chars)</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>User Request Clear</name>
    <verification>Clear description of what skill should do</verification>
  </checkpoint>
  <checkpoint required="recommended">
    <name>Concrete Examples Gathered</name>
    <verification>At least 2 usage scenarios documented</verification>
  </checkpoint>
  <checkpoint required="recommended">
    <name>Skill Meta Folder Exist</name>
    <verification>Folder x-ipe-docs/skill-meta/ exists with necessary files</verification>
  </checkpoint>
</definition_of_ready>
```

---

## Execution Flow

| Step | Name | Action | Gate |
|------|------|--------|------|
| 1 | Identify Skill Type | Determine type, select template | type selected |
| 2 | Gather Examples | Collect usage scenarios | >= 2 examples |
| 3 | Plan Resources | Identify scripts/references/templates | resources planned |
| 4 | Round 1: Meta + Draft | Create skill-meta.md + candidate/ (sub-agent 1) | both complete |
| 5 | Round 2: Reflect + Tests | Reflect on candidate + generate tests (sub-agent 2) | both complete |
| 6 | Round 3: Run Tests | Execute tests in sandbox (sub-agent 3) | tests executed |
| 7 | Round 4: Evaluate | Evaluate results (sub-agent 4) | evaluation complete |
| 8 | Merge/Iterate | Merge if pass, iterate if fail | decision made |
| 9 | Cross-References | Validate external references | all valid |

---

## Execution Procedure

```xml
<procedure name="skill-creation">
  <!-- CRITICAL: Both DoR/DoD check elements below are MANDATORY -->
  <execute_dor_checks_before_starting/>
  <schedule_dod_checks_with_sub_agent_before_starting/>

  <step_1>
    <name>Identify Skill Type</name>
    <action>
      1. Determine skill type based on purpose
      2. Select corresponding SKILL.md template from templates/
      3. Select corresponding skill-meta.md template from templates/
      4. IF Belong to end-to-end project lifecycle workflows → x-ipe-task-based:
         - SKILL.md: templates/x-ipe-task-based.md
         - skill-meta.md: templates/skill-meta-x-ipe-task-based.md
      5. IF Utility functions or integrations → x-ipe-tool:
         - SKILL.md: templates/x-ipe-tool.md
         - skill-meta.md: templates/skill-meta-x-ipe-tool.md
      6. IF Orchestrates other skills → x-ipe-workflow-orchestration:
         - SKILL.md: templates/x-ipe-workflow-orchestration.md
         - skill-meta.md: templates/skill-meta-x-ipe-task-based.md (same structure)
      7. IF Creates/manages skills → x-ipe-meta:
         - SKILL.md: templates/x-ipe-meta.md
         - skill-meta.md: templates/skill-meta-x-ipe-meta.md
      8. IF Human representative skill (道 backbone as CORE) → x-ipe-dao:
         - SKILL.md: templates/x-ipe-dao.md
         - skill-meta.md: templates/skill-meta-x-ipe-dao.md
      9. IF Category orchestration → x-ipe-task-category:
         - SKILL.md: templates/x-ipe-workflow-orchestration.md
         - skill-meta.md: templates/skill-meta-x-ipe-task-category.md
    </action>
    <constraints>
      - BLOCKING: Must select exactly one skill type
      - BLOCKING: Must identify both SKILL.md and skill-meta.md templates
    </constraints>
    <success_criteria>
      - Skill type identified
      - SKILL.md template path determined
      - skill-meta.md template path determined
    </success_criteria>
    <output>skill_type, skill_template_path, skill_meta_template_path</output>
  </step_1>

  <step_2>
    <name>Gather Concrete Examples</name>
    <action>
      1. Ask user for functionality requirements
      2. Collect trigger phrase examples
      3. Document expected outputs
    </action>
    <constraints>
      - CRITICAL: Skip only if patterns already clearly understood
    </constraints>
    <success_criteria>
      - At least 2 usage scenarios documented
      - Trigger patterns identified
    </success_criteria>
    <output>examples[], trigger_patterns[]</output>
  </step_2>

  <step_3>
    <name>Plan Bundled Resources</name>
    <action>
      1. Analyze examples for reusable patterns
      2. Identify which resource types needed:
         - scripts/: Same code rewritten repeatedly
         - references/: Documentation agent should reference
         - templates/: Skill produces standardized documents
    </action>
    <success_criteria>
      - Resource requirements documented
    </success_criteria>
    <output>resources_plan[]</output>
  </step_3>

  <step_4>
    <name>Round 1: Create Meta + Draft</name>
    <requires>skill_type, skill_template_path, skill_meta_template_path, examples[], resources_plan[]</requires>
    <action>
      1. Load skill-meta template from {skill_meta_template_path}
      2. Create skill-meta.md under x-ipe-docs/skill-meta/{skill-name}/ by filling template
      3. Load SKILL.md template from {skill_template_path}
      4. Create candidate/ under x-ipe-docs/skill-meta/{skill-name}/ with full skill structure
      5. Create ALL bundled resources from resources_plan[] inside candidate/:
         - candidate/references/ — all reference files
         - candidate/scripts/ — all script files
         - candidate/templates/ — all template files
    </action>
    <constraints>
      - BLOCKING: Both outputs must complete before Round 2
      - BLOCKING: skill-meta.md MUST be created from template, not from scratch
      - BLOCKING: SKILL.md MUST be created from template, not from scratch
      - BLOCKING: ALL bundled resources (references/, scripts/, templates/) MUST be created inside candidate/ — never directly in .github/skills/{skill-name}/
      - MANDATORY: All internal markdown links in generated skill files MUST use full project-root-relative paths (e.g., `x-ipe-docs/requirements/EPIC-XXX/specification.md`, `.github/skills/x-ipe-task-based-XXX/SKILL.md`). Do NOT use relative paths like `../` or `./`.
    </constraints>
    <success_criteria>
      - skill-meta.md exists (created from {skill_meta_template_path})
      - candidate/ folder with SKILL.md exists (created from {skill_template_path})
      - All planned resources from resources_plan[] exist inside candidate/
    </success_criteria>
    <output>skill-meta.md, candidate/</output>
  </step_4>

  <step_5>
    <name>Round 2: Reflect + Test Cases</name>
    <requires>skill-meta.md, candidate/</requires>
    <action>
      1. Reflect on candidate against skill-meta using this checklist:
         a. Does skill load all referenced tool skills explicitly? (not guess behavior)
         b. Does it read project config (tools.json/.x-ipe.yaml) when gating optional features?
         c. Does it document anti-patterns for common failure modes? (if 3+ steps)
         d. Does it include known limitations with workarounds? (if external dependencies)
         e. Are output naming conventions defined? (if skill produces files)
         f. Were lessons from related skills consulted and applied?
      2. Generate test cases from acceptance criteria
    </action>
    <success_criteria>
      - Candidate refined based on reflection
      - test-cases.yaml created
    </success_criteria>
    <output>candidate/, test-cases.yaml</output>
  </step_5>

  <step_6>
    <name>Round 3: Run Tests</name>
    <requires>test-cases.yaml</requires>
    <action>
      1. Execute tests in sandbox environment
      2. Save outputs to sandbox/ folder
    </action>
    <success_criteria>
      - All tests executed
      - Execution log recorded
    </success_criteria>
    <output>sandbox/{outputs}, execution-log.yaml</output>
  </step_6>

  <step_7>
    <name>Round 4: Evaluate Results</name>
    <requires>sandbox/{outputs}, execution-log.yaml</requires>
    <action>
      1. Evaluate sandbox outputs against expectations
      2. Use self_check for structural/content validation
      3. Use judge_agent for quality scoring with rubric
    </action>
    <success_criteria>
      - Evaluation report generated
      - Pass/fail determination made
    </success_criteria>
    <output>evaluation-report.yaml</output>
  </step_7>

  <step_8>
    <name>Merge or Iterate</name>
    <requires>evaluation-report.yaml</requires>
    <action>
      1. Check evaluation results
      2. IF must_pass_rate == 100% AND should_pass_rate >= 80%:
         - Validate candidate/ completeness: verify all files referenced by candidate/SKILL.md exist inside candidate/ (references/, scripts/, templates/)
         - IF missing files found: add them to candidate/ before merging
         - cp -r candidate/* .github/skills/{skill-name}/
         - Update skill-version-history.md
         - Proceed to Step 9
      3. IF tests failed AND iteration_count < 3:
         - Update candidate, re-run from Round 2
      4. IF tests failed AND iteration_count >= 3:
         - Escalate to human
    </action>
    <constraints>
      - BLOCKING: Pre-merge validation must confirm candidate/ contains ALL files that will exist in production — no direct writes to .github/skills/{skill-name}/ after merge
    </constraints>
    <success_criteria>
      - Skill merged OR iteration documented
    </success_criteria>
    <output>merge_status</output>
  </step_8>

  <step_9>
    <name>Validate Cross-References</name>
    <requires>merge_status == merged</requires>
    <action>
      1. Verify skill's Output Result YAML declares: category, next_task_based_skill, require_human_review (x-ipe-task-based only)
      2. Verify skill description contains trigger keywords for auto-discovery (x-ipe-task-based only)
      3. Verify bidirectional references
      4. Verify Input Initialization subsection exists under Input Parameters with <input_init> XML block
    </action>
    <constraints>
      - MANDATORY: Task-based skills must declare category, next_task_based_skill, require_human_review in Output Result for auto-discovery
    </constraints>
    <success_criteria>
      - Cross-references validated
    </success_criteria>
    <output>cross_references_valid</output>
  </step_9>

  <sub-agent-planning>
    <!-- Constraint: One step = one sub-agent; one sub-agent = many steps -->
    <sub_agent_1>
      <sub_agent_definition>
        <role>Meta & Draft Creator</role>
        <prompt>Load skill-meta template from {skill_meta_template_path} and SKILL.md template from {skill_template_path}. Fill both with skill-specific content. Output: x-ipe-docs/skill-meta/{skill-name}/skill-meta.md and x-ipe-docs/skill-meta/{skill-name}/candidate/</prompt>
      </sub_agent_definition>
      <workflow_step_reference>step_4</workflow_step_reference>
    </sub_agent_1>
    <sub_agent_2>
      <sub_agent_definition>
        <role>Reflector & Test Generator</role>
        <prompt>Review candidate against skill-meta, identify gaps, suggest improvements. Then generate test-cases.yaml from acceptance criteria in skill-meta.md</prompt>
      </sub_agent_definition>
      <workflow_step_reference>step_5</workflow_step_reference>
      <starting_condition>
        - "START after sub_agent_1 completes"
      </starting_condition>
    </sub_agent_2>
    <sub_agent_3>
      <sub_agent_definition>
        <role>Test Runner</role>
        <prompt>Execute test cases in sandbox, record outputs and execution log</prompt>
      </sub_agent_definition>
      <workflow_step_reference>step_6</workflow_step_reference>
      <starting_condition>
        - "START after sub_agent_2 completes"
      </starting_condition>
    </sub_agent_3>
    <sub_agent_4>
      <sub_agent_definition>
        <role>Evaluator</role>
        <prompt>Evaluate sandbox outputs against expectations, generate evaluation-report.yaml</prompt>
      </sub_agent_definition>
      <workflow_step_reference>step_7</workflow_step_reference>
      <starting_condition>
        - "START after sub_agent_3 completes"
      </starting_condition>
    </sub_agent_4>
  </sub-agent-planning>

</procedure>
```

---

## Output Result

```yaml
task_completion_output:
  category: standalone
  status: completed | blocked
  next_task_based_skill: null
  require_human_review: yes
  task_output_links:
    - ".github/skills/{skill-name}/SKILL.md"
    - "x-ipe-docs/skill-meta/{skill-name}/skill-meta.md"
  # Dynamic attributes
  skill_name: "{skill-name}"
  skill_type: "{skill_type}"
  test_pass_rate: "{percentage}"
```

---

## Definition of Done

CRITICAL: Use a sub-agent to validate DoD checkpoints independently.

```xml
<definition_of_done>
  <checkpoint required="true">
    <name>Planning Complete</name>
    <verification>skill_type, template_path, examples[], resources_plan[] defined; skill-meta.md created from template</verification>
    <step_output>skill_type, template_path, examples[], trigger_patterns[], resources_plan[]</step_output>
  </checkpoint>
  <checkpoint required="true">
    <name>Candidate Created</name>
    <verification>candidate/SKILL.md + all bundled resources (references/, scripts/, templates/) exist in candidate/</verification>
    <step_output>skill-meta.md, candidate/</step_output>
  </checkpoint>
  <checkpoint required="true">
    <name>Validation Passed</name>
    <verification>test-cases.yaml created, sandbox executed, evaluation passed (must_pass=100%, should_pass>=80%)</verification>
    <step_output>candidate/, test-cases.yaml, sandbox/{outputs}, execution-log.yaml, evaluation-report.yaml</step_output>
  </checkpoint>
  <checkpoint required="true">
    <name>Merged with Parity</name>
    <verification>Skill merged to .github/skills/{skill-name}/ AND every production file has corresponding candidate/ file</verification>
    <step_output>merge_status</step_output>
  </checkpoint>
  <checkpoint required="true">
    <name>SKILL.md Structure Valid</name>
    <verification>Frontmatter valid (name + triggers), section order correct, keywords used (not emoji), line count under 500</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>DoR/DoD Within Limits</name>
    <verification>Created skill has DoR at most 5 and DoD at most 10 checkpoints</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Step Outputs Covered</name>
    <verification>Every step output in created skill has a corresponding DoD checkpoint</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Cross-References Valid</name>
    <verification>Auto-discovery fields in Output Result (if task-based), Input Initialization present, bidirectional refs verified</verification>
    <step_output>cross_references_valid</step_output>
  </checkpoint>
  <checkpoint required="recommended">
    <name>Input Initialization Present</name>
    <verification>Skills with non-trivial input resolution have Input Initialization subsection with input_init block</verification>
  </checkpoint>
  <checkpoint required="recommended">
    <name>Examples Documented</name>
    <verification>references/examples.md exists with concrete usage scenarios</verification>
  </checkpoint>
</definition_of_done>
```

---

## Templates

| Template | Purpose |
|----------|---------|
| [x-ipe-task-based.md](.github/skills/x-ipe-meta-skill-creator/templates/x-ipe-task-based.md) | SKILL.md for task-based skills |
| [x-ipe-tool.md](.github/skills/x-ipe-meta-skill-creator/templates/x-ipe-tool.md) | SKILL.md for tool skills |
| [x-ipe-workflow-orchestration.md](.github/skills/x-ipe-meta-skill-creator/templates/x-ipe-workflow-orchestration.md) | SKILL.md for workflow/task-category skills |
| [x-ipe-meta.md](.github/skills/x-ipe-meta-skill-creator/templates/x-ipe-meta.md) | SKILL.md for meta skills |
| [x-ipe-dao.md](.github/skills/x-ipe-meta-skill-creator/templates/x-ipe-dao.md) | SKILL.md for human representative skills (x-ipe-dao type) |
| [skill-meta-x-ipe-task-based.md](.github/skills/x-ipe-meta-skill-creator/templates/skill-meta-x-ipe-task-based.md) | skill-meta for task-based/workflow skills |
| [skill-meta-x-ipe-tool.md](.github/skills/x-ipe-meta-skill-creator/templates/skill-meta-x-ipe-tool.md) | skill-meta for tool skills |
| [skill-meta-x-ipe-task-category.md](.github/skills/x-ipe-meta-skill-creator/templates/skill-meta-x-ipe-task-category.md) | skill-meta for task-category skills |
| [skill-meta-x-ipe-meta.md](.github/skills/x-ipe-meta-skill-creator/templates/skill-meta-x-ipe-meta.md) | skill-meta for meta skills |
| [skill-meta-x-ipe-dao.md](.github/skills/x-ipe-meta-skill-creator/templates/skill-meta-x-ipe-dao.md) | skill-meta for human representative skills (x-ipe-dao type) |

BLOCKING: Always use the appropriate template. Never create SKILL.md or skill-meta.md from scratch.

---

## References

| File | Purpose |
|------|---------|
| [skill-general-guidelines-v2.md](.github/skills/x-ipe-meta-skill-creator/references/skill-general-guidelines-v2.md) | Core principles, patterns, standards |
| [2. reference-section-order.md](.github/skills/x-ipe-meta-skill-creator/references/2. reference-section-order.md) | Section ordering guide |
| [3-6. example-*.md](.github/skills/x-ipe-meta-skill-creator/references) | Workflow pattern examples (step-based, function-based) |
| [7-10. example-*.md](.github/skills/x-ipe-meta-skill-creator/references) | Task IO, structured summary, DoR/DoD, gate conditions |
| [11. reference-quality-standards.md](.github/skills/x-ipe-meta-skill-creator/references/11. reference-quality-standards.md) | Quality standards |
| [examples.md](.github/skills/x-ipe-meta-skill-creator/references/examples.md) | Concrete execution examples |
| [12. reference-production-patterns.md](.github/skills/x-ipe-meta-skill-creator/references/12.%20reference-production-patterns.md) | Production patterns: lessons integration, tool loading, config gating, anti-patterns, limitations |

---

## Related Skills

| Skill | Purpose |
|-------|---------|
| `x-ipe-meta-lesson-learned` | Capture issues and feedback after skill execution |
