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.

See {baseDir}/docs/standard.md for skill structure and writing requirements.

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