ai-proj-helper/skills-workflow/save-session-plugin/skills/SKILL.md

name, description

name	description
save-session	Auto-save Claude session conversation with AI-generated title, summary, and tags in searchable JSON format

Save Session Skill

You are now in session save mode. Your task is to save the current conversation with a meaningful title and comprehensive summary.

Auto-Save Mode

If this skill was triggered by an <auto-save-trigger> tag, operate in auto-save mode:

• Skip all user confirmations and questions
• Generate title, summary, and tags automatically
• Save immediately without asking for custom tags
• Output a brief confirmation only

Instructions

1. Analyze the Conversation: Review the entire conversation history to understand:

   • Main topics discussed
   • Key problems solved
   • Important decisions made
   • Technologies or files involved

2. Generate Title: Create a concise, descriptive title (5-10 words) that captures the essence of the conversation.

   • Use imperative or descriptive form
   • Include key technologies/features mentioned
   • Example: "Implement User Authentication with JWT"
   • Example: "Debug Memory Leak in React Component"

3. Generate Summary: Write a structured summary (3-5 paragraphs) that includes:

   • Context: What was the initial request or problem?
   • Approach: What approach or solution was taken?
   • Key Changes: What were the main changes or implementations?
   • Outcome: What was achieved or what's the current status?
   • Next Steps (if applicable): What remains to be done?

4. Extract Tags: Identify 3-8 relevant tags:

   • Technologies used (e.g., "react", "typescript", "docker")
   • Task type (e.g., "bug-fix", "feature", "refactor", "documentation")
   • Domain (e.g., "authentication", "ui", "api", "database")

5. Get Session ID: Check ~/.claude/hooks/.current-session for the current session ID. If it doesn't exist, generate one using format YYYY-MM-DD_HHmm.

6. Filter Conversation Content: Before saving, clean the conversation:

   EXCLUDE these from saved conversation:

   • Bash/shell command outputs (keep only the command intent)
   • Full file contents from Read tool (keep only file path + brief note)
   • Tool result outputs (Glob results, Grep results, etc.)
   • <system-reminder> tags and their contents
   • <auto-save-trigger> tags
   • Raw JSON/XML tool responses
   • Error stack traces (summarize the error instead)
   • Large code blocks from file reads (keep only relevant snippets)

   INCLUDE and preserve:

   • User's questions and requests (the actual intent)
   • Assistant's explanations and reasoning
   • Key decisions and why they were made
   • Code changes made (what was added/modified)
   • Important findings and conclusions
   • File paths that were modified
   • Summary of what tools accomplished (not raw output)

   Transform tool calls to summaries:

   • Instead of: [Bash output: 500 lines of npm install...]
   • Save as: "Installed dependencies with npm install"
   • Instead of: [Read file: 200 lines of code...]
   • Save as: "Read MallPurchaseManager.java to understand order push logic"

7. Save to File: Create a JSON file in ~/.claude/sessions/ with:

   • Filename: <session-id>_<sanitized-title>.json
   • Content structure:

     {
       "id": "YYYY-MM-DD_HHmm",
       "title": "[Generated Title]",
       "date": "[ISO 8601 format]",
       "timestamp": 1234567890,
       "tags": ["tag1", "tag2"],
       "summary": {
         "context": "What was the initial request or problem?",
         "approach": "What approach or solution was taken?",
         "keyChanges": "What were the main changes or implementations?",
         "outcome": "What was achieved or what's the current status?",
         "nextSteps": "What remains to be done (if applicable)"
       },
       "metadata": {
         "messageCount": 0,
         "technologies": ["tech1", "tech2"],
         "filesModified": ["file1", "file2"]
       },
       "conversation": [
         {
           "role": "user|assistant",
           "content": "cleaned message content - NO raw tool outputs",
           "timestamp": "ISO 8601",
           "toolSummary": "optional: brief summary of tools used in this turn"
         }
       ]
     }
     

8. Update Index: After saving the session, update ~/.claude/sessions/index.json:

   • Add entry with id, title, date, tags, and summary preview
   • Keep index sorted by date (newest first)
   • If index doesn't exist, create it
   • Index structure:

     {
       "sessions": [
         {
           "id": "YYYY-MM-DD_HHmm",
           "title": "Title",
           "date": "ISO 8601",
           "tags": ["tag1"],
           "summaryPreview": "First 200 chars of context..."
         }
       ],
       "lastUpdated": "ISO 8601"
     }
     

9. Post-Save Actions: After saving:

   • Reset autosave timer: ~/.claude/hooks/autosave-mark.sh
   • Clear pending save flag: rm -f ~/.claude/hooks/.pending-save

10. Confirm: After saving, report back to the user:

• The session ID and filename
• The generated title
• Main tags extracted
• Brief confirmation with instructions on how to reload

Important Notes

• Create ~/.claude/sessions/ directory if it doesn't exist
• Sanitize the title for filename (lowercase, replace spaces with hyphens, remove special chars)
• In manual mode, ask user if they want to add any custom tags before saving
• In auto-save mode, skip all user interactions
• Always update the index file for fast searching
• Use current timestamp in ISO 8601 format
• Count actual messages in conversation for metadata
• Each conversation MUST have its own unique JSON file

Conversation Filtering Example

RAW conversation (DON'T save like this):

User: "找一下订单推送的代码"
Assistant: [Grep tool output with 50 matching files...]
Assistant: [Read file output with 200 lines of Java code...]
Assistant: "I found the order push code in MallPurchaseManager.java"
User: "修改它加上channelType"
Assistant: [Edit tool with full file diff...]
<system-reminder>Task tools haven't been used...</system-reminder>

CLEANED conversation (Save like this):

{
  "conversation": [
    {
      "role": "user",
      "content": "找一下订单推送的代码"
    },
    {
      "role": "assistant",
      "content": "Found order push code in MallPurchaseManager.java:5536 in the getJsonString() method. This method assembles order data for pushing to Lining platform.",
      "toolSummary": "Searched codebase, read MallPurchaseManager.java"
    },
    {
      "role": "user",
      "content": "修改它加上channelType"
    },
    {
      "role": "assistant",
      "content": "Added channelType field to the order push logic. Now when orders are pushed to Lining platform, it will include the external platform type (卓望/南航).",
      "toolSummary": "Edited MallPurchaseManager.java - added order.setChannelType()"
    }
  ]
}

Example Output (Manual Mode)

Session saved successfully!

ID: 2026-01-20_1430
Title: Implement Dark Mode Toggle Feature
Tags: react, css, ui, feature
File: ~/.claude/sessions/2026-01-20_1430_implement-dark-mode-toggle-feature.json

The conversation has been archived with full history (45 messages).

To reload this session: /reload-session 2026-01-20_1430
To search sessions: /search-sessions dark mode

Example Output (Auto-Save Mode)

[Auto-saved] 2026-01-20_1430: "Implement Dark Mode Toggle Feature" (45 messages)