skill-creator

name	skill-creator
description	Create new skills following a structured 4-phase workflow. Use when you need to build reusable agent skills with proper validation.

Skill Creator

A meta-skill for creating new skills using a structured 4-phase workflow. Based on SkillForge 4.0 principles but simplified for learning projects. This skill ensures quality, prevents duplicates, and promotes timeless, reusable skill designs.

When to Use This Skill

Activate this skill in the following scenarios:

Primary Use Cases

• Creating new skills: When you need to build a new skill for the research agent system
• Formalizing workflows: Converting recurring workflows or processes into reusable skills
• Ensuring quality: When skill quality and consistency matter through structured validation
• Preventing duplicates: Before creating a new skill, to verify no existing skill covers the need

Trigger Phrases

• "Create a new skill for..."
• "Build a skill that..."
• "Formalize this workflow as a skill"
• "I need a reusable skill to..."
• "Make this process into a skill"

When NOT to Use

• For one-off tasks that won't be repeated
• When an existing skill already covers the need
• For tasks too specific to generalize (Timelessness Score < 4)

Four-Phase Workflow

The skill creation process follows four distinct phases. Each phase must complete before proceeding to the next.

Phase 0          Phase 1           Phase 2           Phase 3
Discovery   -->  Requirements  -->  Specification -->  Generation
& Triage         Analysis           Design             & Validation

---

Phase 0: Discovery and Triage

Purpose: Determine if a new skill is needed or if existing skills can be used/improved.

Step 0.1: Search Existing Skills

Before creating any skill, search the existing skill repository:

python3 [SKILLS_DIR]/skill-creator/scripts/discover_skills.py "keyword or description"

Or manually explore:

