file-classification-manager

Manages synchronized dual directories per project, automatically classifying and routing files into permanent outputs and temporary intermediates based on ty...

Security Scan

The skill generally matches its stated purpose (organizing project vs temp files) but contains multiple implementation and instruction mismatches that could lead to accidental or intentional file moves/exposure if used without caution.

Purpose & Capability

The skill's code and SKILL.md both aim to classify and route project vs temporary files and create synchronized directories, which is coherent. However, the module exports a class (FileClassificationManager) while SKILL.md shows top-level API functions (e.g., classify_and_route_file) and examples that import and call functions directly — this mismatch will cause integration/runtime confusion. Also SKILL.md lists extra integration behaviors (subagent attachment handling, logging to memory/YYYY-MM-DD.md, safety confirmations) that are not implemented in index.js.

Instruction Scope

The implementation reads all regular files from the workspace root and moves them (fs.readFile + fs.rename) without implementing the SKILL.md's promised confirmation, backup, or logging behavior. classifyAndRouteFile will rename/move any filepath passed in (there is no validation that the source path is inside the declared workspace root), which means if code is invoked with an absolute path and the runtime has permission it could move arbitrary files on the host. The module also reads an environment variable (OPENCLAW_WORKSPACE) used as workspaceRoot but that env var is not documented in requires.env.

Install Mechanism

No install spec is provided and there are no external dependencies. This is an instruction-only skill with a small JS module — lowest install risk.

Credentials

The skill declares no required environment variables or credentials, which is appropriate. However, the code uses process.env.OPENCLAW_WORKSPACE as a workspace override without documenting it in SKILL.md or requires.env; that undocumented env access should be declared. No secrets or external service credentials are requested.

Persistence & Privilege

The skill is not force-included (always: false) and can be invoked by the agent as normal. It does request the ability to move files on disk (via fs.rename), which is consistent with its purpose but increases impact if misused — this is a behavioral risk rather than an elevated platform privilege.

What to consider before installing

This skill appears to implement file classification and moving, but there are several mismatches and missing safety controls you should consider before installing or allowing autonomous use: - Integration mismatch: SKILL.md shows top-level functions, but the code exports a class; callers will need to instantiate FileClassificationManager rather than calling free functions as documented. Test integration in a sandbox first. - File-move risk: The code will rename/move any filepath passed in and scans the workspace root for files to move. There is no check that the source file is inside the workspace root, no confirmation prompts, no automatic backups, and no operation logging despite those being described in SKILL.md. If the agent is given or constructs an absolute path to sensitive files and runs with sufficient permissions it could move them into the workspace. Run this only with least privilege and in a safe test workspace. - Undeclared env var: The module reads OPENCLAW_WORKSPACE to set the root but SKILL.md and requires.env do not document this. If you rely on that override, declare and restrict it explicitly. - Missing promised safeguards: SKILL.md promises backups, confirmation before delete, and logging, but index.js does not implement these. Ask the author to add/implement: (1) explicit validation that source paths are contained within the workspace root, (2) dry-run or confirmation prompts before moving critical files, (3) automatic backups or copies (not move) for critical file classes, and (4) an append-only operation log file as described. If you want to proceed: (a) test in an isolated sandbox workspace, (b) inspect and run the module with a non-privileged user, (c) require that the author update the package to declare OPENCLAW_WORKSPACE and to implement the missing safety behaviors, and (d) avoid enabling autonomous invocation until those fixes are in place.

File Classification Manager Skill

Description

Dual-purpose intelligent file classification system that manages BOTH project outputs AND temporary files with synchronized directory structures. Automatically organizes files into proper projects/ and temp/ directories based on content type, purpose, and project context. Prevents file clutter in workspace root by enforcing structured dual-storage.

Key Principle: Synchronized Dual Storage

Every project has TWO corresponding directories:

• projects/{project_name}/ - For permanent, valuable outputs (reports, final documents, deliverables)
• temp/{project_name}/ - For temporary, intermediate files (scripts, extracted data, cache, working files)

Both directories are automatically created together and share the same project name to maintain clear association between final outputs and their supporting temporary files.

Capabilities

