system-create-skill

Direct Skill Creation Requests

• "create skill", "create a skill", "new skill for X"
• "build skill", "make skill", "add skill"
• "Create-A-Skill" (canonical name)
• "skill for [purpose]" or "need a skill that does X"

Skill Validation Requests

• "validate skill", "check skill compliance", "audit skill structure"
• "verify skill follows standards", "is this skill compliant"
• "review skill architecture", "skill quality check"

Skill Update Requests

• "update skill", "refactor skill", "fix skill routing"
• "add workflow to skill", "extend skill"
• "reorganize skill structure", "migrate skill"

Skill Canonicalization Requests

• "canonicalize skill", "canonicalize this skill", "canonicalize [skill-name]"
• "rebuild skill to standards", "refactor skill to canonical structure"
• "fix skill compliance", "bring skill to canonical form"
• "standardize skill structure", "make skill compliant"

Quality & Compliance Indicators

• User mentions "architectural standards" or "compliance"
• User references "skill-structure.md"
• User asks about "skill best practices" or "skill patterns"
• User needs to ensure skill follows "template" or "philosophy"

---

Architectural Compliance

MANDATORY: Every skill MUST comply with the canonical architecture defined in:

${PAI_DIR}/skills/CORE/skill-structure.md

This document defines:

• The 3 skill archetypes (Minimal, Standard, Complex)
• The 4-level routing hierarchy
• Mandatory structural requirements
• Workflow organization patterns
• Naming conventions
• Routing patterns

NON-NEGOTIABLE Requirements:

1. Workflow Routing Section FIRST - Immediately after YAML frontmatter
2. Every Workflow Must Be Routed - No orphaned workflow files
3. Every Secondary File Must Be Linked - From main SKILL.md body
4. Canonical Structure Template - Follow the exact structure
5. Progressive Disclosure - SKILL.md → workflows → documentation → references

Template-Driven Philosophy

Consistency over creativity when it comes to structure:

• Use established archetypes (Minimal/Standard/Complex)
• Follow canonical naming conventions
• Implement proven routing patterns
• Maintain predictable organization

Creativity where it matters:

• Domain-specific workflows
• Custom capabilities
• Unique integrations
• Innovative approaches to problems

Quality Gates

Every created/updated skill must pass:

1. Structural Validation

- Correct archetype directory structure

- Proper file naming conventions

- Required files present

1. Routing Validation

- Workflow Routing section present and FIRST

- All workflows explicitly routed

- Activation triggers comprehensive (8-category pattern)

1. Documentation Validation

- All files referenced in SKILL.md

- Clear purpose and when-to-use guidance

- Examples provided

1. Integration Validation

- No duplication of CORE context

- Compatible with agent workflows

---

Step 1: Define Skill Purpose

Ask user to clarify:

• What does this skill do? (Core capability)
• When should it activate? (Trigger patterns)
• What workflows does it need? (Count and categories)
• What integrations? (Agents, external services)

Step 2: Choose Archetype

Based on workflow count and complexity:

Minimal Skill (1-3 workflows)

```

skill-name/

├── SKILL.md

└── workflows/ OR assets/

└── *.md

```

Standard Skill (3-15 workflows)

```

skill-name/

├── SKILL.md

├── workflows/

│ └── *.md (flat or nested)

└── [optional: documentation/, tools/, references/]

```

Complex Skill (15+ workflows)

```

skill-name/

├── SKILL.md

├── CONSTITUTION.md (optional)

├── METHODOLOGY.md (optional)

├── documentation/

├── workflows/ (nested)

├── references/

├── state/

└── tools/

```

Step 3: Read Architecture Document

ALWAYS read the canonical architecture before creating:

```bash

${PAI_DIR}/skills/CORE/skill-structure.md

```

This ensures:

• Latest architectural requirements
• Current best practices
• Proven routing patterns
• Quality standards

Step 4: Create Skill Structure

Use the canonical template from skill-structure.md:

```markdown

---

name: skill-name

description: |

What this skill does and when to use it.

USE WHEN: user says "trigger phrase", "another trigger", or any related request.

---

When user requests [action 1]:

Examples: "actual user phrases", "variations", "synonyms"

→ READ: ${PAI_DIR}/skills/skill-name/workflows/workflow1.md

→ EXECUTE: What to do with this workflow

[Route EVERY workflow file]

---

[Comprehensive activation triggers using 8-category pattern]

---

[Detailed information, file links, examples]

```

