Improve Skill

#!/usr/bin/env node

/**
 * Extract session transcript from Claude Code, Pi, or Codex session files.
 * 
 * Usage:
 *   ./extract-session.js [session-path]
 *   ./extract-session.js --agent claude|pi|codex [--cwd /path/to/dir]
 * 
 * If no arguments, auto-detects based on current working directory.
 */

const fs = require('fs');
const path = require('path');
const os = require('os');

// Parse arguments
const args = process.argv.slice(2);
let sessionPath = null;
let agent = null;
let cwd = process.cwd();

for (let i = 0; i < args.length; i++) {
  if (args[i] === '--agent' && args[i + 1]) {
    agent = args[++i];
  } else if (args[i] === '--cwd' && args[i + 1]) {
    cwd = args[++i];
  } else if (!args[i].startsWith('-')) {
    sessionPath = args[i];
  }
}

/**
 * Encode CWD for session path lookup
 */
function encodeCwd(cwd, style) {
  if (style === 'pi') {
    // Pi uses: --<cwd-without-leading-slash-with-slashes-as-dashes>--
    // e.g., /Users/mitsuhiko/Development/myproject -> --Users-mitsuhiko-Development-myproject--
    const safePath = `--${cwd.replace(/^[/\\]/, '').replace(/[/\\:]/g, '-')}--`;
    return safePath;
  }
  // Claude Code: just replace / with -
  return cwd.replace(/\//g, '-');
}

/**
 * Find the most recent session file in a directory
 */
function findMostRecentSession(dir) {
  if (!fs.existsSync(dir)) return null;
  
  const files = fs.readdirSync(dir)
    .filter(f => f.endsWith('.jsonl'))
    .map(f => ({
      name: f,
      path: path.join(dir, f),
      mtime: fs.statSync(path.join(dir, f)).mtime
    }))
    .sort((a, b) => b.mtime - a.mtime);
  
  return files.length > 0 ? files[0].path : null;
}

/**
 * Find Codex session matching CWD
 */
function findCodexSession(targetCwd) {
  const baseDir = path.join(os.homedir(), '.codex', 'sessions');
  if (!fs.existsSync(baseDir)) return null;
  
  // Find all session files, sorted by mtime
  const allSessions = [];
  
  function walkDir(dir) {
    if (!fs.existsSync(dir)) return;
    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
      const fullPath = path.join(dir, entry.name);
      if (entry.isDirectory()) {
        walkDir(fullPath);
      } else if (entry.name.endsWith('.jsonl')) {
        allSessions.push({
          path: fullPath,
          mtime: fs.statSync(fullPath).mtime
        });
      }
    }
  }
  
  walkDir(baseDir);
  allSessions.sort((a, b) => b.mtime - a.mtime);
  
  // Find most recent matching CWD
  for (const session of allSessions.slice(0, 50)) { // Check last 50
    try {
      const firstLine = fs.readFileSync(session.path, 'utf8').split('\n')[0];
      const data = JSON.parse(firstLine);
      if (data.payload?.cwd === targetCwd) {
        return session.path;
      }
    } catch (e) {
      // Skip invalid files
    }
  }
  
  return null;
}

/**
 * Auto-detect session based on CWD
 */
function autoDetectSession(cwd) {
  // Try Claude Code first
  const claudePath = path.join(os.homedir(), '.claude', 'projects', encodeCwd(cwd, 'claude'));
  let session = findMostRecentSession(claudePath);
  if (session) return { agent: 'claude', path: session };
  
  // Try Pi
  const piPath = path.join(os.homedir(), '.pi', 'agent', 'sessions', encodeCwd(cwd, 'pi'));
  session = findMostRecentSession(piPath);
  if (session) return { agent: 'pi', path: session };
  
  // Try Codex
  session = findCodexSession(cwd);
  if (session) return { agent: 'codex', path: session };
  
  return null;
}

/**
 * Parse Claude Code session format
 */
function parseClaudeSession(content) {
  const messages = [];
  const lines = content.trim().split('\n');
  
  for (const line of lines) {
    try {
      const entry = JSON.parse(line);
      if (entry.message?.role && entry.message?.content) {
        const msg = entry.message;
        messages.push({
          role: msg.role,
          content: extractContent(msg.content),
          timestamp: entry.timestamp
        });
      }
    } catch (e) {
      // Skip invalid lines
    }
  }
  
  return messages;
}

