# improve-skill

improve-skill audits skill effectiveness, simulates user requests, and pinpoints missing capabilities in instructions.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 276 repo stars
- Author: Samarth Gupta
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/gupsammy/Claudest/tree/HEAD/plugins/claude-skills/skills/improve-skill/SKILL.md
- Updated: 2026-10-29
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/samarth-gupta-improve-skill

## What it does

The skill inspects existing instruction sets to see if they actually solve user tasks. It identifies divergence spots where multiple executions might produce conflicting results, pauses on missing requirements, and finds tasks left unfinished. If frontmatter fields or syntax formatting break, the author recommends routing those fixes to `repair-skill` instead.

The evaluation executes in sequential stages. First, it loads the target `SKILL.md` file alongside its helper directories, asking the user what falls short. Next, it runs a mental walkthrough of representative prompts, validates tool parameters against current docs using the `claude-code-guide` subagent, and evaluates edge-case failures. The review scores findings using a rubric from `references/effectiveness-rubric.md`.

This tool relies on search tools alongside local file edits. It only works on skill directories or `SKILL.md` documents, meaning agent configurations are unsupported.

## Install

### Claude Code (native platform)

1. **Plugin marketplace**
In the agent chat (not a shell):
```text
/plugin marketplace add gupsammy/Claudest
```
In the agent chat (not a shell):
```text
/plugin install claude-skills@Claudest
```
This installs the whole claude-skills plugin with all its skills

2. **Skills CLI (Vercel)**
```bash
npx skills add gupsammy/Claudest --skill improve-skill -a claude-code
```

3. **Manually: put the files in place**
- File: `~/.claude/skills/improve-skill/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/improve-skill/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add gupsammy/Claudest --skill improve-skill -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/improve-skill/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add gupsammy/Claudest --skill improve-skill -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/improve-skill/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install gupsammy/Claudest plugins/claude-skills/skills/improve-skill
```

2. **Manually: put the files in place**
- File: `.github/skills/improve-skill/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add gupsammy/Claudest --skill improve-skill -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/gupsammy/Claudest --path plugins/claude-skills/skills/improve-skill
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/improve-skill/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/gupsammy/Claudest/tree/HEAD/plugins/claude-skills/skills/improve-skill/SKILL.md

## When to use it
- detect underspecified workflow steps and dead ends in `SKILL.md`
- verify CLI arguments and tool parameters against official docs
- identify complementary features to expand skill scope
- stress test prompt instructions with edge-case inputs

## Example prompts
- Review and improve the skill located at `./skills/release-helper`
- Check `./my-skill/SKILL.md` for missing features and UX friction
- Audit my skill in `~/.claude/skills/db-migrate` and find logic gaps

## Similar
- [improve](https://affpapa.org/en/nevibecode/skills/improve.md) — skill · 42400 installs
- [improve-react](https://affpapa.org/en/nevibecode/skills/improve-react.md) — skill · 2900 installs
- [improve-code-quality](https://affpapa.org/en/nevibecode/skills/improve-code-quality.md) — skill · 2700 installs
- [improve-architecture](https://affpapa.org/en/nevibecode/skills/daveebbelaar-improve-architecture.md) — skill · 1000 installs
- [improve-ui](https://affpapa.org/en/nevibecode/skills/improve-ui.md) — skill · 10400 installs
- [TDD Refactor Phase - Improve Quality & Security](https://affpapa.org/en/nevibecode/agents/tdd-refactor-phase-improve-quality-security.md) — subagent · ★ 41430 repo stars

## Other versions with the same name
- [improve-skill · openai](https://affpapa.org/en/nevibecode/skills/improve-skill.md) — 1 install

From the same set: [gupsammy/claudest](https://affpapa.org/en/nevibecode/by/gupsammy/claudest.md) — 47 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
