Improve Skill

Proactive skill improvement. When you notice a gap in a skill during work, this skill automatically:

1. Detects which skill is responsible
2. Drafts an improvement
3. Proposes the update to the user

DO NOT wait for the user to ask. Propose improvements immediately. </IMPORTANT>

Automatic Detection

How to Detect the Responsible Skill

When you notice a gap, identify the skill by:

Task-to-Skill Mapping

Gap Detection Triggers

Automatically propose improvement when:

IF (using skill X) AND (any of these occur):
  - You need a rule that doesn't exist
  - The skill's threshold seems wrong for this case
  - A pattern you encountered isn't documented
  - You found a better way to do something
  - The skill's guidance was incomplete
  - You had to look up something externally
THEN:
  - Invoke this skill
  - Propose the improvement

Automatic Process

┌─────────────────────────────────────────────────────────────────┐
│     AUTOMATIC: Gap Detected During Work                         │
│   "I need X but the skill doesn't cover it"                     │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│     AUTOMATIC: Identify Responsible Skill                        │
│   Use task-to-skill mapping + context                           │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│     AUTOMATIC: Draft Improvement Proposal                        │
│   Match skill style, find right section                         │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│     PROPOSE TO USER                                              │
│   "I noticed X is missing from skill Y. Add this?"              │
└─────────────────────────────────────────────────────────────────┘
                          │           │
                         no          yes
                          │           │
                          ▼           ▼
                    ┌─────────┐ ┌───────────────────────┐
                    │Continue │ │ Apply + Report        │
                    │ work    │ └───────────────────────┘
                    └─────────┘

Proposal Format

When proposing an improvement to the user, use this format:

---
**Skill Improvement Detected**