/**
 * Parse Pi session format
 */
function parsePiSession(content) {
  const messages = [];
  const lines = content.trim().split('\n');
  
  for (const line of lines) {
    try {
      const entry = JSON.parse(line);
      if (entry.type === 'message' && entry.message?.role) {
        messages.push({
          role: entry.message.role,
          content: extractContent(entry.message.content),
          timestamp: entry.timestamp
        });
      }
    } catch (e) {
      // Skip invalid lines
    }
  }
  
  return messages;
}

/**
 * Parse Codex session format
 */
function parseCodexSession(content) {
  const messages = [];
  const lines = content.trim().split('\n');
  
  for (const line of lines) {
    try {
      const entry = JSON.parse(line);
      if (entry.type === 'response_item' && entry.payload?.role) {
        const payload = entry.payload;
        messages.push({
          role: payload.role,
          content: extractContent(payload.content),
          timestamp: entry.timestamp
        });
      }
    } catch (e) {
      // Skip invalid lines
    }
  }
  
  return messages;
}

/**
 * Extract text content from various content formats
 */
function extractContent(content) {
  if (typeof content === 'string') return content;
  if (!Array.isArray(content)) return JSON.stringify(content);
  
  const parts = [];
  for (const item of content) {
    if (typeof item === 'string') {
      parts.push(item);
    } else if (item.type === 'text') {
      parts.push(item.text);
    } else if (item.type === 'input_text') {
      parts.push(item.text);
    } else if (item.type === 'tool_use') {
      parts.push(`[Tool: ${item.name}]\n${JSON.stringify(item.input, null, 2)}`);
    } else if (item.type === 'tool_result') {
      const result = typeof item.content === 'string' 
        ? item.content 
        : JSON.stringify(item.content);
      // Truncate long tool results
      const truncated = result.length > 500 
        ? result.slice(0, 500) + '\n[... truncated ...]'
        : result;
      parts.push(`[Tool Result]\n${truncated}`);
    } else {
      parts.push(`[${item.type}]`);
    }
  }
  
  return parts.join('\n');
}

/**
 * Format messages as readable transcript
 */
function formatTranscript(messages, maxMessages = 100) {
  const recent = messages.slice(-maxMessages);
  const lines = [];
  
  for (const msg of recent) {
    const role = msg.role.toUpperCase();
    lines.push(`\n### ${role}:\n`);
    lines.push(msg.content);
  }
  
  if (messages.length > maxMessages) {
    lines.unshift(`\n[... ${messages.length - maxMessages} earlier messages omitted ...]\n`);
  }
  
  return lines.join('\n');
}

// Main
async function main() {
  let result;
  
  if (sessionPath) {
    // Explicit path provided
    if (!fs.existsSync(sessionPath)) {
      console.error(`Session file not found: ${sessionPath}`);
      process.exit(1);
    }
    // Guess agent from path
    if (sessionPath.includes('.claude')) {
      result = { agent: 'claude', path: sessionPath };
    } else if (sessionPath.includes('.pi')) {
      result = { agent: 'pi', path: sessionPath };
    } else if (sessionPath.includes('.codex')) {
      result = { agent: 'codex', path: sessionPath };
    } else {
      // Default to Claude format
      result = { agent: 'claude', path: sessionPath };
    }
  } else if (agent) {
    // Agent specified, find session for that agent
    if (agent === 'claude') {
      const dir = path.join(os.homedir(), '.claude', 'projects', encodeCwd(cwd, 'claude'));
      const session = findMostRecentSession(dir);
      if (!session) {
        console.error(`No Claude Code session found for: ${cwd}`);
        process.exit(1);
      }
      result = { agent: 'claude', path: session };
    } else if (agent === 'pi') {
      const dir = path.join(os.homedir(), '.pi', 'agent', 'sessions', encodeCwd(cwd, 'pi'));
      const session = findMostRecentSession(dir);
      if (!session) {
        console.error(`No Pi session found for: ${cwd}`);
        process.exit(1);
      }
      result = { agent: 'pi', path: session };
    } else if (agent === 'codex') {
      const session = findCodexSession(cwd);
      if (!session) {
        console.error(`No Codex session found for: ${cwd}`);
        process.exit(1);
      }
      result = { agent: 'codex', path: session };
    } else {
      console.error(`Unknown agent: ${agent}`);
      process.exit(1);
    }
  } else {
    // Auto-detect
    result = autoDetectSession(cwd);
    if (!result) {
      console.error(`No session found for: ${cwd}`);
      console.error('Try specifying --agent claude|pi|codex or provide a session path directly.');
      process.exit(1);
    }
  }
  
  // Read and parse session
  const content = fs.readFileSync(result.path, 'utf8');
  
  let messages;
  switch (result.agent) {
    case 'claude':
      messages = parseClaudeSession(content);
      break;
    case 'pi':
      messages = parsePiSession(content);
      break;
    case 'codex':
      messages = parseCodexSession(content);
      break;
  }
  
  // Output metadata and transcript
  console.log(`# Session Transcript`);
  console.log(`Agent: ${result.agent}`);
  console.log(`File: ${result.path}`);
  console.log(`Messages: ${messages.length}`);
  console.log('');
  console.log(formatTranscript(messages));
}

