directory-structure

name	directory-structure
description	Generate a professional ASCII directory structure in Markdown. Use this before modifying a project to understand its layout, identify key files, visualize or document the file structure of a directory, project or codebase.
version	1.0.0
author	Human Skill Team
tags	["documentation","structure","visualization","tree","file-system"]
trigger_patterns	["directory structure","file tree","show structure","visualize folder","project structure","codebase tree","list files","dir structure"]

Directory Structure Generator

When to Use

Activate this skill when the user asks to:

• Understand the directory structure of a project
• Show the directory structure of a project
• Visualize the file tree of a codebase
• Document the folder organization
• List files in a structured format
• Generate a markdown representation of a directory

The tree_gen Tool

This skill uses the tree_gen tool to create Markdown-formatted directory trees.

📝 PARAMETERS:

• input_path: REQUIRED - Absolute path of the directory to scan.
• output_path: OPTIONAL - Where to write the output file. Defaults to input_path.
• file_name: OPTIONAL - Output filename. Defaults to {dir_name}_structure.md.
• layout: OPTIONAL - "vertical" (default, classic top-down) or "horizontal" (top-level dirs side-by-side).
• max_depth: OPTIONAL - How many levels deep to recurse. Default: 4. Set 0 for unlimited.
• use_gitignore: OPTIONAL - Read and apply .gitignore rules. Default: true.
• ignored_path: OPTIONAL - Comma-separated absolute paths to exclude.
• ignored_extensions: OPTIONAL - Comma-separated extensions to exclude (e.g. .log,.tmp).

Decision Tree: How to Use This Tool

1️⃣ Identify the Scope

Ask yourself:

• Is this a small project (<100 files)?
• Is this a large codebase (>1000 files)?
• Does the user want the full project or a specific folder?
• Do they want all files or just source code?

2️⃣ Choose the Right Strategy

Scenario	Strategy
Small project	Scan everything, minimal ignores
Medium web app	Ignore node_modules, build outputs
Large monorepo	Target specific directories, aggressive ignores
Root-level scan	Always ignore knowledge, chats, workdir
Source code only	Ignore all non-code files

---

📋 HOW TO CALL THIS TOOL:

The agent executes execute.py with the JSON payload passed directly as a string argument:

human-skills '{"tool_name": "tree_gen", "tool_args": {"input_path": "home/user_name/workdir/my-project", "output_path": "home/user_name/workdir/my-project", "file_name": "PROJECT_MAP", "layout": "vertical", "max_depth": "3", "use_gitignore": "true", "ignored_path": "home/user_name/workdir/my-project/tests, home/user_name/workdir/my-project/docs", "ignored_extensions": ".csv,.json"}}'

Which maps to this JSON payload:

{
    "tool_name": "tree_gen",
    "tool_args": {
        "input_path":         "home/user_name/workdir/my-project",
        "output_path":        "home/user_name/workdir/my-project",
        "file_name":          "PROJECT_MAP",
        "layout":             "vertical",
        "max_depth":          "3",
        "use_gitignore":      "true",
        "ignored_path":       "home/user_name/workdir/my-project/tests, home/user_name/workdir/my-project/docs",
        "ignored_extensions": ".csv,.json"
    }
}

Expected output:

✅ Directory Structure Generated.
   Path    : home/user_name/workdir/my-project/PROJECT_MAP.md
   Layout  : vertical
   Depth   : 3 levels
   Lines   : 33
   Size    : 986.0 B
   Dirs    : 15
   Files   : 26
   Scanned : 282.2 KB

⚠️ IMPORTANT NOTES:

• All values in tool_args must be strings (e.g. "max_depth": "3", not 3).
• Common patterns (.git, node_modules, __pycache__, binaries, media) are auto-ignored.
• If output exceeds 500 lines, a tip is shown to reduce max_depth or add ignored_path.
• Default filename: {dir_name}_structure.md (e.g. my-project_structure.md).

Scenario-Based Instructions

📁 Scenario 1: Small Project (< 100 files)

When: Scanning a small Python project, simple script, or personal library where we want to show almost everything, ignoring only cache and git files, using the default depth of 4.

What to ignore: Minimal - only critical clutter

• __pycache__, .git, .venv, node_modules

Example:

human-skills '{
    "tool_name": "tree_gen",
    "tool_args": {
        "input_path": "home/user_name/workdir/my-folder",
        "ignored_path": "__pycache__, .git, .venv, .env, .gitkeep, .DS_Store, .log, .tmp"
    }
}'

---

📦 Scenario 2: Medium Web Application (100–1000 files)

When: Scanning a typical React, Vue, or Node.js web app where we need to ignore dependencies and build outputs for a cleaner overview.

What to ignore: Dependencies and build artifacts

• node_modules, dist, build, coverage
• .next, .nuxt, .cache
• __pycache__, .pytest_cache

Example:

human-skills '{
    "tool_name": "tree_gen",
    "tool_args": {
        "input_path": "home/user_name/workdir/my-webapp",
        "ignored_path": "node_modules, dist, .next, coverage, __pycache__, .git, .venv, .env, .gitkeep, .DS_Store, .log, .tmp"
    }
}'

---

🏢 Scenario 3: Large Codebase/Monorepo (> 1000 files)

When: Scanning an enterprise application, complex system, or a specific package within a large monorepo. We must ignore tests and dependencies to keep the output manageable.

Strategy:

1. Never scan the entire root - it will be too large
2. Target specific packages/modules one at a time
3. Use aggressive ignores

What to ignore: Everything non-essential

• All dependencies: node_modules, vendor, .venv
• All build outputs: dist, build, out, target
• All test files and coverage
• All media and assets

