Skill Master

An intelligent orchestrator that automates the entire skill lifecycle: discovery, creation, execution, and improvement.

Overview

When invoked with a task, this skill:

1. Searches for existing skills that can handle the task
2. Creates a new skill if none found (after deep research)
3. Invokes the skill (using Skill tool) to complete the user's task
4. Reviews the execution and improves the skill if needed

When invoked with feedback about a previous output: 5. Fixes the output according to user's request 6. Links feedback to the skill via state tracking 7. Improves the skill based on the feedback

Workflow

---

Phase 1: Skill Discovery

Goal: Find an existing skill that can handle the user's task.

Step 1.1: Parse the Request

Identify from the user's request:

• Core task: What needs to be accomplished?
• Domain: What area/field does this belong to?
• Keywords: Key terms for searching

Step 1.2: Search for Skills

MUST follow the complete search workflow in references/skill-search.md.

Copy and track overall search progress:

Search Phase Progress:
- [ ] Step 1: Internal skills searched
- [ ] Step 2.1: ALL known GitHub repos searched (anthropics, K-Dense-AI, ComposioHQ)
- [ ] Step 2.2: Known repos enumerated (if 2.1 had no matches)
- [ ] Step 2.3: Broader GitHub search (only after 2.1+2.2 exhausted)
- [ ] Step 3: Web search (only after GitHub exhausted)

CRITICAL: MUST complete ALL searches in each step before proceeding to next step.

Search order - execute in sequence:

1. Internal skills: MUST check both

   ~/.claude/skills/

   and

   .claude/skills/

2. GitHub known repos: MUST search ALL three repos before broader search:

   • site:github.com/anthropics/skills SKILL.md <keywords>

   • site:github.com/K-Dense-AI/claude-scientific-skills SKILL.md <keywords>

   • site:github.com/ComposioHQ/awesome-claude-skills SKILL.md <keywords>

3. GitHub enumeration: MUST enumerate repo contents if searches return no match
4. GitHub broader: Only after known repos exhausted
5. Web: Only after GitHub exhausted

See references/known-skill-repos.md for curated skill sources.

Step 1.3: Evaluate Results

Validation gate before concluding search:

• All internal locations checked
• All known GitHub repos searched
• All known repos enumerated (if no WebSearch matches)
• Results documented for each source

If skill found:

• Present the skill to user with description
• Proceed to Phase 2 (Storage Confirmation)

If NO skill found (only after ALL searches complete):

• Inform user: "No existing skill found. I'll research and create one."
• Proceed to Phase 3 (Skill Creation)

---

Phase 2: Storage Confirmation

Goal: Determine where to store the skill.

Ask user using AskUserQuestion:

Where should this skill be stored?

1. LOCAL (.claude/skills/)
   - Project-specific
   - Shared with team via git

2. GLOBAL (~/.claude/skills/)
   - Personal
   - Available across all projects

Remember the choice for later use.

Step 2.1: Source Tracking (External Skills Only)

CRITICAL: When storing a skill found from an external source (GitHub, web), you MUST create a

source.md

file alongside the SKILL.md to track provenance.

Create

source.md

in the skill directory with:

# Source

- **Origin**: <GitHub | Web | MCP Marketplace>
- **URL**: <original URL where skill was found>
- **Repository**: <owner/repo if GitHub>
- **Author**: <original author if known>
- **Retrieved**: <date skill was fetched>
- **License**: <license if specified>

## Notes

<Any relevant notes about the source, modifications made, etc.>

Do NOT create source.md for:

• Skills created from scratch (Phase 3)
• Skills already present locally

---

Phase 3: Skill Creation (if not found)

Goal: Create a new skill through deep research.

Follow the creation workflow in references/skill-create.md.

Steps:

1. Research the domain thoroughly using WebSearch
2. Identify best practices and common patterns
3. Design the skill structure
4. Generate SKILL.md following official format
5. Save to the location user chose in Phase 2

---

Phase 4: Skill Execution

Goal: Invoke the skill to complete the user's original task.

CRITICAL: You MUST invoke the found/created skill using the Skill tool. Do NOT manually follow the instructions - the skill must be triggered as an independent execution.

Step 4.1: Invoke the Skill

Use the Skill tool to trigger the skill:

Skill: <skill-name>
args: <user's original request>

Example:

Skill: market-research-reports
args: "Create a market analysis for electric vehicles in Europe"

The Skill tool will:

1. Load the skill's SKILL.md
2. Execute the skill's workflow
3. Complete the user's task
4. Return control when finished

Step 4.2: Capture Execution Memory

After the skill completes, the conversation now contains "execution memory" - the full record of what happened during skill execution. This memory is used in Phase 5 for review.

Step 4.3: Verify Completion

Confirm the skill delivered the expected output to the user.

---

Phase 5: Skill Review

Goal: Determine if the skill needs improvement based on actual execution.

CRITICAL: This must happen in a fresh agent context using Task tool.

