| 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:
- Identifying skill type and selecting appropriate template
- Gathering concrete usage examples
- Creating skill with sub-agent DAG workflow
- Validating against acceptance criteria
- 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
- Specialized workflows - Multi-step procedures for specific domains
- Tool integrations - Instructions for working with specific file formats or APIs
- Domain expertise - Project-specific knowledge, schemas, business logic
- Bundled resources - Templates, references, and scripts for complex tasks
Skill Types
See skill-type-comparison.md for detailed comparison of all skill types.
Important Notes
BLOCKING: NEVER directly edit files in .github/skills/{skill-name}/.
All skill modifications MUST go through the candidate workflow:
- Edit in
x-ipe-docs/skill-meta/{skill-name}/candidate/
- Validate via reflection + tests (Rounds 2–3)
- Merge candidate →
.github/skills/{skill-name}/ only after validation
BLOCKING: Read skill-general-guidelines-v2.md for core principles and patterns before creating skills.
CRITICAL: SKILL.md body must stay under 500 lines (600 for x-ipe-tool type). Move examples to references/. DoR ≤ 5 checkpoints, DoD ≤ 10 checkpoints — if over limit, merge related checks.
MANDATORY: All 8 skill types have complete templates in the templates/ folder. See skill-type-comparison.md for details.
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
Input Parameters
input:
skill_name: "{skill-name}"
skill_type: x-ipe-task-based | x-ipe-task-category | x-ipe-tool | x-ipe-workflow-orchestration | x-ipe-meta | x-ipe-knowledge | x-ipe-assistant | x-ipe-dao
user_request: "{description of what skill should do}"
examples: []
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, x-ipe-knowledge, x-ipe-assistant, 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</>
Skill Meta Folder Exist
Folder x-ipe-docs/skill-meta/ exists with necessary files
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 | Self-Critique Scope | AI validates scope; escalates only specific ambiguities | scope validated |
| 5 | Round 1: Meta + Draft | Create skill-meta.md + candidate/ (sub-agent 1) | both complete |
| 6 | Round 2: Reflect + Tests | Reflect on candidate + generate tests (sub-agent 2) | both complete |
| 7 | Round 3: Run Tests | Execute tests in sandbox (sub-agent 3) | tests executed |
| 8 | Round 4: Evaluate | Evaluate results (sub-agent 4) | evaluation complete |
| 9 | Merge/Iterate | Merge if pass, iterate if fail | decision made |
| 10 | Cross-References | Validate external references | all valid |
Execution Procedure
<procedure name="skill-creation">
<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 → x-ipe-dao: ⚠️ DEPRECATED → redirects to x-ipe-assistant
- SKILL.md: templates/x-ipe-assistant.md
- skill-meta.md: templates/skill-meta-x-ipe-assistant.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
10. IF Knowledge pipeline service (Operations + Steps, called by assistant orchestrator) → x-ipe-knowledge:
- SKILL.md: templates/x-ipe-knowledge.md
- skill-meta.md: N/A (no dedicated skill-meta template yet)
11. IF Assistant/orchestrator skill (格物致知 backbone, coordinates other skills) → x-ipe-assistant:
- SKILL.md: templates/x-ipe-assistant.md
- skill-meta.md: templates/skill-meta-x-ipe-assistant.md
</action>
<constraints>
- BLOCKING: Must select exactly one skill type
- BLOCKING: Must identify both SKILL.md and skill-meta.md templates
</>
skill_type, skill_template_path, skill_meta_template_path
Gather Concrete Examples
1. Ask user for functionality requirements
2. Collect trigger phrase examples
3. Document expected outputs
- CRITICAL: Skip only if patterns already clearly understood
- At least 2 usage scenarios documented
- Trigger patterns identified
examples[], trigger_patterns[]
Plan Bundled Resources
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
- Resource requirements documented
resources_plan[]
Self-Critique Scope
skill_type, skill_template_path, examples[], resources_plan[]
1. AI self-critique — validate scope against objective criteria:
a. Skill type matches the description (e.g., not a tool skill disguised as task-based)
b. Template path exists and is correct for the chosen type
c. Examples cover at least 2 distinct trigger patterns
d. Resources plan references only files that will be created (no dangling refs)
e. No naming conflicts with existing skills in .github/skills/
2. Collect unresolved_questions[] — ONLY genuine ambiguities:
- "This skill could be task-based OR tool type — which fits better?"
- "Example 2 overlaps with existing skill X — should we merge or keep separate?"
3. IF unresolved_questions is EMPTY → scope validated, proceed
4. IF unresolved_questions is NON-EMPTY:
IF process_preference.interaction_mode == "dao-represent-human-to-interact":
→ Invoke x-ipe-assistant-user-representative-Engineer with specific questions
ELSE:
→ Present ONLY the specific questions to human
→ Incorporate answers, revise scope
- MUST NOT ask broad "is this scope correct?" — only ask specific, bounded questions
- IF self-critique passes with zero questions → skip human/DAO entirely
scope_validated
Round 1: Create Meta + Draft
skill_type, skill_template_path, skill_meta_template_path, examples[], resources_plan[]
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
- 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 `./`.
- 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/
skill-meta.md, candidate/
Round 2: Reflect + Test Cases
skill-meta.md, candidate/
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 gate optional features via project config (tools.json/.x-ipe.yaml)?
c. Does it document anti-patterns? (if 3+ steps) Limitations? (if external deps)
d. Are output naming conventions defined? (if skill produces files)
e. Were lessons from related skills consulted and applied?
2. Generate test cases from acceptance criteria
- Candidate refined based on reflection
- test-cases.yaml created
candidate/, test-cases.yaml
Round 3: Run Tests
test-cases.yaml
1. Execute tests in sandbox environment
2. Save outputs to sandbox/ folder
- All tests executed
- Execution log recorded
sandbox/{outputs}, execution-log.yaml
Round 4: Evaluate Results
sandbox/{outputs}, execution-log.yaml
1. Evaluate sandbox outputs against expectations
2. Use self_check for structural/content validation
3. Use judge_agent for quality scoring with rubric
- Evaluation report generated
- Pass/fail determination made
evaluation-report.yaml
Merge or Iterate
evaluation-report.yaml
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 10
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
- 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
- Skill merged OR iteration documented
merge_status
Validate Cross-References
merge_status == merged
1. Verify skill's Output Result YAML declares: category, next_task_based_skill, interaction_mode (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 XML block
5. Verify DoR ≤ 5 checkpoints AND DoD ≤ 10 checkpoints. If over, trim to most critical checks.
- MANDATORY: Task-based skills must declare category, next_task_based_skill, interaction_mode in Output Result for auto-discovery
- CRITICAL: DoR ≤ 5 checkpoints, DoD ≤ 10 checkpoints
- Cross-references validated
cross_references_valid
Meta & Draft Creator
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/
step_5
Reflector & Test Generator
Review candidate against skill-meta, identify gaps, suggest improvements. Then generate test-cases.yaml from acceptance criteria in skill-meta.md
step_6
- "START after sub_agent_1 completes"
Test Runner
Execute test cases in sandbox, record outputs and execution log
step_7
- "START after sub_agent_2 completes"
Evaluator
Evaluate sandbox outputs against expectations, generate evaluation-report.yaml
step_8
- "START after sub_agent_3 completes"
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"
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>
<checkpoint required="true">
<name>Planning Complete</name>
<verification>skill_type, template_path, examples[], resources_plan[] defined; skill-meta.md created from template</verification>
</checkpoint>
<checkpoint required="true">
<name>Candidate Created</name>
<verification>candidate/SKILL.md + all bundled resources (references/, scripts/, templates/) exist in candidate/</verification>
</checkpoint>
<checkpoint required="true">
<name>Validation Passed</name>
<verification>test-cases.yaml created, sandbox executed, evaluation passed (must_pass=100%, should_pass>=80%)</verification>
</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
SKILL.md Structure Valid
Frontmatter valid (name + triggers), section order correct, keywords used, line count under limit (500; 600 for x-ipe-tool)
DoR/DoD Within Limits
Created skill has DoR at most 5 and DoD at most 10 checkpoints
Step Outputs Covered
Every step output in created skill has a corresponding DoD checkpoint
Cross-References Valid
Auto-discovery fields in Output Result (if task-based), Input Initialization present, bidirectional refs verified
Input Initialization Present
Skills with non-trivial input resolution have Input Initialization subsection with input_init block
Examples Documented
references/examples.md exists with concrete usage scenarios
Templates
BLOCKING: Always use the appropriate template. Never create SKILL.md or skill-meta.md from scratch.
References
Related Skills
| Skill | Purpose |
|---|
x-ipe-meta-lesson-learned | Capture issues and feedback after skill execution |
