Summarize Folder

Summarize Folder

Purpose

You are a folder summarizer. Given a folder path and a detail level, you will read the folder's contents and produce a clear, plain-English summary of what is in it — what each file does, how things are organized, and any patterns or conventions worth noting.

Arguments

This skill receives arguments through the following variables:

• $ARGUMENTS — the full argument string (e.g., "src/components detailed")
• $1 — the folder path to summarize (e.g., "src/components")
• $2 — the detail level: brief or detailed (e.g., "detailed")

Example invocation: /summarize-folder src/components detailed

Built-in Variables

These variables are available to you automatically:

• $CLAUDE_SKILL_DIR — absolute path to the directory containing this SKILL.md file
• $SKILL_DIR — same as $CLAUDE_SKILL_DIR (alias)
• $CLAUDE_DIR — path to the .claude/ directory in the project root

Instructions

1. Parse the arguments: $1 is the folder path, $2 is the detail level (brief or detailed)
2. List the folder's contents — files, subdirectories, and their sizes
3. Read key files to understand what they do (prioritize entry points, README files, and configuration)
4. Identify patterns: naming conventions, groupings, shared dependencies
5. Produce the summary at the requested detail level
6. Write the summary to output/{folder-name}-summary.md

Workflow

1. List the folder contents:

   • Use Glob to find all files in the folder
   • Count files, subdirectories, and total items
   • Note any unusually large or deeply nested structures

2. Read and analyze key files:

   • For brief: read only top-level files and directory names
   • For detailed: read files in subdirectories too, note imports and exports

3. Produce the summary:

   • Start with a one-sentence overview of the folder's purpose
   • List each file or subdirectory with a short description
   • Note any patterns (naming conventions, shared structure, etc.)
   • For detailed: include relationships between files and notable code patterns

4. Write the output to output/{folder-name}-summary.md

5. Invoke the /write-logs skill to log input, decisions, and output:

component: summarize-folder
type: skill
entries:
  - level: DEBUG
    message: "[RAW INPUT] folder=$1, detail=$2"
  - level: INFO
    flag: --decision
    message: "Considered: <approaches>. Chose: <approach>. Why: <reason>"
  - level: DEBUG
    message: "[OUTPUT] <summary of what was produced>"

Report

When finished, return:

• The summary (inline in the response)
• File and subdirectory count
• Key patterns identified
• Any areas that were unclear or need human review
• The file path where the summary was saved