Workflow Weaver

Workflow Weaver

Records your workflow with Claude into reusable skills through interactive questioning and real-time state management. Turn any workflow into a shareable skill that other Claude instances can immediately execute.

How It Works

1. You say: "start recording: [skill-name]"
2. Work normally with Claude
3. After each significant action, Claude asks if you want to include it
4. You choose: Add as step / Save as reference / Both / Skip
5. When done: "stop recording" generates a complete, usable SKILL.md

The skill monitors your workflow in real-time, maintains recording state in building.json, saves reference materials, and generates a fully-documented skill that's immediately executable.

Recording Commands

Start recording:

• "start recording: [skill-name]"
• "start recording skill: [skill-name]"
• "begin recording: [skill-name]"

During recording:

• "pause recording" - Stop monitoring temporarily
• "resume recording" - Continue monitoring
• "show current skill" - Preview progress
• "stop recording" or "finish recording" - Generate SKILL.md

Behavior: Detection and Initialization

When you say "start recording: [skill-name]":

Step 1: Validate skill name

• Check if recording already active (only one at a time)
• Validate skill name (alphanumeric, hyphens, underscores)

Step 2: Create directory structure

mkdir -p .claude/skills-in-progress/[skill-name]/references

Step 3: Initialize building.json

{
  "skill_name": "[skill-name]",
  "started_at": "[ISO-8601 timestamp]",
  "status": "recording",
  "steps": [],
  "references": [],
  "metadata": {
    "total_actions": 0,
    "included_steps": 0,
    "references_count": 0
  }
}

Step 4: Confirm to user

📝 Recording started for skill: **[skill-name]**

I'll ask about each action I take. Work normally!

Behavior: Self-Monitoring After Each Action

CRITICAL RULE: After EVERY significant action YOU (Claude) perform, immediately pause and use AskUserQuestion to ask how to handle it.

Actions to Monitor

Question Format

Use AskUserQuestion with this exact structure:

Question: "I just [describe action]. How should I handle this?"

Header: "Action"

Options:
  1. Label: "Add as step"
     Description: "Include this action as a numbered step in the skill"

  2. Label: "Save as reference"
     Description: "Save the content to references/ folder"

  3. Label: "Both"
     Description: "Add as step AND save content as reference"

  4. Label: "Skip"
     Description: "Don't include in the skill"

MultiSelect: false

Processing User Response

Option 1: "Add as step"

Add to steps array in building.json:

{
  "step_id": [next_number],
  "type": "[webfetch|websearch|read|bash|edit|write|grep|glob]",
  "action": "[Imperative description: 'Fetch docs', 'Read config']",
  "details": {
    "url": "[if webfetch/websearch]",
    "query": "[if websearch]",
    "file": "[if read/edit/write]",
    "command": "[if bash]",
    "pattern": "[if grep/glob]",
    "glob_pattern": "[if glob]"
  },
  "description": "[Why this step matters]",
  "timestamp": "[ISO-8601]"
}

Update metadata:

• metadata.total_actions++
• metadata.included_steps++

Respond to user:

✓ Added as step [X]

Option 2: "Save as reference"

1. Determine file type and save appropriately:

   • WebFetch/WebSearch → save as .md with source URL
   • Read → copy original file to references/
   • Bash output → save output to .txt file
   • Other → save appropriately

2. Use descriptive names:

   • Good: aws-deployment-guide.md, package-config.json
   • Bad: doc1.md, file.txt

3. Add to references array in building.json:

{
  "name": "[descriptive-name].[ext]",
  "source": "[original URL or file path]",
  "type": "[web|local|generated]",
  "description": "[What this contains and why]",
  "saved_at": "[ISO-8601]"
}

Update metadata:

• metadata.references_count++

Respond to user:

✓ Saved to references/[filename]

Option 3: "Both"

Perform BOTH actions above:

1. Add as step
2. Save as reference

Respond to user:

✓ Saved to references/[filename]
✓ Added as step [X]

Option 4: "Skip"