Example - Scan specific package:

human-skills '{
    "tool_name": "tree_gen",
    "tool_args": {
        "input_path": "home/user_name/workdir/monorepo/packages/backend",
        "ignored_path": "node_modules, dist, coverage, tests, __tests__, .git"
    }
}'

Example - Multiple targeted scans:

# First: Backend
human-skills '{
    "tool_name": "tree_gen",
    "tool_args": {
        "input_path": "home/user_name/workdir/monorepo/packages/backend",
        "output_path": "home/user_name/workdir/docs",
        "ignored_path": "node_modules, dist, tests"
    }
}'

# Then: Frontend (separate call)
human-skills '{
    "tool_name": "tree_gen",
    "tool_args": {
        "input_path": "home/user_name/workdir/monorepo/packages/frontend",
        "output_path": "home/user_name/workdir/docs",
        "ignored_path": "node_modules, .next, public/assets"
    }
}'

---

🌍 Scenario 4: Root-Level Scan (home/user_name/ or system root)

When: Generating a system-wide or root workspace overview. We must aggressively ignore huge directories like workdir, chats, and knowledge to prevent overflowing the token limit.

⚠️ CRITICAL RULES:

1. ALWAYS ignore these paths for home/user_name/:

   • home/user_name/workdir (user projects - scan separately)
   • home/user_name/chats (conversation history)
   • home/user_name/knowledge/main (large knowledge base)
   • home/user_name/memory/default (vector database)

2. What to show:

   • Agent configurations
   • Skills
   • System configuration files
   • Project metadata

Example:

human-skills '{
    "tool_name": "tree_gen",
    "tool_args": {
        "input_path": "home/user_name/",
        "ignored_path": "home/user_name/workdir, home/user_name/chats, home/user_name/knowledge/main, home/user_name/memory/default"
    }
}'

---

🎯 Scenario 5: Specific Folder Deep Dive

When: The user requests a deep dive into ONE specific directory (e.g., "show me the src folder structure"). We need to show all source files with minimal filtering.

Strategy:

• Target ONLY that folder
• Show everything inside (minimal ignores)
• Good for code review, onboarding, documentation

What to ignore: Only cache and temporary files

• __pycache__, .pytest_cache
• *.pyc, .DS_Store

Example:

human-skills '{
    "tool_name": "tree_gen",
    "tool_args": {
        "input_path": "home/user_name/workdir/my-app/src",
        "ignored_path": "__pycache__, .pytest_cache"
    }
}'

---

📝 Scenario 6: Documentation Purpose

When: Preparing structure output for a README, documentation, or architectural diagram. We should only show source code and configuration, strictly hiding test suites and build outputs.

Strategy:

• Focus on source code and configuration
• Ignore everything that's not essential to understanding
• Keep output clean and professional

What to ignore:

• All dependencies and node_modules
• All build outputs and artifacts
• All test files (unless specifically asked)
• All media and binary files
• All local development files (.env, .vscode)

Example:

human-skills '{
    "tool_name": "tree_gen",
    "tool_args": {
        "input_path": "home/user_name/workdir/my-project",
        "output_path": "home/user_name/workdir/my-project/docs",
        "ignored_path": "node_modules, dist, build, tests, __tests__, coverage, .git, .vscode, public/images"
    }
}'

---

Quick Reference: Common Ignore Patterns

By Language/Framework

Python Projects:

__pycache__, .pytest_cache, .venv, .mypy_cache, *.pyc, dist, build

Node.js Projects:

node_modules, dist, build, .next, .nuxt, coverage, .cache

Full-Stack Projects:

node_modules, __pycache__, dist, build, .venv, coverage, .git

By Purpose

Code Review (show source only):

node_modules, dist, build, tests, __tests__, coverage, docs, public

Documentation (clean view):

node_modules, dist, .git, .vscode, tests, coverage, *.min.js, assets

Deployment Check (show build outputs):

node_modules, .git, src, tests (only ignore source and development files)

---

Best Practices

✅ DO:

1. Always check project size first - use list_dir to estimate
2. For large projects, scan specific directories - never scan massive roots
3. For home/user_name/, ALWAYS ignore workdir and chats
4. Match ignores to user's intent - code review vs documentation needs different ignores
5. Present the output - read structure.md and show it to user after generation

❌ DON'T:

1. Don't scan home/user_name/workdir directly - ask which project inside it
2. Don't forget node_modules - it can have 100k+ files
3. Don't ignore too little - output will be overwhelming
4. Don't use relative paths in ignored_path - always use absolute paths
5. Don't generate without understanding user's goal - ask if unclear

---

Common Issues & Solutions

Issue	Solution
"Output is 10,000+ lines"	Add more aggressive ignores or target smaller directory
"Empty structure.md"	Path doesn't exist or all files were ignored
"Still showing node_modules"	Use absolute path: /full/path/to/node_modules
"Missing important files"	Review ignored_path - may have over-filtered

Troubleshooting

Issue: Empty Output

Cause: Directory doesn't exist or is empty. Solution: Verify the path exists with list_dir first.

Issue: Too Much Output

Cause: Not enough ignore patterns. Solution: Add more paths/extensions to ignore, or generate subdirectories separately.

Issue: File Not Found

Cause: Output directory doesn't exist. Solution: Create output directory first or use existing path.

Output Format

The generated structure.md file contains:

• Markdown-formatted tree structure
• File and folder counts
• List of ignored paths/patterns
• Generation timestamp

Example output:

## file tree
/my-project/
├── src/
│   ├── main.py
│   └── utils/
│       └── helpers.py
├── tests/
│   └── test_main.py
└── README.md