main().catch(e => {
  console.error(e.message);
  process.exit(1);
});

{
  "schema_version": "2.0",
  "meta": {
    "generated_at": "2026-01-17T04:40:17.020Z",
    "slug": "dwsy-improve-skill",
    "source_url": "https://github.com/Dwsy/agent/tree/main/skills/improve-skill",
    "source_ref": "main",
    "model": "claude",
    "analysis_version": "3.0.0",
    "source_type": "community",
    "content_hash": "cc8d077c616767cb830de2e0e62ae15562e8cc2db0350714d85a302be1d9da68",
    "tree_hash": "02babffa919497a91eb7b7f5806ceb590fa2690e2e87307bef611a7208071599"
  },
  "skill": {
    "name": "improve-skill",
    "description": "Analyze coding agent session transcripts to improve existing skills or create new ones. Use when asked to improve a skill based on a session, or extract a new skill from session history.",
    "summary": "Analyze coding agent session transcripts to improve existing skills or create new ones. Use when ask...",
    "icon": "📈",
    "version": "1.0.0",
    "author": "Dwsy",
    "license": "MIT",
    "category": "productivity",
    "tags": [
      "workflow",
      "session",
      "analysis",
      "improvement",
      "documentation"
    ],
    "supported_tools": [
      "claude",
      "codex",
      "claude-code"
    ],
    "risk_factors": [
      "filesystem",
      "env_access"
    ]
  },
  "security_audit": {
    "risk_level": "low",
    "is_blocked": false,
    "safe_to_publish": true,
    "summary": "This skill is a legitimate utility that reads agent session files to extract and format transcripts. After evaluating all 97 static findings, all are FALSE_POSITIVES: the C2 keyword alerts flag innocent strings (community, git hashes); cryptographic algorithm alerts flag legitimate function names and JSON content; external command alerts flag documentation examples, not actual backtick execution; filesystem access is necessary and documented functionality for reading session files. No network calls or malicious patterns exist.",
    "risk_factor_evidence": [
      {
        "factor": "filesystem",
        "evidence": [
          {
            "file": "scripts/extract-session.js",
            "line_start": 50,
            "line_end": 107
          },
          {
            "file": "scripts/extract-session.js",
            "line_start": 267,
            "line_end": 322
          }
        ]
      },
      {
        "factor": "env_access",
        "evidence": [
          {
            "file": "scripts/extract-session.js",
            "line_start": 18,
            "line_end": 21
          },
          {
            "file": "scripts/extract-session.js",
            "line_start": 69,
            "line_end": 69
          },
          {
            "file": "scripts/extract-session.js",
            "line_start": 114,
            "line_end": 119
          }
        ]
      }
    ],
    "critical_findings": [],
    "high_findings": [],
    "medium_findings": [],
    "low_findings": [],
    "dangerous_patterns": [],
    "files_scanned": 3,
    "total_lines": 743,
    "audit_model": "claude",
    "audited_at": "2026-01-17T04:40:17.020Z"
  },
  "content": {
    "user_title": "Improve Skills from Session Transcripts",
    "value_statement": "Users struggle to capture and reuse successful patterns from coding sessions. This skill extracts session transcripts from Claude Code, Pi, and Codex to help you create or improve reusable skills from your actual workflow.",
    "seo_keywords": [
      "Claude Code skills",
      "skill improvement",
      "session transcript extraction",
      "AI workflow optimization",
      "Codex skill management",
      "Pi agent skills",
      "prompt engineering",
      "workflow automation",
      "skill development",
      "Claude Code workflow"
    ],
    "actual_capabilities": [
      "Extract session transcripts from Claude Code, Pi, and Codex agents",
      "Parse and format JSONL session files into readable text",
      "Auto-detect the current agent based on working directory",
      "Generate structured prompts for improving existing skills",
      "Generate structured prompts for creating new skills from sessions",
      "Locate skill files across different agent directories"
    ],
    "limitations": [
      "Only reads session files; does not modify or create skills directly",
      "Requires agent session files to exist on the filesystem",
      "Cannot analyze sessions from agents other than Claude Code, Pi, or Codex"
    ],
    "use_cases": [
      {
        "target_user": "Power users",
        "title": "Refine Your Workflows",
        "description": "Extract sessions where you struggled and create improvement prompts to make future sessions smoother."
      },
      {
        "target_user": "Team leads",
        "title": "Capture Team Knowledge",
        "description": "Document successful patterns from expert sessions and turn them into reusable team skills."
      },
      {
        "target_user": "New developers",
        "title": "Learn Best Practices",
        "description": "Create onboarding skills from expert sessions that demonstrate proper tool usage and workflows."
      }
    ],
    "prompt_templates": [
      {
        "title": "Extract Current Session",
        "scenario": "Quick transcript extraction",
        "prompt": "Run ./scripts/extract-session.js to extract the current session transcript."
      },
      {
        "title": "Specify Agent Type",
        "scenario": "Target specific platform",
        "prompt": "Run ./scripts/extract-session.js --agent claude to extract from Claude Code specifically."
      },
      {
        "title": "Improve Existing Skill",
        "scenario": "Enhance a skill",
        "prompt": "Use the improve-skill to analyze this session and generate a prompt for improving the existing skill at ~/.claude/skills/my-skill/SKILL.md."
      },
      {
        "title": "Create New Skill",
        "scenario": "Extract reusable pattern",
        "prompt": "Use the improve-skill to analyze this session and generate a prompt for creating a new skill called pattern-name based on what was accomplished."
      }
    ],
    "output_examples": [
      {
        "input": "Extract the current session and help me improve my code-review skill",
        "output": [
          "Found Claude Code session with 47 messages",
          "Analyzed session for improvement opportunities",
          "Generated improvement prompt targeting code-review skill",
          "Skill location: ~/.claude/skills/code-review/SKILL.md"
        ]
      },
      {
        "input": "Create a new skill from this debugging session",
        "output": [
          "Identified 3 key patterns from the session",
          "Created skill template with commands and API references",
          "Added common pitfalls section based on errors encountered",
          "Skill written to ~/.claude/skills/systematic-debugging/SKILL.md"
        ]
      }
    ],
    "best_practices": [
      "Extract sessions soon after completing work while context is fresh",
      "Focus on specific struggles or discoveries rather than general improvements",
      "Keep skill improvements concise with practical examples"
    ],
    "anti_patterns": [
      "Analyzing sessions without identifying clear improvement points",
      "Creating skills from single sessions without validating the pattern",
      "Making skills too broad instead of focused on specific use cases"
    ],
    "faq": [
      {
        "question": "What agents does this skill support?",
        "answer": "Claude Code, Pi, and Codex. The script auto-detects based on your working directory."
      },
      {
        "question": "Where are session files stored?",
        "answer": "Claude Code: ~/.claude/projects/, Pi: ~/.pi/agent/sessions/, Codex: ~/.codex/sessions/."
      },
      {
        "question": "Can I use this without the extract script?",
        "answer": "Yes, but manual transcript extraction is required. The skill works with any session text."
      },
      {
        "question": "Is my session data sent anywhere?",
        "answer": "No. The script runs locally and only reads files on your machine. No network calls are made."
      },
      {
        "question": "Why does the improvement happen in a new session?",
        "answer": "Starting fresh reduces token usage and prevents context contamination from the current task."
      },
      {
        "question": "How is this different from regular prompting?",
        "answer": "This skill provides structured workflows and templates specifically designed for skill development."
      }
    ]
  },
  "file_structure": [
    {
      "name": "scripts",
      "type": "dir",
      "path": "scripts",
      "children": [
        {
          "name": "extract-session.js",
          "type": "file",
          "path": "scripts/extract-session.js",
          "lines": 350
        }
      ]
    },
    {
      "name": "SKILL.md",
      "type": "file",
      "path": "SKILL.md",
      "lines": 156
    }
  ]
}