Step 5.1: Spawn Fresh Agent

Use Task tool to create a fresh agent for review:

Task: "Review skill execution for improvements"

You are reviewing a skill execution. You have:
1. The SKILL.md content (provided below)
2. The conversation memory of what actually happened (this conversation)

Your job: Compare what the skill SAYS vs what ACTUALLY HAPPENED.

## The Skill
<paste SKILL.md content here>

## Review Questions
1. Did I have to deviate from the skill's instructions? Where?
2. Did I have to improvise something not in the skill? What?
3. Did the user have to clarify something the skill should have covered?
4. Were there errors/retries that better instructions could prevent?

## Output
If NO divergence: "Skill executed perfectly. No improvements needed."
If divergence found: List specific improvements with format:
- Location: <which part of skill>
- Issue: <what happened during execution>
- Suggestion: <concrete change to make>

Step 5.2: Handle Review Results

If no improvements needed:

• Report to user: "Skill worked well, no updates needed."
• Proceed to Phase 6 (Complete)

If improvements suggested:

• Present improvements to user
• Ask: "Would you like me to apply these improvements to the skill?"
• If yes: Proceed to Phase 5.3
• If no: Proceed to Phase 6 (Complete)

Step 5.3: Apply Improvements

Follow the improvement workflow in references/skill-improve.md.

For local/personal skills: Apply changes directly using Edit tool.

For official/external skills:

• Cannot modify directly
• Generate improvement suggestions as a document
• Offer to create a PR description if it's on GitHub

---

Phase 6: Complete

Report final status:

## Task Complete

- **Task**: <original request>
- **Skill Used**: <skill name>
- **Skill Location**: <path>
- **Improvements Applied**: Yes / No / N/A

<Any relevant notes>

---

Phase 7: Feedback Handling (User-Triggered)

Trigger: User explicitly invokes skill-master with feedback about a previous output.

Examples:

• /skill-master please fix the report, the analysis is too shallow

• Invoke skill-master to adjust the documentation and add more examples

Step 7.1: Fix the Output First

Address the user's immediate request:

1. Identify the output file(s) mentioned
2. Make the requested changes/improvements
3. Confirm changes with user

Step 7.2: Check for State Tracking

Look for

.skill-master-state.json

in the working directory:

Read: .skill-master-state.json

If state file exists and matches the output:

• Proceed to Step 7.3

If no state file or no match:

• Report: "Output fixed. No linked skill found for improvement."
• Done.

Step 7.3: Link Feedback to Skill

From state file, identify:

• skill_name

  : Which skill produced this output

• skill_path

  : Where the skill is stored

• outputs

  : Verify the file user mentioned is in the outputs list

Step 7.4: Trigger Review with Feedback Context

Use Task tool to spawn fresh agent for review:

Task: "Review skill based on user feedback"

The user requested changes to output produced by this skill.
This feedback indicates the skill needs improvement.

## The Skill
<paste SKILL.md content>

## User Feedback
<user's feedback request>

## Changes Made
<what was changed to fix the output>

## Your Task
Determine how to improve the skill so future executions
produce better output without needing these adjustments.

## Output
List specific improvements:
- WHERE: <which part of skill>
- ISSUE: <what was missing/wrong>
- SUGGESTION: <concrete change>

Step 7.5: Apply Improvements

Follow references/skill-improve.md to apply the suggested improvements.

Report:

## Feedback Processed

- **Output Fixed**: Yes
- **Linked Skill**: <skill name>
- **Skill Improved**: Yes / No (if external)
- **Changes**: <summary of skill improvements>

---

State Management

Track workflow state by writing to

.skill-master-state.json

:

{
  "request": "original user request",
  "state": "SEARCH | CREATE | EXECUTE | REVIEW | COMPLETE | FEEDBACK",
  "skill_found": true/false,
  "skill_name": "name",
  "skill_path": "path",
  "skill_source": {
    "origin": "internal | github | web | created",
    "url": "original URL if external",
    "retrieved": "date"
  },
  "storage_location": "local | global",
  "outputs": ["path/to/output1.md", "path/to/output2.pdf"],
  "improvements_needed": true/false,
  "improvements_applied": true/false
}

Update this file as you progress through phases.

Output Tracking

During Phase 4 (Execution), track all files created by the skill:

1. Before execution: Note existing files in output directories
2. After execution: Identify new/modified files
3. Update state: Add file paths to

   outputs

   array

This enables Phase 7 (Feedback Handling) to link user feedback to the skill that produced the output.

---

Error Handling

Error	Recovery
Search fails (network)	Retry once, then proceed to creation
Skill creation fails	Report to user, ask for guidance
Execution fails	Capture in memory, still do review
Review times out	Skip review, complete workflow

---

References

• skill-search.md - Skill discovery workflow
• skill-create.md - Skill creation workflow
• skill-review.md - Execution review workflow
• skill-improve.md - Improvement application workflow