| name | folder-studio |
| description | Build, run, troubleshoot, or extend a Folder Studio macOS menu bar app that reads folder context, suggests engravings, colors folders, previews Finder-style skins, and applies custom icons. Use when Codex needs to work on a workspace containing `FolderStudioApp`, keep Folder Studio separate from Cursor Studio, regenerate the Xcode project, or validate the `FolderStudio` scheme and tests. |
Folder Studio
Use this skill for a Folder Studio workspace. If the current repo contains FolderStudioApp and project.yml, use that workspace by default. Otherwise, pass --workspace /path/to/workspace to the runner script.
Quick Start
- Read
references/project-map.md for the split target layout and the main folder-skin files.
- Run
bash scripts/run_folder_studio.sh doctor.
- Run
bash scripts/run_folder_studio.sh inspect.
- Use
bash scripts/run_folder_studio.sh test after analysis, rendering, or UI changes.
- Use
bash scripts/run_folder_studio.sh build when you need the app product.
- Use
bash scripts/run_folder_studio.sh open to jump into Xcode.
Workflow
Product Boundary
- Keep
FolderStudio focused on context-aware folder skins, not cursor packs.
- Folder Studio owns:
- folder analysis
- dominant category detection
- engraving suggestions
- color palette and finish controls
- Finder icon preview and apply/reset behavior
- Do not blend cursor-pack planning back into this target. That belongs to
CursorStudio.
UI Guidance
- Keep the menu bar panel compact and professional.
- The app should make these signals visible immediately:
- folder name and dominant category
- key content counts
- current engraving, badge, and palette choices
- whether the icon is ready to apply or reset
Editing Guidance
- Read
project.yml before changing targets or schemes.
- Folder analysis and icon rendering belong in
FolderStudioApp/Sources/Services/.
- Panel state and persistence belong in
FolderStudioApp/Sources/App/.
- Compact panel UI belongs in
FolderStudioApp/Sources/Views/.
- If category heuristics or palette behavior change, update the tests too.
Validation
- Run
doctor if the workspace or tools are uncertain.
- Run
test after changing analysis, builders, render logic, or panel behavior.
- Run
build after target or view changes.
- Preserve Finder icon behavior:
- preview should match the generated icon payload
- apply should set a custom folder icon
- reset should clear it back to Finder defaults
Resources
scripts/run_folder_studio.sh: workspace detection and local doctor, inspect, generate, open, build, and test commands.references/project-map.md: target map, main files, analysis and icon contract, and validation notes.