• Dual Directory Management: Simultaneously manages projects/ (outputs) and temp/ (intermediate files) directories
• Synchronized Project Naming: Ensures identical project names across both storage areas for clear association
• Purpose-Based Classification: Automatically determines whether a file belongs in outputs vs intermediate based on content and file patterns
• Project Detection: Identifies project context from user input or file content
• Automatic Structure Creation: Creates standardized dual directory structure for any new project
• Smart File Routing: Routes files to correct subdirectories in the appropriate storage area (projects vs temp)
• Legacy File Cleanup: Migrates existing misplaced files to proper dual-storage locations
• Cross-Agent Compatibility: Works with subagents and ACP coding sessions

Usage Scenarios

• When generating new files (reports, scripts, data)
• When processing files via other skills (PDF Extract, Summarize Pro, etc.)
• When organizing existing workspace clutter
• When working with multiple concurrent projects

API Functions

classify_and_route_file(filepath, project_context)

Routes a file to the appropriate directory based on its type and project context.

Parameters:

• filepath: Path to the file to be classified
• project_context: Project name or context object

Returns: Final destination path

ensure_project_structure(project_name)

Creates the standard directory structure for a project if it doesn't exist.

Parameters:

• project_name: Name of the project (alphanumeric + underscores only)

Directory Structure Created:

projects/{project_name}/
├── outputs/
└── assets/
temp/{project_name}/
├── intermediate/
└── cache/

detect_project_from_content(content)

Analyzes file content to determine likely project association.

Parameters:

• content: File content or metadata to analyze

Returns: Suggested project name or null

cleanup_workspace_root()

Scans workspace root for misplaced files and routes them appropriately.

Returns: Migration report

File Type Classification Rules

Files are automatically routed to the CORRECT storage area based on their purpose:

🎯 Projects Storage (Permanent Outputs)

File Pattern	Destination	Purpose
*_review.md, *_literature.md	projects/{project}/outputs/	Literature reviews and analyses
final_*.md, comprehensive_*.md	projects/{project}/outputs/	Final reports and deliverables
summary_*.md, conclusion_*.md	projects/{project}/outputs/	Executive summaries and conclusions

⚡ Temp Storage (Temporary Files)

File Pattern	Destination	Purpose
*.py, *.js, *.m	temp/{project}/intermediate/	Analysis and processing scripts
*_content.txt, *_extract.txt	temp/{project}/intermediate/	Extracted raw content
*.pdf, *.docx	temp/{project}/intermediate/	Source documents for processing
*.mat, *.csv, *.json	temp/{project}/intermediate/	Intermediate data files
*.png, *.jpg, *.gif	temp/{project}/intermediate/	Generated or processed images
cache_*, temp_*	temp/{project}/cache/	Cached API responses and temporary data

Key Rule: The system maintains synchronized project names - if a file goes to projects/dipleg_review/outputs/, its supporting files go to temp/dipleg_review/intermediate/.

Integration Guidelines

For Other Skills:

When developing skills that generate files, import this skill and use:

const fcm = require('file-classification-manager');
const outputPath = fcm.classify_and_route_file(filename, projectContext);

For Subagents:

Pass project context when spawning subagents:

sessions_spawn({
  task: "Process documents",
  runtime: "subagent",
  attachments: [{name: "fcm_config.json", content: JSON.stringify({project: "my_project"})}]
})

Safety Rules

• Never delete files without confirmation
• Always backup before moving critical files
• Preserve original file timestamps and metadata
• Log all file operations to memory/YYYY-MM-DD.md

Error Handling

• If project context is ambiguous, prompt user for clarification
• If file type is unrecognized, place in temp/general/intermediate/
• If directory creation fails, fall back to safe temporary location

Examples

Basic Usage:

// Classify a literature review file
const result = classify_and_route_file("brain_dipleg_review.md", "dipleg_research");
// Result: "projects/dipleg_research/outputs/brain_dipleg_review.md"

Project Setup:

// Ensure project structure exists
ensure_project_structure("pv_topology_analysis");
// Creates projects/pv_topology_analysis/ and temp/pv_topology_analysis/ directories

Workspace Cleanup:

// Clean up misplaced files
const report = cleanup_workspace_root();
console.log(report.movedFiles); // Array of successfully moved files

Version

1.0.0

Author

OpenClaw Assistant

License

MIT