**Skill:** `[skill-name]`
**Gap:** [What's missing or wrong]
**Context:** [How you discovered this]

**Proposed Addition:**

[Show the exact content to add, in skill's style]

**Location:** [Section where it would go]

---
Apply this improvement? (y/n)

Example Proposal

---
**Skill Improvement Detected**

**Skill:** `code-smells`
**Gap:** Missing "Parallel Inheritance Hierarchies" detection criteria
**Context:** During PR review, found this smell but skill didn't have clear thresholds

**Proposed Addition:**

### Parallel Inheritance Hierarchies

**Detection:**
- Every time you create a subclass of one class, you need to create a subclass of another
- Prefixes in class names match across hierarchies (e.g., `PhoneDevice`/`PhoneDialer`)

**Severity:** Should Fix (50)

**Location:** Category 3: Change Preventers section

---
Apply this improvement? (y/n)

Phase 1: Locate the Skill

Skills can be in multiple locations:

To find a skill:

# Check global skills (symlinked from radisha)
ls -la ~/.claude/skills/<skill-name>/

# Find the actual source
readlink -f ~/.claude/skills/<skill-name>/SKILL.md

Always edit the source file in radisha project, not the symlink.

Phase 2: Analyze Current Content

Before making changes:

1. Read the full skill - understand its structure and style
2. Identify the section where your addition belongs
3. Check for conflicts - does your addition contradict existing content?
4. Match the style - use same formatting (tables, code blocks, etc.)

Skill Structure (typical)

---
name: skill-name
description: ...
---

# Skill Title

<IMPORTANT> key rules </IMPORTANT>

## When to Use
## Process/Phases
## Detailed Instructions
## Common Mistakes (if applicable)
## References

Phase 3: Draft Improvement

Types of Improvements

Writing Guidelines

1. Be concise - skills should be scannable
2. Use tables - easier to read than paragraphs
3. Include examples - show, don't just tell
4. Add rationale - explain WHY, not just WHAT
5. Match existing tone - consistent style throughout

Improvement Template

## [Section Name]

### [New Rule/Pattern Name]

**Why:** [Brief rationale]

**Detection:**
- [Criteria 1]
- [Criteria 2]

**Example:**
```code
// Bad
[bad example]

// Good
[good example]

Severity: [Critical/Must Fix/Should Fix/Nitpick]

## Phase 4: Apply Change

### Edit Checklist

- [ ] Found the source file (not symlink)
- [ ] Read surrounding context
- [ ] Matched existing style
- [ ] Added to appropriate section
- [ ] No contradictions with existing content
- [ ] Used Edit tool (not Write) for existing files

### Common Edit Locations

| Skill Type | Typical Sections to Update |
|------------|---------------------------|
| Programming skills | Rules tables, code examples |
| Planning skills | Phase checklists, task lists |
| Review skills | Detection criteria, severity tables |
| Debugging skills | Troubleshooting steps, symptoms |

## Phase 5: Report

After making the change, report:

```markdown
## Skill Improved: [skill-name]

**What was missing:** [Description of the gap]

**What was added:**
- [Summary of addition]

**Location:** [File:Line or Section name]

**Reason:** [Why this improvement helps]

Examples of Automatic Detection

Example 1: During PR Review

Situation: Reviewing C++ code, you encounter a pattern that looks wrong but isn't in code-smells.

Internal thought: "This is a 'Refused Bequest' - subclass doesn't use parent methods. The skill mentions it but has no detection criteria."

Automatic action:

---
**Skill Improvement Detected**

**Skill:** `code-smells`
**Gap:** "Refused Bequest" lacks detection criteria
**Context:** Found during PR review of inheritance hierarchy

**Proposed Addition:**

**Detection criteria:**
- Subclass overrides parent method to do nothing or throw
- Subclass uses <30% of inherited interface
- Subclass only uses parent for type compatibility

**Severity:** Should Fix (50) - indicates wrong inheritance

**Location:** Object-Orientation Abusers section

---
Apply this improvement? (y/n)

Example 2: During Implementation

Situation: Writing C++ code, you need a pattern for optional parameters but programming-cpp doesn't cover it.

Internal thought: "I know std::optional is the right choice here, but the skill doesn't mention it."

Automatic action:

---
**Skill Improvement Detected**

**Skill:** `programming-cpp`
**Gap:** No guidance on optional parameters
**Context:** Needed while implementing function with optional config

**Proposed Addition:**

### Optional Parameters

| Pattern | Use Case |
|---------|----------|
| `std::optional<T>` | Value may or may not be present |
| Default argument | Always has a sensible default |
| Overloads | Different behavior, not just presence |

```cpp
// Good: explicit optionality
void configure(std::optional<Config> config = std::nullopt);

// Bad: using pointer for optionality
void configure(Config* config = nullptr);

Location: Parameters section

Apply this improvement? (y/n)

### Example 3: After Debugging

**Situation:** Spent time debugging a rocprofiler-systems issue. The solution should be in the debugging skill.

**Internal thought:** "I figured out that `ROCPROFSYS_VERBOSE=3` helps diagnose this. Others will hit this too."

**Automatic action:**
```markdown
---
**Skill Improvement Detected**

**Skill:** `debugging-rocprof-sys`
**Gap:** Missing verbose logging troubleshooting step
**Context:** Discovered while debugging instrumentation failure

**Proposed Addition:**

### Enable Verbose Logging

When standard troubleshooting doesn't reveal the issue:

```bash
export ROCPROFSYS_VERBOSE=3
rocprof-sys-run -- ./app

Levels: 1 (errors), 2 (warnings), 3 (info), 4+ (debug)

Location: General Troubleshooting section

Apply this improvement? (y/n)

## When NOT to Use This Skill

| Situation | What to Do Instead |
|-----------|---------------------|
| Creating a new skill | Use `radisha-create-skill` |
| Major skill rewrite | Plan it as a feature |
| Project-specific rules | Add to project's CLAUDE.md |
| One-time exception | Just note it in the review |

## Quick Reference

```bash
# Find skill source
readlink -f ~/.claude/skills/<name>/SKILL.md

# Edit skill
# Use Edit tool on the source file

# After editing, changes are immediately available
# (skills are symlinked, no need to "deploy")

Integration

This skill works with:

• radisha-create-skill - for new skills
• radisha-update - for updating radisha itself
• radisha-skills - to list available skills