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

Important Notes

BLOCKING: Read 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/.

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

Input Parameters

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
  user_request: "{description of what skill should do}"
  examples: []  # Concrete usage examples (optional)

Definition of Ready

<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</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

Execution Procedure

<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 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
    </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
    </constraints>
    <success_criteria>
      - skill-meta.md exists (created from {skill_meta_template_path})
      - candidate/ folder with SKILL.md exists (created from {skill_template_path})
    </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
      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%:
         - 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>
    <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. Check copilot-instructions.md registration (x-ipe-task-based only)
      2. Check x-ipe-workflow-task-execution registration (x-ipe-task-based only)
      3. Verify bidirectional references
    </action>
    <constraints>
      - MANDATORY: Task type skills must be registered in copilot-instructions.md
    </constraints>
    <success_criteria>
      - Cross-references validated
    </success_criteria>
    <output>cross_references_valid</output>
  </step_9>

  <sub-agent-planning>
    <sub_agent_1>
      <sub_agent_definition>
        <role>Meta Creator</role>
        <prompt>Load skill-meta template from {skill_meta_template_path}, fill with skill-specific content (purpose, acceptance criteria, test scenarios). Output: x-ipe-docs/skill-meta/{skill-name}/skill-meta.md</prompt>
      </sub_agent_definition>
      <workflow_step_reference>step_4</workflow_step_reference>
    </sub_agent_1>
    <sub_agent_2>
      <sub_agent_definition>
        <role>Draft Creator</role>
        <prompt>Load SKILL.md template from {skill_template_path}, fill with skill-specific content following guidelines. Output: x-ipe-docs/skill-meta/{skill-name}/candidate/</prompt>
      </sub_agent_definition>
      <workflow_step_reference>step_4</workflow_step_reference>
    </sub_agent_2>
    <sub_agent_3>
      <sub_agent_definition>
        <role>Reflector</role>
        <prompt>Review candidate against skill-meta, identify gaps, suggest improvements</prompt>
      </sub_agent_definition>
      <workflow_step_reference>step_5</workflow_step_reference>
      <starting_condition>
        - "START after sub_agent_1 and sub_agent_2 complete"
      </starting_condition>
    </sub_agent_3>
    <sub_agent_4>
      <sub_agent_definition>
        <role>Test Generator</role>
        <prompt>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 and sub_agent_2 complete"
      </starting_condition>
    </sub_agent_4>
    <sub_agent_5>
      <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_3 and sub_agent_4 complete"
      </starting_condition>
    </sub_agent_5>
    <sub_agent_6>
      <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_5 completes"
      </starting_condition>
    </sub_agent_6>
  </sub-agent-planning>

</procedure>

Output Result

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.

<definition_of_done>
  <!-- Step Output Verification -->
  <checkpoint required="true">
    <name>Step 1-3 Outputs Complete</name>
    <verification>skill_type, template_path, examples[], resources_plan[] defined</verification>
    <step_output>skill_type, template_path, examples[], trigger_patterns[], resources_plan[]</step_output>
  </checkpoint>
  <checkpoint required="true">
    <name>Step 4 Outputs Complete</name>
    <verification>skill-meta.md and candidate/ folder created</verification>
    <step_output>skill-meta.md, candidate/</step_output>
  </checkpoint>
  <checkpoint required="true">
    <name>Step 5 Outputs Complete</name>
    <verification>test-cases.yaml exists in x-ipe-docs/skill-meta/{skill-name}/</verification>
    <step_output>candidate/, test-cases.yaml</step_output>
  </checkpoint>
  <checkpoint required="true">
    <name>Step 6 Outputs Complete</name>
    <verification>sandbox/ folder with test outputs and execution-log.yaml exist</verification>
    <step_output>sandbox/{outputs}, execution-log.yaml</step_output>
  </checkpoint>
  <checkpoint required="true">
    <name>Step 7 Outputs Complete</name>
    <verification>evaluation-report.yaml exists with pass/fail results</verification>
    <step_output>evaluation-report.yaml</step_output>
  </checkpoint>
  <checkpoint required="true">
    <name>Step 8 Output Complete</name>
    <verification>Skill merged to .github/skills/{skill-name}/ or iteration documented</verification>
    <step_output>merge_status</step_output>
  </checkpoint>
  <checkpoint required="true">
    <name>Step 9 Output Complete</name>
    <verification>Cross-references validated (copilot-instructions.md if x-ipe-task-based)</verification>
    <step_output>cross_references_valid</step_output>
  </checkpoint>
  
  <!-- Quality Verification -->
  <checkpoint required="true">
    <name>Candidate SKILL.md Created</name>
    <verification>File exists at x-ipe-docs/skill-meta/{skill-name}/candidate/SKILL.md</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>SKILL.md Created</name>
    <verification>File exists at .github/skills/{skill-name}/SKILL.md</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Frontmatter Valid</name>
    <verification>name (1-64 chars) and description (includes triggers)</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Section Order Correct</name>
    <verification>Follows cognitive flow per skill type</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Line Count Under Limit</name>
    <verification>SKILL.md < 500 lines</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Keywords Used</name>
    <verification>Uses BLOCKING/CRITICAL/MANDATORY (not emoji)</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Step Outputs Covered in Created Skill</name>
    <verification>Every step output in created skill has corresponding DoD checkpoint</verification>
  </checkpoint>
  <checkpoint required="true">
    <name>Cross-References Valid</name>
    <verification>Registered in copilot-instructions.md (if x-ipe-task-based)</verification>
  </checkpoint>
</definition_of_done>

Templates

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

References

Example

See references/examples.md for concrete execution examples.

Related Skills