ls -la [SKILLS_DIR]/
grep -r "description:" [SKILLS_DIR]/*/SKILL.md

Step 0.2: Triage Decision

Based on the search results, determine the appropriate action:

Decision	Condition	Action
CREATE_NEW	No existing skill covers the need	Proceed to Phase 1
IMPROVE_EXISTING	Existing skill partially covers the need	Enhance the existing skill
USE_EXISTING	Existing skill fully covers the need	Use the existing skill as-is

Step 0.3: Document Triage Rationale

Before proceeding, document your decision:

## Triage Decision: [CREATE_NEW | IMPROVE_EXISTING | USE_EXISTING]

### Skills Searched
- [skill-1]: [relevance assessment]
- [skill-2]: [relevance assessment]

### Rationale
[Why the decision was made]

### Gap Analysis (if CREATE_NEW)
[What capability is missing from existing skills]

---

Phase 1: Requirements Analysis

Purpose: Deeply understand the skill requirements through structured analysis.

Step 1.1: Extract Requirements

Identify both explicit and implicit requirements from the request:

Explicit Requirements (directly stated):

• What the skill must do
• Expected inputs and outputs
• Specific constraints mentioned

Implicit Requirements (inferred):

• Error handling needs
• Edge cases to consider
• Integration requirements
• User experience expectations

Step 1.2: Apply Five Thinking Models

Analyze the skill through five complementary lenses:

1. First Principles Thinking

"What is the fundamental problem this skill solves?"

• Strip away assumptions
• Identify the core value proposition
• Question existing approaches

Template:

Core Problem: [What fundamental need does this address?]
Essential Components: [What absolutely must be included?]
Assumptions Challenged: [What "obvious" things might be wrong?]

2. Systems Thinking

"How does this skill fit into the larger ecosystem?"

• Map interactions with other skills
• Identify dependencies and dependents
• Consider emergent behaviors

Template:

Upstream Dependencies: [What this skill needs]
Downstream Consumers: [What might use this skill]
System Integration Points: [How it connects to the broader system]
Potential Conflicts: [What might it interfere with?]

3. Pre-Mortem Analysis

"If this skill fails, what went wrong?"

Imagine the skill failed completely. Work backward to identify potential failure modes:

Template:

Failure Mode 1: [Description]
- Cause: [Why this might happen]
- Prevention: [How to avoid it]
- Detection: [How to notice early]

Failure Mode 2: [Description]
- Cause: [Why this might happen]
- Prevention: [How to avoid it]
- Detection: [How to notice early]

4. Constraints Analysis

"What limitations must this skill work within?"

Identify hard constraints (non-negotiable) and soft constraints (preferences):

Template:

Hard Constraints:
- [Constraint 1]: [Why it's mandatory]
- [Constraint 2]: [Why it's mandatory]

Soft Constraints:
- [Constraint 1]: [Why it's preferred]
- [Constraint 2]: [Why it's preferred]

Resource Limits:
- Time: [Execution time bounds]
- Tokens: [LLM token budget]
- External calls: [API limits]

5. Pareto Principle (80/20)

"What 20% of features delivers 80% of the value?"

Prioritize ruthlessly:

Template:

High-Value Features (MUST HAVE):
1. [Feature]: [Value delivered]
2. [Feature]: [Value delivered]

Nice-to-Have Features (COULD HAVE):
1. [Feature]: [Marginal value]
2. [Feature]: [Marginal value]

Cut Features (WON'T HAVE):
1. [Feature]: [Why cut]

Step 1.3: Assess Timelessness Score

Rate the skill's expected longevity on a 1-10 scale:

Score	Assessment	Action
1-3	Too specific/temporary	REJECT - Do not create skill
4-5	Needs abstraction	REVISE - Make more general
6-7	Good balance	APPROVE - Proceed with creation
8-10	Timeless pattern	EXEMPLARY - Document as template

Scoring Criteria:

Criterion	Low Score (1-3)	High Score (8-10)
Specificity	Tied to specific tool versions	Pattern-based, tool-agnostic
Reusability	Single project only	Cross-project applicable
Stability	Frequent changes expected	Core concepts unlikely to change
Scope	Narrow edge case	Common, recurring need
Dependencies	Many external dependencies	Minimal dependencies

Assessment Template:

## Timelessness Assessment

| Criterion | Score (1-10) | Rationale |
|-----------|--------------|-----------|
| Specificity | [N] | [Why] |
| Reusability | [N] | [Why] |
| Stability | [N] | [Why] |
| Scope | [N] | [Why] |
| Dependencies | [N] | [Why] |

**Average Score**: [N]
**Decision**: [REJECT | REVISE | APPROVE | EXEMPLARY]

---

Phase 2: Specification

Purpose: Define the complete skill specification before implementation.

Step 2.1: Define YAML Frontmatter

Create the skill metadata:

---
name: [lowercase-hyphen-case]
description: [Action-oriented description under 1024 chars, no angle brackets]
---

Naming Rules:

• Lowercase letters, numbers, and hyphens only
• Maximum 64 characters
• Must be unique across all skills
• Should be descriptive but concise

Description Rules:

• Start with an action verb
• Maximum 1024 characters
• No angle brackets (<>)
• Include primary trigger condition

Step 2.2: Structure Sections

Plan the skill documentation structure:

# [Skill Name]

[Brief overview paragraph]

## When to Use This Skill
[Scenarios and trigger conditions]

## How to Use
[Step-by-step usage instructions]

### Basic Usage
[Minimal example]

### Advanced Usage
[Complex scenarios]

## Examples
[Practical examples with expected outputs]

## Best Practices
[Guidelines for effective use]

## Troubleshooting
[Common issues and solutions]

Step 2.3: Define Trigger Phrases

Identify 3-5 natural language phrases that should activate this skill:

### Trigger Phrases
1. "[Primary trigger phrase]"
2. "[Alternative phrasing]"
3. "[Another common request format]"
4. "[Domain-specific terminology]"
5. "[Abbreviated/shorthand version]"

Step 2.4: Determine Script Requirements

Assess whether the skill needs supporting scripts:

Skill Type	Scripts Needed	Examples
Process/Workflow	No	Synthesis, analysis methodologies
Tool Integration	Yes	API wrappers, search utilities
Validation/Testing	Yes	Linters, validators
Data Processing	Yes	Parsers, formatters

If scripts are needed, specify:

• Script name and purpose
• Input parameters
• Output format
• Dependencies required

---

Phase 3: Generation and Validation

Purpose: Create the skill artifacts and validate them.

Step 3.1: Generate SKILL.md

Create the skill file using the template:

# Create skill directory
mkdir -p [SKILLS_DIR]/[skill-name]

# Create SKILL.md
# (Use the structured template from Phase 2)

SKILL.md Template:

---
name: [skill-name]
description: [Skill description]
---

# [Skill Title]

[Overview paragraph explaining what the skill does and its value]

## When to Use This Skill

[Detailed scenarios when this skill should be activated]

### Primary Use Cases
- **[Use case 1]**: [Description]
- **[Use case 2]**: [Description]
- **[Use case 3]**: [Description]

### Trigger Phrases
- "[Phrase 1]"
- "[Phrase 2]"
- "[Phrase 3]"

## How to Use

[Step-by-step instructions]

### Prerequisites
[Required setup or dependencies]

### Basic Usage
[Minimal working example]

### Step-by-Step Workflow

#### Step 1: [First Step]
[Instructions]

#### Step 2: [Second Step]
[Instructions]

#### Step 3: [Third Step]
[Instructions]

## Examples

### Example 1: [Simple Case]
[Detailed example with input and expected output]

### Example 2: [Complex Case]
[Detailed example showing advanced usage]

## Best Practices

1. **[Practice 1]**: [Explanation]
2. **[Practice 2]**: [Explanation]
3. **[Practice 3]**: [Explanation]

## Troubleshooting

### [Common Issue 1]
**Symptom**: [What the user observes]
**Solution**: [How to fix it]

### [Common Issue 2]
**Symptom**: [What the user observes]
**Solution**: [How to fix it]

## Related Skills
- [related-skill-1]: [How they relate]
- [related-skill-2]: [How they relate]

Step 3.2: Create Supporting Scripts (if needed)

mkdir -p [SKILLS_DIR]/[skill-name]/scripts

# Create script with proper structure

Script Template:

#!/usr/bin/env python3
"""
[Script Name] - [Brief description]

Part of the [skill-name] skill.
"""

import argparse
import sys


def main():
    parser = argparse.ArgumentParser(
        description="[Script description]"
    )
    parser.add_argument(
        "input",
        help="[Input description]"
    )
    parser.add_argument(
        "--option",
        default="default",
        help="[Option description]"
    )

    args = parser.parse_args()

    # Implementation here
    result = process(args.input, args.option)
    print(result)


def process(input_value, option):
    """[Function description]"""
    # Implementation
    pass


if __name__ == "__main__":
    main()

Step 3.3: Run Validation

Validate the skill before deployment:

python3 [SKILLS_DIR]/skill-creator/scripts/validate_skill.py [SKILLS_DIR]/[skill-name]/SKILL.md

Validation Rules:

Rule	Requirement	Error if Violated
name	Lowercase, hyphen-case, ≤64 chars	"Invalid skill name format"
description	≤1024 chars, no angle brackets	"Description exceeds limit or contains invalid characters"
"When to Use"	Section must exist	"Missing required section: When to Use"
"How to Use"	Section must exist	"Missing required section: How to Use"
Frontmatter	Valid YAML syntax	"Invalid YAML frontmatter"

Validation Output Example:

Validating: [skill-name]/SKILL.md

[PASS] YAML frontmatter is valid
[PASS] Name format: skill-name (23 chars)
[PASS] Description length: 156 chars
[PASS] No angle brackets in description
[PASS] "When to Use" section found
[PASS] "How to Use" section found
[PASS] At least one example provided

Validation Result: PASSED
Skill is ready for use.

Step 3.4: Test the Skill

Before finalizing, manually test the skill:

1. Trigger Test: Verify trigger phrases activate the skill
2. Workflow Test: Follow the documented workflow end-to-end
3. Edge Case Test: Try boundary conditions
4. Integration Test: Verify interaction with related skills

---

Complete Example Workflow

Here is a complete example of creating a simple skill using all four phases:

Request

"Create a skill for generating meeting summaries from transcripts"

Phase 0: Discovery and Triage

# Search existing skills
python3 scripts/discover_skills.py "meeting summary transcript"

Results: No existing skills found for meeting summaries.

Triage Decision: CREATE_NEW

Rationale: The data-synthesis skill handles general synthesis but lacks meeting-specific structure (action items, attendees, decisions).

Phase 1: Requirements Analysis

Explicit Requirements:

• Input: Meeting transcript (text)
• Output: Structured summary with key sections
• Must extract action items

Implicit Requirements:

• Handle various transcript formats
• Preserve speaker attribution
• Time-efficient processing

Five Thinking Models Applied:

1. First Principles: Core problem is information extraction and organization from unstructured text.

2. Systems Thinking: Integrates with data-synthesis for multi-meeting analysis; outputs feed into task management systems.

3. Pre-Mortem:

   • Failure: Missing action items due to informal language
   • Prevention: Provide examples of action item patterns

4. Constraints:

   • Hard: Must handle transcripts up to 50,000 words
   • Soft: Should complete in under 2 minutes

5. Pareto (80/20):

   • MUST HAVE: Action items, key decisions, summary
   • COULD HAVE: Sentiment analysis, topic clustering
   • WON'T HAVE: Real-time transcription integration

Timelessness Score: 7/10 (APPROVE)

• Meetings are timeless
• Summary patterns are stable
• Transcript formats may vary (minor concern)

Phase 2: Specification

---
name: meeting-summarizer
description: Generate structured meeting summaries from transcripts. Use when you need to extract action items, decisions, and key discussion points from meeting records.
---

Sections: When to Use, How to Use, Summary Template, Examples, Best Practices

Trigger Phrases:

1. "Summarize this meeting transcript"
2. "Extract action items from this meeting"
3. "Create meeting notes from..."
4. "What were the key decisions in this meeting?"

Scripts Needed: None (LLM-native processing)

Phase 3: Generation and Validation

Create skill:

mkdir -p [SKILLS_DIR]/meeting-summarizer
# Write SKILL.md content

Validate:

python3 scripts/validate_skill.py [SKILLS_DIR]/meeting-summarizer/SKILL.md

Output:

Validation Result: PASSED
Skill is ready for use.

---

Available Scripts

discover_skills.py

Search existing skills to prevent duplicates.

python3 [SKILLS_DIR]/skill-creator/scripts/discover_skills.py "search query"

Options:

Option	Description
query	Search term (required)
--path	Skills directory path (default: auto-detect)
--verbose	Show detailed match information

validate_skill.py

Validate skill structure and content.

python3 [SKILLS_DIR]/skill-creator/scripts/validate_skill.py path/to/SKILL.md

Options:

Option	Description
skill_path	Path to SKILL.md file (required)
--strict	Enable strict validation mode
--fix	Attempt to auto-fix minor issues

---

Best Practices

1. Always Start with Triage

Never skip Phase 0. Duplicate skills create confusion and maintenance burden.

2. Apply All Five Thinking Models

Each model reveals different aspects. Skipping any leaves blind spots.

3. Keep Skills Focused

Follow the Single Responsibility Principle. One skill should do one thing well.

4. Include Practical Examples

Abstract documentation without examples is hard to apply. Show, don't just tell.

5. Document the WHY, Not Just the HOW

Future maintainers need context. Explain reasoning behind design decisions.

6. Aim for Timelessness Score >= 6

If a skill scores below 6, abstract it further or reconsider if it should be a skill at all.

7. Test Before Deployment

Always validate and manually test before declaring a skill complete.

8. Consider Edge Cases

Document what the skill does NOT handle to set clear expectations.

9. Keep Dependencies Minimal

Skills with fewer dependencies are more portable and maintainable.

10. Write for Your Future Self

In six months, will you remember why you made certain choices? Document it.

---

Validation Checklist

Before finalizing any skill, verify:

• Phase 0 triage completed and documented
• All five thinking models applied in Phase 1
• Timelessness Score >= 6
• YAML frontmatter is valid
• Name is lowercase, hyphen-case, ≤64 chars
• Description is ≤1024 chars with no angle brackets
• "When to Use" section exists and is comprehensive
• "How to Use" section exists with clear steps
• At least one practical example included
• Best practices documented
• Troubleshooting section addresses common issues
• validate_skill.py passes
• Manual testing completed

---

Related Skills

• data-synthesis: For combining outputs from multiple skills
• report-writing: For documenting skill design decisions
• academic-search: Example of a well-structured skill with scripts

---

Troubleshooting

"Validation failed: Invalid skill name"

Cause: Name contains uppercase letters, spaces, or special characters. Solution: Use only lowercase letters, numbers, and hyphens. Example: my-skill-name

"Validation failed: Description too long"

Cause: Description exceeds 1024 characters. Solution: Condense the description. Move detailed explanations to the skill body.

"Timelessness Score too low"

Cause: Skill is too specific to current tools or temporary needs. Solution: Abstract the skill to focus on patterns rather than implementations. If the score remains low, this may not be suitable as a reusable skill.

"Cannot find existing skills"

Cause: discover_skills.py cannot locate the skills directory. Solution: Specify the path explicitly with --path [SKILLS_DIR]

"Skill duplicates existing functionality"

Cause: Similar skill already exists. Solution: Consider using IMPROVE_EXISTING decision instead of creating a new skill.