improve-skill

name	improve-skill
description	Iteratively improve an existing skill or command based on feedback
allowed-tools	["Bash","Read","Write","Edit","Glob","Grep"]

Iteratively improve an existing skill or command based on feedback, corrections, or identified issues.

Process

1. Locate the Component

   • Search plugins/*/commands/ and plugins/*/skills/ for the specified name
   • Read the current instruction file
   • Understand its purpose and current implementation

2. Gather Context If feedback is provided, analyze it. Otherwise, prompt for:

   • What's not working as expected?
   • What behavior should change?
   • Any specific scenarios that fail?

3. Analyze Current Instructions Evaluate the existing component for:

   • Clarity of description/trigger documentation
   • Completeness of process steps
   • Coverage of edge cases
   • Robustness of rules
   • Quality of examples

4. Propose Improvements Based on feedback and analysis, suggest specific changes:

   • Additional process steps
   • New rules to handle edge cases
   • Better examples
   • Clarified language
   • Error handling additions

5. Present Changes Show a diff-style view of proposed changes:

   ## Proposed Changes to {component-name}
   
   ### Addition: New Rule
   + - Handle edge case X by doing Y
   
   ### Modification: Process Step 3
   - 3. Old step description
   + 3. Improved step description with more detail
   
   ### Addition: Example
   + ## Example: Edge Case Handling
   + User: `/component-name --edge-case`
   + Result: Handles it gracefully
   

6. Apply or Iterate

   • If user approves, apply the changes
   • If user has more feedback, incorporate and re-propose
   • Track what was changed for potential rollback

Arguments

Argument	Required	Description
name	Yes	Name of the skill or command to improve
feedback	No	Specific feedback or issues to address

Component Type Assessment

Before improving, verify the component is the right type:

Commands (commands/*.md) - Use when:

• User should invoke explicitly via /command-name
• Needs to appear in autocomplete
• Discrete, user-initiated action (commit, build, test, deploy)
• Format: YAML frontmatter with name, description, allowed-tools

Skills (skills/*/INSTRUCTIONS.md) - Use when:

• Agent should trigger proactively based on context
• No explicit user invocation needed
• Background behavior or analysis
• Format: Markdown with ## When to Use description

If a skill should be a command (user-invoked action), recommend converting it.

Improvement Categories

Clarity Improvements

• Ambiguous language made specific
• Complex steps broken down
• Jargon explained or removed

Robustness Improvements

• Edge cases handled
• Error scenarios addressed
• Fallback behaviors defined

Completeness Improvements

• Missing steps added
• Examples included
• Rules expanded

Consistency Improvements

• Alignment with other components in the repo
• Standardized formatting
• Consistent terminology

Example

User: /improve-skill commit

Analysis reveals:

• Missing guidance on merge commits
• No example for breaking changes
• Unclear on when to use which commit type

Proposed additions:

### Merge Commits

When committing a merge, use the format:
`merge: integrate {branch} into {target}`

### Breaking Changes

For breaking changes, use:
`feat!: description` or `fix!: description`
Include a BREAKING CHANGE footer explaining the impact.

Important Rules

• Always show proposed changes before applying
• Preserve the component's original intent - don't change what it does, just how well it does it
• Make incremental improvements - don't rewrite entire components
• Reference specific feedback when explaining changes
• After applying changes, run bun run typecheck and bun run build to verify