improve-this

Description

A skill that evaluates any project — code, docs, prompts, or otherwise — for potential improvements. Propose which categories to evaluate, review the findings, and optionally generate a phased implementation plan for the issues you care about.

Run it with different AI models (or newly-released models) to surface different improvement perspectives on prior work. The skill is strictly evaluate-and-report — it never modifies files.

Usage

/improve-this                      # Review the full project
/improve-this src/components       # Scope to a directory
/improve-this search               # Scope to a topic
/improve-this --dry-run            # Also test-run the skill under review in a sandbox
/improve-this --version            # Show installed version and update status
/improve-this --help               # Show help

The skill will:

1. Infer your project type, and check the claims your docs make (flags, paths, versions, tool names) against what's actually in the repo
2. Propose relevant evaluation categories for you to confirm
3. Analyze the project and present findings with Impact + Confidence ratings and file:line evidence
4. Offer to save the report and/or generate an implementation plan for selected findings

Skills, READMEs, and agent instruction files

When the project contains them, these get dedicated rubrics (in references/), loaded only when their category is selected:

• Skill Effectiveness (SKILL.md, command files) — triggering description, executable steps, defined failure paths, output contract, references that actually exist, progressive disclosure, platform parity
• README Quality — purpose, install commands that work as written, usage that matches real flags/features, accurate claims
• Agent Instructions (CLAUDE.md, AGENTS.md, GEMINI.md, …) — per-session token cost, contradictions, rules that don't fit the project, missing tools, emphasis inflation

--dry-run adds a behavioral check for skill projects: a subagent runs the skill on 2–3 sample prompts in a scratch directory, and deviations are reported as findings.

Tip: Run with different models to get different perspectives on the same codebase.

Installation

From the mackayi marketplace (recommended)

/plugin marketplace add keithmackay/mackayi
/plugin install improve-this@mackayi

Claude Code

# Global (available in all projects) — copy the whole skill folder; SKILL.md alone loses help, version, dry-run, and rubric files
mkdir -p ~/.claude/skills
cp -r /path/to/improve-this/skills/improve-this ~/.claude/skills/improve-this

# Or symlink it, so a git pull updates the skill
ln -s /path/to/improve-this/skills/improve-this ~/.claude/skills/improve-this

Then invoke with: /improve-this

Codex

Add to your marketplace JSON (~/.agents/plugins/marketplace.json, create if absent):

{
  "name": "personal",
  "interface": { "displayName": "Personal Plugins" },
  "plugins": [
    {
      "name": "improve-this",
      "source": { "source": "local", "path": "/path/to/improve-this/" },
      "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
      "category": "Productivity"
    }
  ]
}

Antigravity

The skill's SKILL.md is fully Antigravity-compatible (no platform-specific metadata to strip).

# Global install (all workspaces)
mkdir -p ~/.gemini/antigravity/skills
cp -r /path/to/improve-this/skills/improve-this ~/.gemini/antigravity/skills/improve-this

# Workspace install (current project only)
mkdir -p .agents/skills
cp -r /path/to/improve-this/skills/improve-this .agents/skills/improve-this

Skills are auto-discovered. Mention /improve-this to activate.

Gemini CLI

gemini extensions install https://github.com/keithmackay/improve-this

To update:

gemini extensions update improve-this

The skill is auto-discovered from GEMINI.md after installation.

Compatibility

Feature	Claude Code	Codex	Antigravity	Gemini CLI
Core skill	✅	✅	✅	✅
--dry-run (needs subagents)	✅	✅	✅	❌

Legend: ✅ Supported · ❌ Not supported

Gemini CLI note: Gemini CLI has no subagent dispatch, so --dry-run reports that it's unsupported and runs the static review only. Everything else works on all platforms.

Maintaining this skill

skills/improve-this/SKILL.md is the source of truth for the skill body. Neither Claude Code nor Antigravity supports including one file's content inside another, so improve-this.md and the root SKILL.md are manually kept as synced copies (GEMINI.md avoids this by using Gemini CLI's @-include convention instead). Support files (help.md, version.md, dry-run.md, references/) are mirrored at the repo root for the same reason. After editing anything under skills/improve-this/, run scripts/check-sync.sh. It confirms the body copies and root mirrors match, and that the manifest versions agree with the top CHANGELOG entry.

Changelog

See CHANGELOG.md for release history.

License

MIT

References

• Claude Code Skills: https://code.claude.com/docs/en/skills
• Claude Code Complete Guide (PDF): https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
• Codex Plugins: https://developers.openai.com/codex/plugins/build
• Antigravity Skills: https://antigravity.google/docs/skills
• Gemini CLI Extensions: https://github.com/google-gemini/gemini-cli/blob/main/docs/extension.md
• Agent Skills open standard: https://agentskills.io/home