Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
ainergiz avatar

Improve Skill

  • 1 installs
  • Updated January 7, 2026
  • ainergiz/mac-setup-guide

improve-skill is a Claude Code skill that analyzes coding-agent session transcripts to improve existing skills or create new ones.

About

improve-skill is a Claude Code skill that analyzes coding-agent session transcripts to improve an existing skill or extract a new one. Its extract-session.js script pulls the current Claude Code or Codex transcript, then it generates a prompt to run in a fresh session. A developer uses it after a session to capture what was learned into a skill.

  • Auto-detects and extracts Claude Code or Codex session transcripts via a bundled script
  • Generates a self-contained improvement or creation prompt for a fresh session
  • Explains why a separate session gives cleaner, token-efficient skill analysis

Improve Skill by the numbers

  • 1 all-time installs (skills.sh)
  • Ranked #640 of 781 Skill Development skills by installs in the Skillselion catalog
  • Data as of Jul 28, 2026 (Skillselion catalog sync)
At a glance

improve-skill capabilities & compatibility

Capabilities
skill authoring · session analysis · transcript extraction
Use cases
documentation · refactoring
Pricing
Free
From the docs

What improve-skill says it does

Analyze coding agent sessions to improve or create skills. Works with Claude Code and Codex.
SKILL.md
Auto-detect agent and extract current session
SKILL.md
npx skills add https://github.com/ainergiz/mac-setup-guide --skill improve-skill

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs1
Last updatedJanuary 7, 2026
Repositoryainergiz/mac-setup-guide

What it does

Analyzing coding-agent session transcripts to improve an existing skill or extract a new one.

Who is it for?

Turning a completed Claude Code or Codex session into an improved or new skill.

Skip if: Authoring a skill from scratch with no session history to analyze.

When should I use this skill?

When asked to improve a skill based on a session or extract a new skill from session history.

What you get

An improved or newly extracted SKILL.md grounded in a real session transcript.

  • extracted session transcript
  • a skill improvement or creation prompt

By the numbers

  • Supports 2 agents (Claude Code and Codex)
  • extract-session.js is about 7.7KB

Files

SKILL.mdMarkdownGitHub ↗

Improve Skill

Analyze coding agent sessions to improve or create skills. Works with Claude Code and Codex.

Quick Start

Extract the current session and generate an improvement prompt:

# Auto-detect agent and extract current session
./scripts/extract-session.js

Session Extraction

The extract-session.js script finds and parses session files:

# Auto-detect (uses most recent session for current working directory)
./scripts/extract-session.js

# Specify agent type
./scripts/extract-session.js --agent claude
./scripts/extract-session.js --agent codex

# Specify a different working directory
./scripts/extract-session.js --cwd /path/to/project

Session file locations:

  • Claude Code: ~/.claude/projects/<encoded-cwd>/*.jsonl
  • Codex: ~/.codex/sessions/YYYY/MM/DD/*.jsonl

Workflow: Improve an Existing Skill

When asked to improve a skill based on a session:

1. Extract the session transcript:

   ./scripts/extract-session.js > /tmp/session-transcript.txt

2. Find the existing skill in one of these locations:

  • ~/.claude/skills/<skill-name>/SKILL.md
  • ~/.codex/skills/<skill-name>/SKILL.md

3. Generate an improvement prompt for a new session:

═══════════════════════════════════════════════════════════════════════════════
COPY THE FOLLOWING PROMPT INTO A NEW AGENT SESSION:
═══════════════════════════════════════════════════════════════════════════════

I need to improve the "<skill-name>" skill based on a session where I used it.

First, read the current skill at: <path-to-skill>

Then analyze this session transcript to understand:
- Where I struggled to use the skill correctly
- What information was missing from the skill
- What examples would have helped
- What I had to figure out on my own

<session_transcript>
<paste transcript here>
</session_transcript>

Based on this analysis, improve the skill by:
1. Adding missing instructions or clarifications
2. Adding examples for common use cases discovered
3. Fixing any incorrect guidance
4. Making the skill more concise where possible

Write the improved skill back to the same location.

═══════════════════════════════════════════════════════════════════════════════

Workflow: Create a New Skill

When asked to create a new skill from a session:

1. Extract the session transcript:

   ./scripts/extract-session.js > /tmp/session-transcript.txt

2. Generate a creation prompt for a new session:

═══════════════════════════════════════════════════════════════════════════════
COPY THE FOLLOWING PROMPT INTO A NEW AGENT SESSION:
═══════════════════════════════════════════════════════════════════════════════

Analyze this session transcript to extract a reusable skill called "<skill-name>":

<session_transcript>
<paste transcript here>
</session_transcript>

Create a new skill that captures:
1. The core capability or workflow demonstrated
2. Key commands, APIs, or patterns used
3. Common pitfalls and how to avoid them
4. Example usage for typical scenarios

Write the skill to: ~/.claude/skills/<skill-name>/SKILL.md

Use this format:
---
name: <skill-name>
description: "<one-line description>"
---

# <Skill Name> Skill

<overview and quick reference>

## <Section for each major capability>

<instructions and examples>

═══════════════════════════════════════════════════════════════════════════════

Why a Separate Session?

The improvement prompt is meant to be copied into a fresh agent session because:

1. Token efficiency - The current session already has a lot of context; starting fresh means only the transcript and skill are loaded 2. Clean analysis - The new session can focus purely on improvement without being influenced by the current task 3. Reproducibility - The prompt is self-contained and can be shared or reused

Tips for Good Skill Improvements

When analyzing a transcript, look for:

  • Confusion patterns - Where did the agent retry or change approach?
  • Missing examples - What specific commands or code patterns were discovered?
  • Workarounds - What did the agent have to figure out that wasn't documented?
  • Errors - What failed and how was it resolved?
  • Successful patterns - What worked well and should be highlighted?

Keep skills concise - focus on the most important information and examples.

Related skills

FAQ

Which agents does improve-skill support?

Claude Code (~/.claude/projects/.../*.jsonl) and Codex (~/.codex/sessions/.../*.jsonl).

Why run the improvement in a separate session?

For token efficiency, clean analysis, and a self-contained reproducible prompt.

Skill Developmentagentsautomation

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.