AGENT SKILL

tree_gen

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.

License 许可
MIT
最近更新
2026-11-11
Stars
★ 3
Forks
0

01 前言 Front Matter

name
tree_gen
tags
[ "documentation", "structure", "visualization", "tree", "file-system" ]
author
Human Skill Team
version
1.0.0
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.
trigger_patterns
[ "directory structure", "file tree", "show structure", "visualize folder", "project structure", "codebase tree", "list files", "dir structure" ]

02 资源文件 1

03 SKILL.md 正文

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

04 同仓库更多 Skills

mdnaimul22
mdnaimul22/human-skills

system-lifecycle-designer

Universal architectural methodology for designing granular, atomic, and sub-atomic lifecycles and end-to-end workflows for single functionality integrations across any domain (daemons, batch jobs, request transactions, resource pools). Provides patterns for deterministic identity, pre-commit validation, differential reconciliation, sticky leasing, state machines, transactional persistence, and closed-loop feedback.

★ 3
mdnaimul22
mdnaimul22/human-skills

style-sampling

Make a new episode in a proven video style - Collage Explainer, Finance Explainer, Animated Science Explainer, 3D Brand Explainer, 3D True Crime - on the person's topic. Use for "an episode of", "in the style of", "sample this style", 「用这个风格做一集」. One video to copy is reverse-any-video.

★ 3
mdnaimul22
mdnaimul22/human-skills

reverse-any-video

Rebuild any video file as an editable HyperFrames project - motion graphics, talking heads, live action or AI-generated footage - checked against the original frame by frame. Use to reverse, recreate, remake, replicate or copy a video, or 「复刻这个视频」「照着这个视频做一个」.

★ 3
mdnaimul22
mdnaimul22/human-skills

typescript-patterns

TypeScript patterns for strict, type-safe, maintainable code in modern TypeScript and JavaScript applications. Covers strict compiler configuration, type design, narrowing, discriminated unions, generics, async and error handling, module boundaries, dependency hygiene, and type-level testing. Use when writing or reviewing TypeScript or JavaScript code.

★ 3
mdnaimul22
mdnaimul22/human-skills

test-collaboration

Inventory and govern a project's test assets. Connect requirements, business rules, risks, bugs, and cross-boundary contracts to stable TEST-IDs and executable evidence in the repository's existing test registry or TESTS.md. Use for test inventory, test gap analysis, unit/integration/contract/E2E/smoke classification, bug-to-test regression protection, consumer/provider contract testing, test-necessity review, and pre-delivery evidence review.

★ 3
mdnaimul22
mdnaimul22/human-skills

story-lifecycle

Manage a file-based epic → story → sprint development loop without requiring an external project management tool. Creates and tracks epics, breaks them into user stories, assigns them to sprints, and drives implementation story by story. Use when starting a new feature initiative or when the team has no Jira/Linear/Taiga but needs structured delivery tracking.

★ 3