--- name: skill-memory description: Generate progressive project SKILL package from documentation with path mirroring argument-hint: "[path] [--tool ] [--regenerate] [--skip-docs]" --- # Memory SKILL Package Generator ## Overview Lightweight planner that analyzes documentation structure, decomposes SKILL package work into tasks, and generates execution plans. Transforms project documentation into reusable SKILL package with **mirrored source structure**. **SKILL Package Output**: All knowledge files are placed in `.claude/skills/{project_name}/knowledge/` directory with **mirrored project structure**. For example: - Project: `my_app` - Source: `my_app/src/modules/auth/` → SKILL: `.claude/skills/my_app/knowledge/src/modules/auth/API.md` - Source: `my_app/lib/core/` → SKILL: `.claude/skills/my_app/knowledge/lib/core/README.md` ## Path Mirroring Strategy **Principle**: SKILL knowledge structure **mirrors** source code structure under project-specific directory. | Source Path | Project Name | SKILL Knowledge Path | |------------|--------------|---------------------| | `my_app/src/modules/auth/` | `my_app` | `.claude/skills/my_app/knowledge/src/modules/auth/API.md` | | `my_app/lib/core/` | `my_app` | `.claude/skills/my_app/knowledge/lib/core/README.md` | | `another_project/src/api/` | `another_project` | `.claude/skills/another_project/knowledge/src/api/API.md` | **Benefits**: - Easy to locate SKILL docs for any source file - Maintains logical organization matching codebase - Clear 1:1 mapping between code and knowledge - Supports any project structure (src/, lib/, packages/, etc.) ## Core Concept **SKILL Package** = SKILL.md entry + OVERVIEW.md (index) + Path-mirrored knowledge docs ``` .claude/skills/{project}/ ├── SKILL.md # Entry point with progressive references └── knowledge/ ├── OVERVIEW.md # Project overview + quickstart + module index (合并) └── [mirrored source structure] ├── src/ │ ├── modules/ │ │ ├── auth/ │ │ │ ├── API.md │ │ │ └── README.md │ │ └── api/ │ │ ├── API.md │ │ └── README.md │ └── utils/ │ └── README.md └── lib/ └── core/ ├── API.md └── README.md ``` ## Parameters ```bash /memory:skill-memory [path] [--tool ] [--regenerate] [--skip-docs] ``` - **path**: Target directory (default: current directory) - Specifies the directory to generate SKILL package for - **--tool**: CLI tool selection (default: gemini) - `gemini`: Comprehensive documentation, pattern recognition - `qwen`: Architecture analysis, system design focus - **--regenerate**: Force regenerate docs from source code (optional) - When enabled: Runs `/memory:docs --mode full` first - When disabled: Uses existing docs from `.workflow/docs/{project}` - **--skip-docs**: Skip documentation generation phase (optional) - Uses existing docs in `.workflow/docs/{project}` directly - Fails if no existing docs found ## Planning Workflow ### Phase 1: Initialize Session #### Step 1: Create Session and Generate Config ```bash # Parse arguments bash( path="${1:-.}" tool="gemini" regenerate=false skip_docs=false shift while [[ $# -gt 0 ]]; do case "$1" in --tool) tool="$2"; shift 2 ;; --regenerate) regenerate=true; shift ;; --skip-docs) skip_docs=true; shift ;; *) shift ;; esac done # Detect paths project_root=$(git rev-parse --show-toplevel 2>/dev/null || pwd) if [[ "$path" == /* ]] || [[ "$path" == [A-Z]:* ]]; then target_path="$path" else target_path=$(cd "$path" 2>/dev/null && pwd || echo "$PWD/$path") fi # Extract project name from target_path project_name=$(basename "$target_path") # Paths docs_path=".workflow/docs/${project_name}" skill_path=".claude/skills/${project_name}" # Create session timestamp=$(date +%Y%m%d-%H%M%S) session="WFS-skill-${timestamp}" mkdir -p ".workflow/${session}"/{.task,.process,.summaries} touch ".workflow/.active-${session}" # Generate config cat > ".workflow/${session}/.process/config.json" </dev/null | wc -l) echo "${doc_count}" else echo "0" fi ) ``` **Output**: `15` (existing docs found) or `0` (no docs) #### Step 2: Trigger Documentation Generation (if needed) ```bash # Generate docs if needed bash( skip_docs=$(jq -r '.skip_docs' .workflow/WFS-skill-20240120/.process/config.json) regenerate=$(jq -r '.regenerate' .workflow/WFS-skill-20240120/.process/config.json) doc_count=$(jq -r '.existing_docs // 0' .workflow/WFS-skill-20240120/.process/config.json) if [[ "$skip_docs" == "true" ]]; then if [[ $doc_count -eq 0 ]]; then echo "❌ Error: --skip-docs specified but no documentation found" exit 1 else echo "📄 Using existing documentation (${doc_count} files)" fi elif [[ "$regenerate" == "true" ]] || [[ $doc_count -eq 0 ]]; then echo "📝 Generating documentation..." # Will trigger /memory:docs via SlashCommand else echo "📄 Using existing documentation (${doc_count} files)" fi ) # Update config with docs status bash( jq '. + {existing_docs: 15, docs_status: "ready"}' .workflow/WFS-skill-20240120/.process/config.json > .workflow/WFS-skill-20240120/.process/config.json.tmp && mv .workflow/WFS-skill-20240120/.process/config.json.tmp .workflow/WFS-skill-20240120/.process/config.json ) ``` **If documentation needed**: ```bash # Call /memory:docs SlashCommand("/memory:docs --mode full --tool gemini") # Wait for docs completion (manual or via /workflow:execute) # Then continue... ``` ### Phase 3: Analyze Documentation Structure **Goal**: Analyze existing documentation to prepare for SKILL package generation #### Step 1: List Documentation Files ```bash # Find all documentation files (excluding project-level files) bash( docs_path=$(jq -r '.docs_path' .workflow/WFS-skill-20240120/.process/config.json) find "${docs_path}" -type f -name "*.md" \ ! -path "${docs_path}/README.md" \ ! -path "${docs_path}/ARCHITECTURE.md" \ ! -path "${docs_path}/EXAMPLES.md" \ ! -path "${docs_path}/api/*" \ > .workflow/WFS-skill-20240120/.process/module-docs.txt cat .workflow/WFS-skill-20240120/.process/module-docs.txt ) ``` **Output** (module-docs.txt): ``` .workflow/docs/my_app/src/modules/auth/API.md .workflow/docs/my_app/src/modules/auth/README.md .workflow/docs/my_app/src/modules/api/API.md .workflow/docs/my_app/src/modules/api/README.md .workflow/docs/my_app/lib/core/API.md .workflow/docs/my_app/lib/core/README.md ``` #### Step 2: Extract Directory Structure ```bash # Extract unique directories from module docs bash( docs_path=$(jq -r '.docs_path' .workflow/WFS-skill-20240120/.process/config.json) # Get unique directory paths cat .workflow/WFS-skill-20240120/.process/module-docs.txt | \ xargs -n 1 dirname | \ sort -u | \ sed "s|^${docs_path}/||" \ > .workflow/WFS-skill-20240120/.process/doc-dirs.txt cat .workflow/WFS-skill-20240120/.process/doc-dirs.txt ) ``` **Output** (doc-dirs.txt): ``` src/modules/auth src/modules/api lib/core ``` #### Step 3: Count Statistics ```bash # Calculate statistics bash( total_docs=$(wc -l < .workflow/WFS-skill-20240120/.process/module-docs.txt) total_dirs=$(wc -l < .workflow/WFS-skill-20240120/.process/doc-dirs.txt) echo "📊 Documentation Analysis:" echo " - Module docs: ${total_docs}" echo " - Directories: ${total_dirs}" ) # Update config bash( jq '. + {analysis: {total_docs: "12", total_dirs: "3"}}' .workflow/WFS-skill-20240120/.process/config.json > .workflow/WFS-skill-20240120/.process/config.json.tmp && mv .workflow/WFS-skill-20240120/.process/config.json.tmp .workflow/WFS-skill-20240120/.process/config.json ) ``` ### Phase 4: Generate Tasks **Goal**: Create task JSONs for SKILL package generation **Task Structure**: ``` IMPL-001: Generate SKILL.md entry point IMPL-002: Generate OVERVIEW.md (合并 README + EXAMPLES + module index) IMPL-003: Mirror module documentation structure ``` #### Task 1: Generate SKILL.md Entry Point **Goal**: Create SKILL.md with YAML frontmatter and progressive references ```json { "id": "IMPL-001", "title": "Generate SKILL.md Entry Point", "status": "pending", "meta": { "type": "skill-entry", "agent": "@doc-generator", "tool": "gemini" }, "context": { "requirements": [ "Create SKILL.md with YAML frontmatter", "Add progressive loading guide", "Reference OVERVIEW.md for project overview", "Reference mirrored module paths" ], "project_name": "${project_name}", "skill_path": "${skill_path}" }, "flow_control": { "pre_analysis": [ { "step": "load_project_info", "command": "bash(cat ${docs_path}/README.md 2>/dev/null || echo 'No README')", "output_to": "project_readme" }, { "step": "list_modules", "command": "bash(cat ${session_dir}/.process/doc-dirs.txt)", "output_to": "module_list" } ], "implementation_approach": [ { "step": 1, "title": "Generate SKILL.md", "description": "Create SKILL.md entry point with YAML frontmatter and progressive references", "modification_points": [ "Create ${skill_path}/SKILL.md", "Add YAML frontmatter (name, description)", "Add progressive loading guide (Level 0-3)", "Reference OVERVIEW.md for minimal context", "List available modules from [module_list]" ], "logic_flow": [ "Parse [project_readme] for project description", "Parse [module_list] for available modules", "Generate SKILL.md with structure:", " - YAML frontmatter", " - Progressive loading guide", " - Level 0: [OVERVIEW.md](knowledge/OVERVIEW.md)", " - Level 1-3: Module references with mirrored paths" ], "depends_on": [], "output": "skill_entry" } ], "target_files": ["${skill_path}/SKILL.md"] } } ``` #### Task 2: Generate OVERVIEW.md (Merged Index) **Goal**: Merge project README + EXAMPLES + module index into single OVERVIEW.md ```json { "id": "IMPL-002", "title": "Generate OVERVIEW.md (Merged Index)", "status": "pending", "meta": { "type": "skill-overview", "agent": "@doc-generator", "tool": "gemini" }, "context": { "requirements": [ "Merge README.md, EXAMPLES.md, and module index into OVERVIEW.md", "Include project overview, quickstart, and module list", "Add statistics and token estimates" ], "docs_path": "${docs_path}", "skill_path": "${skill_path}" }, "flow_control": { "pre_analysis": [ { "step": "load_readme", "command": "bash(cat ${docs_path}/README.md 2>/dev/null || echo 'No README')", "output_to": "readme_content" }, { "step": "load_examples", "command": "bash(cat ${docs_path}/EXAMPLES.md 2>/dev/null || echo 'No examples')", "output_to": "examples_content" }, { "step": "load_architecture", "command": "bash(cat ${docs_path}/ARCHITECTURE.md 2>/dev/null || echo 'No architecture')", "output_to": "architecture_content" }, { "step": "load_module_list", "command": "bash(cat ${session_dir}/.process/doc-dirs.txt)", "output_to": "module_dirs" }, { "step": "calculate_stats", "command": "bash(find ${docs_path} -name '*.md' | wc -l; find ${docs_path} -name '*.md' -exec wc -c {} + | tail -1 | awk '{print int($1/4)}')", "output_to": "stats" } ], "implementation_approach": [ { "step": 1, "title": "Generate OVERVIEW.md", "description": "Merge project overview, quickstart, architecture, and module index into single OVERVIEW.md", "modification_points": [ "Parse [readme_content], [examples_content], [architecture_content]", "Parse [module_dirs] for module list", "Calculate [stats] for token estimates", "Create ${skill_path}/knowledge/OVERVIEW.md with sections:", " 1. Project Overview (from README)", " 2. Quick Start (from EXAMPLES)", " 3. Architecture (from ARCHITECTURE)", " 4. Module Index (from module_dirs with links)", " 5. Statistics (files, tokens, generated date)" ], "logic_flow": [ "Create directory: ${skill_path}/knowledge/", "Merge content sections:", " # Project Overview", " [readme_content summary]", " ", " ## Quick Start", " [examples_content key examples]", " ", " ## Architecture", " [architecture_content summary]", " ", " ## Module Index", " [For each dir in module_dirs:", " - [module_name](src/modules/auth/README.md)]", " ", " ## Statistics", " - Modules: X", " - Files: Y", " - Estimated Tokens: Z" ], "depends_on": [], "output": "overview_doc" } ], "target_files": ["${skill_path}/knowledge/OVERVIEW.md"] } } ``` #### Task 3: Mirror Module Documentation **Goal**: Copy all module documentation with mirrored path structure ```json { "id": "IMPL-003", "title": "Mirror Module Documentation Structure", "status": "pending", "depends_on": ["IMPL-001", "IMPL-002"], "meta": { "type": "skill-mirror", "agent": "@doc-generator", "tool": "gemini" }, "context": { "requirements": [ "Mirror all module documentation from ${docs_path} to ${skill_path}/knowledge/", "Preserve directory structure exactly", "Copy API.md and README.md files", "Maintain path mapping (src/modules/auth/ → knowledge/src/modules/auth/)" ], "docs_path": "${docs_path}", "skill_path": "${skill_path}" }, "flow_control": { "pre_analysis": [ { "step": "load_module_docs", "command": "bash(cat ${session_dir}/.process/module-docs.txt)", "output_to": "all_module_docs" }, { "step": "load_doc_dirs", "command": "bash(cat ${session_dir}/.process/doc-dirs.txt)", "output_to": "doc_directories" } ], "implementation_approach": [ { "step": 1, "title": "Mirror documentation structure", "description": "Copy all module documentation with exact path mirroring", "modification_points": [ "Parse [all_module_docs] for file list", "Parse [doc_directories] for directory structure", "For each file in ${docs_path}:", " - Extract relative path from ${docs_path}", " - Create mirrored directory in ${skill_path}/knowledge/", " - Copy file to mirrored location", "Example: ${docs_path}/src/modules/auth/API.md", " → ${skill_path}/knowledge/src/modules/auth/API.md" ], "logic_flow": [ "Create base directory: ${skill_path}/knowledge/", "For each directory in [doc_directories]:", " - Create ${skill_path}/knowledge/{dir}/", "For each file in [all_module_docs]:", " - Get relative_path from ${docs_path}", " - Copy to ${skill_path}/knowledge/{relative_path}", "Verify all files copied successfully" ], "depends_on": [], "output": "mirrored_docs" } ], "target_files": ["${skill_path}/knowledge/**/*.md"] } } ``` ## Session Structure ``` .workflow/ ├── .active-WFS-skill-20240120-143022 # Active session marker └── WFS-skill-20240120-143022/ ├── IMPL_PLAN.md # Implementation plan ├── TODO_LIST.md # Progress tracker ├── .process/ │ ├── config.json # Session config │ ├── module-docs.txt # Module documentation paths │ └── doc-dirs.txt # Documentation directories └── .task/ ├── IMPL-001.json # SKILL.md generation ├── IMPL-002.json # OVERVIEW.md generation └── IMPL-003.json # Mirror documentation ``` **Config File Structure** (config.json): ```json { "session_id": "WFS-skill-20240120-143022", "timestamp": "2024-01-20T14:30:22+08:00", "path": ".", "target_path": "/home/user/projects/my_app", "project_root": "/home/user/projects", "project_name": "my_app", "tool": "gemini", "regenerate": false, "skip_docs": false, "docs_path": ".workflow/docs/my_app", "skill_path": ".claude/skills/my_app", "existing_docs": 15, "docs_status": "ready", "analysis": { "total_docs": "12", "total_dirs": "3" } } ``` ## Generated SKILL Package **Structure mirrors project source directories**: ``` .claude/skills/ └── {project_name}/ # Project-specific root (e.g., my_app/) ├── SKILL.md # Entry point (IMPL-001) └── knowledge/ ├── OVERVIEW.md # Merged index (IMPL-002) └── [mirrored structure] # Mirrored docs (IMPL-003) ├── src/ │ ├── modules/ │ │ ├── auth/ │ │ │ ├── API.md │ │ │ └── README.md │ │ └── api/ │ │ ├── API.md │ │ └── README.md │ └── utils/ │ └── README.md └── lib/ └── core/ ├── API.md └── README.md ``` ## Execution ```bash # Plan SKILL package generation /memory:skill-memory [path] [--tool gemini|qwen] [--regenerate] [--skip-docs] # Execute tasks /workflow:execute ``` **Common Usage**: - `/memory:skill-memory` - Auto-detect project, use existing docs - `/memory:skill-memory --regenerate` - Force regenerate docs first - `/memory:skill-memory --skip-docs` - Use existing docs only ## Examples ### Example 1: First-time SKILL Package Generation ```bash # Step 1: Plan (this command) /memory:skill-memory # Output: # ✓ Session initialized: WFS-skill-20240120-143022 # ✓ Project: my_app # 📄 Using existing documentation (15 files) # 📊 Documentation Analysis: # - Module docs: 12 # - Directories: 3 # ✅ Tasks generated: IMPL-001, IMPL-002, IMPL-003 # Step 2: Execute /workflow:execute # Result: .claude/skills/my_app/ created with mirrored structure ``` ### Example 2: Update Existing SKILL Package ```bash # Regenerate docs and update SKILL /memory:skill-memory --regenerate # Execute /workflow:execute ``` ### Example 3: SKILL Package Only (No Docs Generation) ```bash # Use existing docs /memory:skill-memory --skip-docs # Execute /workflow:execute ``` ## SKILL.md Template (Generated by IMPL-001) ```markdown --- name: ${project_name} description: Progressive knowledge base for ${project_name} project. Load project context at appropriate detail level based on task requirements. --- # ${project_name} Knowledge Progressive project knowledge with path-mirrored structure. See [OVERVIEW.md](knowledge/OVERVIEW.md) for complete module index. ## Progressive Loading Guide ### Level 0: Minimal Context (~500 tokens) **Use for**: Quick queries, code reviews, bug fixes **Load**: [Project Overview](knowledge/OVERVIEW.md#project-overview) ### Level 1: Standard Context (~2000 tokens) **Use for**: Feature implementation, refactoring **Load**: [Complete Overview](knowledge/OVERVIEW.md) (includes architecture and module index) ### Level 2: Module-Focused (~1500 tokens per module) **Use for**: Working on specific module **Available Modules** (see [OVERVIEW.md](knowledge/OVERVIEW.md#module-index) for full list): - [auth module](knowledge/src/modules/auth/README.md) - [api module](knowledge/src/modules/api/README.md) - [core library](knowledge/lib/core/README.md) **Example**: To work on auth module, load: - [auth/README.md](knowledge/src/modules/auth/README.md) - [auth/API.md](knowledge/src/modules/auth/API.md) ### Level 3: Full Context (⚠️ High token usage) **Use for**: Architecture changes, major refactoring **Load**: Start with OVERVIEW.md, then progressively load modules as needed. ## Path Mapping Knowledge structure mirrors source code: - Source: `src/modules/auth/` → Knowledge: `knowledge/src/modules/auth/` - Source: `lib/core/` → Knowledge: `knowledge/lib/core/` ## Quick Start 1. **Understand project**: Read [OVERVIEW.md](knowledge/OVERVIEW.md) 2. **Explore modules**: See module index in OVERVIEW.md 3. **Deep dive**: Load specific module documentation using mirrored paths ## Updates Regenerate SKILL package after major code changes: \`\`\`bash /memory:skill-memory --regenerate \`\`\` **Generated**: ${timestamp} ``` ## OVERVIEW.md Template (Generated by IMPL-002) ```markdown # ${project_name} - Project Overview **Generated**: ${timestamp} **Modules**: ${module_count} **Files**: ${file_count} **Estimated Tokens**: ${token_estimate} --- ## 📋 Project Overview ${readme_summary} ## 🚀 Quick Start ${examples_key_sections} ## 🏗️ Architecture ${architecture_summary} ## 📦 Module Index ${module_list_with_links} ### src/modules/auth **Path**: `knowledge/src/modules/auth/` **Files**: [README.md](src/modules/auth/README.md), [API.md](src/modules/auth/API.md) **Description**: Authentication and authorization module ### src/modules/api **Path**: `knowledge/src/modules/api/` **Files**: [README.md](src/modules/api/README.md), [API.md](src/modules/api/API.md) **Description**: REST API endpoints and handlers ### lib/core **Path**: `knowledge/lib/core/` **Files**: [README.md](lib/core/README.md), [API.md](lib/core/API.md) **Description**: Core library utilities ## 📊 Statistics - **Total Modules**: ${module_count} - **Documentation Files**: ${file_count} - **Estimated Total Tokens**: ${token_estimate} - **Structure**: Path-mirrored to source code ## 🔗 Navigation All module documentation uses mirrored source paths: - `knowledge/src/modules/auth/` ← mirrors → `src/modules/auth/` - `knowledge/lib/core/` ← mirrors → `lib/core/` See [SKILL.md](../SKILL.md) for progressive loading guide. --- **Version**: 5.0.0 **Last Updated**: ${timestamp} ``` ## Design Philosophy **Path Mirroring**: - ✅ Knowledge structure mirrors source code exactly - ✅ Easy to locate docs for any source file - ✅ Maintains logical organization - ✅ Supports any project structure **Single Overview File**: - ✅ OVERVIEW.md merges: README + EXAMPLES + Architecture + Module Index - ✅ Single file for quick project understanding (~2000 tokens) - ✅ Includes all navigation links to mirrored modules **SKILL-Native Design**: - ✅ SKILL.md as entry point (required by Claude Code) - ✅ Standard Markdown links for progressive loading - ✅ Claude loads referenced files on-demand - ✅ Human-readable OVERVIEW.md for module discovery **Progressive Loading**: - Level 0: OVERVIEW.md#project-overview (~500 tokens) - Level 1: Full OVERVIEW.md (~2000 tokens) - Level 2: Specific modules (~1500/module) - Level 3: Full context (load progressively as needed) --- **Version**: 5.0.0 (Path-Mirrored) **Last Updated**: 2025-01-03 **Dependencies**: `/memory:docs`, `/workflow:execute`, `gemini` CLI