# Improve Skills

When a skill has misleading descriptions, missing coverage, or suboptimal behavior.

> See `{baseDir}/docs/standard.md` for skill structure and layer responsibilities.

## Principle

Improvement is better than workaround. Fix problems when you find them, so others don't hit the same pitfall.

## Process

### 1. Identify the Problem

- Record which skill and which part has the issue
- Describe specifically: what's misleading, what's missing, what's not working well
- Record the scenario where you encountered it

### 2. Assess Impact

- How many agents will this affect?
- Is it a design issue or a documentation issue?
- What's the complexity of the fix?

### 3. Design the Fix

- **Documentation issue** → update SKILL.md or docs/
- **Logic flaw** → modify the script
- **Missing coverage** → add a new workflow or script
- **Process issue** → redesign the workflow

### 4. Implement

- Make changes locally
- Update SKILL.md if behavior changed
- Test if the change is significant

### 5. Submit

Call `{baseDir}/scripts/promote-improvements` to push to your branch.

Commit message should describe what was changed and why.