Agent Workspace Manager

Organize and maintain agent workspace directories by initializing structure, classifying files, auditing placement, cleaning content, and suggesting expansions.

Security Scan

The skill's description matches its behavior (organizing and auditing workspaces) but its instructions give broad discretion to read, move, rename, archive, and potentially delete user files without clear confirmation steps and refer to helper scripts that are not included — this mismatch and potential for destructive action warrants caution.

Purpose & Capability

The name/description (manage and maintain agent workspace directories) aligns with the instructions: classification rules, structure templates, duplicate detection, and health checks. The skill does not request unrelated credentials or binaries. Minor inconsistency: the docs mention helper scripts (e.g., workspace_audit.py) and workflows that expect executable tooling, but no code files or install steps are provided.

Instruction Scope

SKILL.md instructs the agent to scan workspaces, run shell find/grep commands, detect duplicates, move/archive files, rename files, and 'prune' redundant content. Those actions necessarily read and modify arbitrary files in the user's workspace(s). The instructions are permissive/vague about deletion and automation (e.g., 'Prune: Remove truly redundant content'), and they do not require explicit user confirmation or a dry-run mode. The skill also references tools/scripts (workspace_audit.py) that are not bundled, creating ambiguity about how actions are intended to be executed.

Install Mechanism

Instruction-only skill with no install spec and no bundled code — this is low installation risk. Because there is no install, no external binaries are being pulled, but the skill expects the agent to execute filesystem and shell operations at runtime.

Credentials

The skill requests no environment variables, no credentials, and no config paths — appropriate and proportional for a local workspace management task. It does not reference external endpoints or secrets.

Persistence & Privilege

The skill is not marked always:true, but it instructs the agent to modify user files (mv, rename, archive, and potentially delete). Combined with the platform default that agents may invoke skills autonomously, this increases the blast radius: an autonomously-invoking agent could apply destructive changes if the skill is used without explicit safeguards. The SKILL.md lacks firm safeguards (confirmation prompts, dry-run only by default), which makes persistent or repeated modifications risky.

What to consider before installing

This skill appears to do what it says (organize and audit workspace files) but it gives the agent broad permission to read and modify your files and is ambiguous about automatic deletion or renaming. Before installing or running it: 1) Back up any important workspaces. 2) Require (or edit the SKILL.md to add) an explicit dry-run/read-only mode and mandatory user confirmation before any move/rename/delete operations. 3) Test on a non-production/sample workspace first. 4) Ensure the agent's file-system permissions are limited to only the directories you want managed. 5) Note the skill references helper scripts (e.g., workspace_audit.py) that are not included — ask the publisher how those are supplied and audited. If you need automatic cleanup, insist on clear safeguards (confirmation prompts, logs, and an easy undo/archive policy) before allowing this skill to run autonomously.

Overview

This skill provides a systematic approach to organizing and maintaining agent workspace directories. It ensures documents are placed in appropriate functional directories, detects structure issues, and maintains content freshness.

Core Capabilities

1. Structure Initialization

Initialize a standardized workspace structure for new agents:

workspace/
├── MEMORY.md              # Core memory index (agent reads this first)
├── memory/                # Time-based memory fragments
├── knowledge/             # Stable domain knowledge
│   └── sql/               # Core business SQL (NEW)
├── tasks/                 # Temporary/project-specific items
├── decisions/             # Decision records with rationale
├── preferences/           # User preferences and settings
├── archives/              # Expired but preserved content
│   └── sql_versions/      # Historical SQL versions (NEW)
├── templates/             # Reusable templates
│   └── sql/               # Reusable SQL templates (NEW)
└── scripts/               # Scripts and utilities (NEW)

Usage: When setting up a new workspace, create this structure to enable efficient information retrieval.

2. Document Classification

Every document must be placed in a directory matching its functional purpose:

Document Type	Directory	Characteristics
Events, conversations, time-based records	memory/	Has timestamp, may expire
Domain knowledge, technical docs	knowledge/	Stable, long-term valid
Core business SQL	knowledge/sql/	Long-term used SQL
Tasks, todos, project items	tasks/	Temporary, project-bound
Important choices with rationale	decisions/	Decision history, traceable
User habits, preferences	preferences/	Personalization config
Expired but valuable content	archives/	Preserved for reference
Historical SQL versions	archives/sql_versions/	Deprecated SQL
Reusable patterns, templates	templates/	Copy-paste ready
Reusable SQL templates	templates/sql/	Standard queries
Scripts (.py, .sh)	scripts/	Utility scripts

Classification Rule: Before creating any document, determine its primary function. Place it in the matching directory. Never place files in incorrect directories.

3. Code File Classification (NEW)

