# Folder Studio

> 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.

- Skill: `arnie016/folder-studio` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add arnie016/folder-studio`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arnie016/folder-studio/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Arnie016 (https://skillmd.com/u/arnie016)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/arnie016/folder-studio

---


# 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

1. Read `references/project-map.md` for the split target layout and the main folder-skin files.
2. Run `bash scripts/run_folder_studio.sh doctor`.
3. Run `bash scripts/run_folder_studio.sh inspect`.
4. Use `bash scripts/run_folder_studio.sh test` after analysis, rendering, or UI changes.
5. Use `bash scripts/run_folder_studio.sh build` when you need the app product.
6. 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.