Only update metadata:

• metadata.total_actions++

Respond to user:

✓ Skipped

After updating: Always write updated building.json to disk immediately.

Behavior: Session Control

Monitor for these commands during recording:

"pause recording":

• Set status: "paused" in building.json
• Stop asking questions about subsequent actions
• Respond: "⏸️ Recording paused. Say 'resume recording' to continue."

"resume recording":

• Set status: "recording" in building.json
• Resume asking questions about actions
• Respond: "▶️ Recording resumed. I'll continue asking about each action."

"show current skill": Display summary from building.json:

📊 Current Skill: [skill-name]

Steps: [X]
References: [Y]
Status: [recording|paused]

Recent steps:
1. [action 1]
2. [action 2]
...

"stop recording" or "finish recording": Proceed to generation phase.

Behavior: Generating Final SKILL.md

When you say "stop recording" or "finish recording":

Step 1: Read state

cat .claude/skills-in-progress/[skill-name]/building.json

Step 2: Validate state

• Check for empty recording (0 steps)
  • If empty, confirm: "No steps recorded. Cancel and restart?"
  • Allow user to cancel or continue with references only
• Check for 50+ steps
  • Warn: "This skill has 50+ steps. Consider breaking into smaller skills."
  • Ask: "Continue anyway, or refine?"

Step 3: Generate SKILL.md

Create file with this structure:

---
name: [skill-name]
description: "[One-sentence summary derived from steps]"
allowed-tools:
  - [list unique tool types from steps]
---

# [Skill Name in Title Case]

[2-3 sentence summary of what this skill accomplishes]

## Prerequisites

[Infer from steps any required tools, files, environment setup, permissions, or dependencies]

## Steps

[For each step in building.json, create numbered section:]

### 1. [Step Action as Imperative]

[Step description explaining what this accomplishes and why it matters]

**Action:** [type]
**Details:**
- [key]: [value]
- [key]: [value]

[If reference was saved:]
**Reference:** [references/filename](references/filename)

[Repeat for all steps]

## References

[Only include this section if references array is not empty:]

This skill uses these reference materials:

- **[name]** ([references/name](references/name)) - [description]
- [Repeat for all references]

## Usage

To use this skill:

1. [Describe first step from workflow]
2. [Describe second step]
3. [Continue...]

[Optionally add example usage, variations, or common patterns]

## Notes

- [Any important prerequisites not covered above]
- [Tips for adapting this skill to different scenarios]
- [Known limitations or edge cases]
- [Dependencies on external services or tools]

---

*Generated by workflow-weaver on [current date]*
*Original recording: [skill-name], started [started_at]*

Step 4: Write SKILL.md

cat > .claude/skills-in-progress/[skill-name]/SKILL.md << 'EOF'
[generated content]
EOF

Step 5: Move to skills folder

mv .claude/skills-in-progress/[skill-name] .claude/skills/[skill-name]

Step 6: Confirm success

✅ Skill generated successfully!

📁 Location: .claude/skills/[skill-name]/
📄 Skill file: SKILL.md
📚 References: [X] files
🔢 Steps: [Y]

Your skill is ready to use!

Best Practices

Naming conventions:

• Skill names: lowercase-with-hyphens (alphanumeric, hyphens, underscores only)
• References: descriptive-source.extension (e.g., aws-deploy-guide.md, local-config.json)
• Avoid generic names: No doc1.md, file.txt, data.json

Writing step descriptions:

• Use imperative voice: "Fetch API docs" not "Fetched docs"
• Include the WHY: "Review auth flow to identify security gaps"
• Be specific: Full commands, exact URLs, complete file paths
• Link to references where relevant

Reference organization:

• Keep related content together
• Use source type in filename: github-api-docs.md, local-env-config.json
• Add descriptions explaining what the reference contains

Grouping actions:

• If 3+ similar actions occur consecutively, consider asking once: "I fetched 3 documentation pages. Save all as references?"
• Group related steps in description to help users understand workflow order

Error Handling

Corrupted building.json:

