ClawSkills/claw-skills/workflows/fix-skills.md

fix-skills

Used when a skill or its scripts fail to produce expected results, or throw errors.

Principle

Do not resort to workarounds lightly. Identify the root cause first, then fix properly.

Process

1. Gather Information

• Record the triggering scenario: how it was called, expected result, actual result
• Record the error output in full (stack traces, debug output)
• Confirm the environment: model version, node, skill version (git log helps)

2. Analyze Root Cause

Investigate in this order:

1. Are inputs/parameters correct? — Do they match what the script or tool expects?
2. Are dependencies satisfied? — Are required secrets, tokens, config files present?
3. Is there a bug in the script logic? — Read the source, add set -x if needed
4. Is there a design flaw in the skill? — Does the logic actually cover this scenario?

3. Pinpoint the File

• Identify which file and which line the problem is in
• If it's a skill issue → follow the improve-skills workflow
• If it's an execution environment issue → document in memory/ and escalate to hang

4. Fix

• Test the fix locally
• If skill files need to be modified → follow improve-skills process to PR or push to a branch
• Avoid introducing new side effects

5. Verify

• Reproduce the original scenario; confirm the issue is resolved
• Log the fix in memory/YYYY-MM-DD.md

6. Escalate if Needed

• If the issue requires hang or another agent → post in report channel
• Include: scenario, expected/actual result, root cause, fix applied