Step 5: Validate Compliance

Run through quality gates:

• ✅ Workflow Routing section present and FIRST?
• ✅ All workflows explicitly routed?
• ✅ All files referenced in main body?
• ✅ Activation triggers comprehensive?
• ✅ Examples provided?
• ✅ Naming conventions followed?

Step 6: Test Activation

Verify skill activates with natural language triggers from description.

---

Detailed pattern and quality references:

• references/skill-patterns-reference.md - 8-category routing pattern, routing patterns, anti-patterns
• references/quality-checklist.md - Complete quality checklist and validation gates

---

Primary Reference Document

${PAI_DIR}/skills/CORE/skill-structure.md

• Canonical guide for all skill structure and routing
• Defines the 3 archetypes (Minimal, Standard, Complex)
• The 4-level routing hierarchy
• All structural requirements and naming conventions
• Routing pattern examples
• Complete skill ecosystem reference
• ALWAYS read this before creating or updating skills

Workflow Files

${PAI_DIR}/skills/system-create-skill/workflows/create-skill.md

• Complete skill creation workflow
• Step-by-step process with validation gates
• Template generation
• Quality assurance checks

${PAI_DIR}/skills/system-create-skill/workflows/validate-skill.md

• Skill compliance audit workflow
• Structural validation
• Routing validation
• Documentation validation
• Integration validation

${PAI_DIR}/skills/system-create-skill/workflows/update-skill.md

• Skill update and refactoring workflow
• Adding workflows to existing skills
• Reorganizing skill structure
• Migration patterns

---

Example 1: Creating a Minimal Skill

User: "Create a skill for generating API documentation"

System-create-skill Response:

1. Read skill-structure.md
2. Determine archetype: Minimal (single workflow)
3. Create structure:

```

api-docs/

├── SKILL.md

└── workflows/

└── generate-docs.md

```

1. Write SKILL.md with:

- YAML: name, description with USE WHEN triggers

- Workflow Routing section (FIRST)

- When to Activate section (8-category pattern)

- Main body with workflow description

1. Validate against quality checklist
2. Test activation: "generate API docs for my service"

Example 2: Creating a Standard Skill

User: "Create a skill for database operations - migrations, backups, queries, optimization"

System-create-skill Response:

1. Read skill-structure.md
2. Determine archetype: Standard (4 workflows)
3. Create structure:

```

database/

├── SKILL.md

└── workflows/

├── run-migration.md

├── backup-database.md

├── optimize-queries.md

└── execute-query.md

```

1. Write SKILL.md with semantic routing:

- Route "run migration" → run-migration.md

- Route "backup database" → backup-database.md

- Route "optimize" → optimize-queries.md

- Route "query" → execute-query.md

1. Comprehensive activation triggers covering all 4 workflows
2. Validate and register
3. Test each workflow activation

Example 3: Validating Existing Skill

User: "Validate the research skill for compliance"

System-create-skill Response:

1. Read skill-structure.md
2. Read ${PAI_DIR}/skills/research/SKILL.md
3. Run validation:

- ✅ Workflow Routing section present and FIRST

- ✅ All 12 workflows explicitly routed

- ✅ Activation triggers comprehensive

- ✅ All files referenced

- ✅ Standard archetype structure correct

1. Report: "research skill is COMPLIANT - no issues found"

---

system-create-skill ensures:

• Every created skill follows architectural standards
• Compliance is validated automatically
• Templates drive consistency
• Quality gates prevent non-compliant skills
• Philosophy is embedded in process

Three core operations:

1. Create - New skills with architectural compliance
2. Validate - Existing skills against standards
3. Update - Modify skills while maintaining compliance

One source of truth:

${PAI_DIR}/skills/CORE/skill-structure.md

Zero tolerance for:

• Orphaned workflows (not routed)
• Invisible files (not linked)
• Vague triggers (not comprehensive)
• Structural violations (wrong archetype)

---

Related Documentation:

• ${PAI_DIR}/skills/CORE/skill-structure.md - Canonical architecture guide (PRIMARY)
• ${PAI_DIR}/skills/CORE/CONSTITUTION.md - Overall PAI philosophy

Last Updated: 2025-11-17