⚠️ building.json appears corrupted.

Options:
1. Restart recording (lose progress)
2. Attempt recovery (read last valid state)
3. Cancel recording

Skill name already exists:

⚠️ Skill '[name]' already exists.

Options:
1. Overwrite existing (will be backed up)
2. Use different name
3. Cancel

Recording has 50+ steps:

💡 This skill has 50+ steps. Consider:
1. Continue (may be hard to use)
2. Break into multiple smaller skills
3. Finish and refine later

Missing or unreadable reference:

• Note in SKILL.md with [MISSING REFERENCE] marker
• Include original source path/URL for manual recovery
• Continue generation without blocking

Permission denied when writing:

• Offer to write to alternative location
• Show path where skill would be saved
• Ask permission to retry or save elsewhere

Edge Cases

Only one recording at a time:

• If user tries "start recording" while already recording
• Respond: "Already recording skill: [name]. Say 'stop recording' first."
• Offer to show current skill with "show current skill"

Empty recording:

• If 0 steps when stopping
• Confirm: "No steps recorded. Cancel recording and start over?"
• Allow saving with references only if references exist

Paused too long:

• If recording paused for 100+ actions performed
• Offer reminder: "Still recording? Say 'stop' to finish or 'resume' to continue."

Massive recordings:

• More than 100 steps suggests need to break into multiple skills
• Warn user and suggest splitting workflow

File system issues:

• If can't create directories, offer fallback locations
• If can't write building.json, fail early with clear error
• Ensure graceful degradation

Example Session

User: start recording: deploy-to-production

Claude: 📝 Recording started for skill: **deploy-to-production**

I'll ask about each action I take. Work normally!

[Claude performs WebFetch to deployment docs]

Claude: I just fetched https://docs.aws.amazon.com/deploy.
        How should I handle this?

User: Both

Claude: ✓ Saved to references/aws-deploy-docs.md
        ✓ Added as step 1

[Claude reads local config file]

Claude: I just read file config/production.yml.
        How should I handle this?

User: Save as reference

Claude: ✓ Saved to references/production-config.yml

[Claude executes deployment bash commands]

Claude: I just executed: `aws deploy create-deployment`
        How should I handle this?

User: Add as step

Claude: ✓ Added as step 2

[... workflow continues ...]

User: stop recording

Claude: ✅ Skill generated successfully!

📁 Location: .claude/skills/deploy-to-production/
📄 Skill file: SKILL.md
📚 References: 3 files
🔢 Steps: 7

Your skill is ready to use!

Implementation Requirements

1. State persistence: Write building.json after EVERY update

   • Atomic writes to prevent corruption
   • Timestamp every operation
   • Validate JSON before writing

2. Action detection: Monitor all significant operations

   • WebFetch, WebSearch, Read, Bash, Edit, Write, Grep, Glob
   • Ask immediately after action completes
   • Include relevant details in question

3. Clear questions: Make AskUserQuestion options self-explanatory

   • Short descriptions (<50 chars)
   • Clear distinction between options
   • Use consistent formatting

4. Graceful degradation: Handle missing tools/permissions

   • Attempt to continue if permission denied
   • Offer fallback options
   • Log issues in references or notes

5. Consistent formatting: Follow specified JSON and SKILL.md formats exactly

   • Valid JSON for building.json
   • Markdown with YAML frontmatter for SKILL.md
   • Descriptive filenames for references
   • Consistent timestamps (ISO-8601)

Success Criteria

• Claude detects "start recording" commands in all formats
• Directory structure created correctly in .claude/skills-in-progress/
• AskUserQuestion appears after each monitored action
• building.json updates correctly with each response
• References saved with descriptive, meaningful names
• Final SKILL.md well-formatted, complete, and immediately executable
• Skill can be used by another Claude instance without modification
• Error cases handled gracefully with helpful messages
• State persists across conversation turns
• References folder organized and accessible

This skill enables self-documenting workflow capture. Use it to create reusable skills from any workflow you build with Claude.