Code files (SQL, Python, Shell, etc.) must follow these rules:

File Type	Directory	Purpose
.sql (core business)	knowledge/sql/	Long-term used SQL queries
.sql (templates)	templates/sql/	Reusable standard queries
.sql (historical)	archives/sql_versions/	Deprecated SQL versions
.py (scripts)	scripts/	Python utility scripts
.sh (scripts)	scripts/	Shell utility scripts
.json (config)	config/ or root	Configuration files

SQL File Naming Rules:

• ✅ DO: Use semantic names: 神策宽表转JSON.sql
• ❌ DON'T: Use version suffixes: 神策宽表转JSON_v1.sql, 神策宽表转JSON_最终版.sql
• ❌ DON'T: Use functional suffixes: 神策宽表转JSON_修正版.sql, 神策宽表转JSON_完整版.sql

When to Create New Version:

• If SQL needs update, modify the existing file
• Archive old version to archives/sql_versions/ with timestamp if needed
• Keep only ONE active version in knowledge/sql/

4. Workspace Health Check

Run health checks to identify issues:

• Misplaced files: Documents in wrong directories
• Duplicates: Similar content in multiple files
• Code file duplicates: Multiple versions of same SQL/script (NEW)
• Stale content: Outdated information that needs refresh
• Orphan files: Files without clear purpose or references
• Naming violations: Files with version suffixes (NEW)

Output: A report with specific file recommendations.

5. Duplicate File Detection (ENHANCED)

Detect duplicate files using these methods:

For Document Files (.md)

1. Name similarity: Files with similar names (e.g., report-v1.md and report-v2.md)
2. Content similarity: Files with >80% content overlap
3. Functional similarity: Files serving the same purpose

For Code Files (.sql, .py, .sh)

1. Version suffixes: Files with _v1, _v2, _final, _修正版, _完整版 etc.
2. Same functionality: Multiple SQL files for the same transformation/query
3. Timestamp in name: Files with timestamps that could be archived

Detection Command:

# Find SQL files with version suffixes
find . -name "*.sql" -type f | grep -E "(_v[0-9]|_最终|_完整|_修正|_修复)"

# Find duplicate MD files by name pattern
find . -name "*.md" -type f | grep -E "(_v[0-9]|_最终|_完整)"

6. Content Freshness Maintenance

Maintain document freshness through:

1. Merge: Combine duplicate or similar files, preserving all key information
2. Archive: Move expired content to archives/ with timestamp
3. Refresh: Update stale knowledge with latest information
4. Prune: Remove truly redundant content (only when no key info is lost)
5. Consolidate: Merge multiple versions into one, archive old versions (NEW)

Safety Principle: Never delete content that might contain unique valuable information. Archive instead.

7. Structure Extension Detection

When existing directories cannot accommodate new functional needs:

1. Detect: Identify documents that don't fit current categories
2. Propose: Suggest new directories or structure reorganization
3. Implement: Create new directories following naming conventions
4. Document: Update this skill's structure reference

Example: If knowledge/ grows too large with mixed domain types, split into knowledge/product/, knowledge/technical/, knowledge/business/.

Workflow

For New Workspace Setup

1. Determine agent type (personal assistant, project manager, knowledge base, etc.)
2. See references/structure-templates.md for appropriate template
3. Create directories and initial files
4. Set up MEMORY.md as the entry point

For Workspace Audit

1. Scan all files in workspace
2. Classify each file by function
3. Check for misplaced files
4. Detect duplicate files (including code files)
5. Generate health report
6. Propose fixes for user approval

For Content Cleanup

1. Identify duplicates/similar files
2. Detect version-suffixed files (NEW)
3. Propose merge candidates
4. Identify expired content
5. Archive with preservation
6. Verify no key information is lost

For Code File Cleanup (NEW)

1. Scan all code files (.sql, .py, .sh)
2. Identify files with version suffixes
3. Determine the latest/best version
4. Keep latest in appropriate directory (knowledge/sql/ or templates/sql/)
5. Archive old versions to archives/sql_versions/
6. Remove version suffixes from filenames

Resources

references/

• structure-templates.md - Pre-defined workspace templates for different agent types
• classification-rules.md - Detailed rules for document classification (UPDATED)

Multi-Agent Sharing

This skill is designed to be copyable across agents:

1. Install the same skill in multiple agent workspaces
2. Each agent follows the same structure conventions
3. Shared knowledge can be exchanged between agents
4. Consistent structure enables cross-agent collaboration

Changelog

v1.1 (2026-03-25)

• Added code file classification rules (SQL, Python, Shell)
• Added duplicate file detection methods
• Added file naming best practices
• Enhanced workspace health check to detect version-suffixed files
• Added SQL-specific cleanup workflow