Auto-load project context from .frame — orient first, then explore with the frame CLI. Use whenever a `.frame/` directory is present in the project, or when the user asks to load project context or understand the project structure.
Load semantic project context using the frame CLI before doing any non-trivial work in a frame-enabled project. Frame is denser than reading source files — purposes are pre-summarized, structure is pre-extracted.
Companion to frame-populate (which fills missing purposes). This skill is read-only.
.frame/ directory at its rootIf .frame/ is missing, this skill does not apply — fall back to normal exploration.
Run:
frame read --json
From the output, note:
totalFiles, totalSymbols, languageComposition — size and stackneedsGeneration — count of unpopulated purposes. If > 0, tell the user purposes are partially populated and suggest frame-populate to fill gaps. Proceed regardless.parseErrors — if > 0, identify which files (look for parseError !== null in the files[] array) and remember to fall back to raw Read for thosefiles[] array — paths, languages, purposes, exports, imports, externalImports. This is your working map. Note: symbols are stripped from frame read output — use frame read-file <path> --json to get symbol-level detail. The imports field lists internal (project-relative) paths only; reach for frame deps when you need the reverse graph (importedBy) or want internal + external deps surfaced together.Do NOT drill into every file at this stage. The skeleton is the orientation; deeper reads happen on demand.
frame read errors with "No frame found": tell the user to run frame generate first, then stop.frame command not found: tell the user the frame CLI is not installed, point them at the project README, then stop.needsGeneration > 0: mention to user, suggest frame-populate, continue with whatever purposes exist.parseErrors > 0: mention which files failed to parse so you know to use raw Read for those.Pick the right command for the task. Do not run all of them.
| Command | Use when… |
|---|---|
frame read-file <path> --json | Need full symbol detail for a specific file — parameters, returns, language features, per-symbol purposes |
frame search <query> --json | Need to find files/symbols by name or purpose text and don't know the path. Flags: --files-only, --symbols-only, --limit N, --threshold N |
frame api-surface --json | Need to understand the public contract of the project — all exported symbols grouped by file |
frame deps <path> --json | Need the import graph for a file — what it imports and what imports it. Add --external for package deps |
Read when you only need structure or intent — frame is denser and pre-summarizedRead when you need actual implementation, not just shapesearch → read-file → deps (find entry point, understand it, trace the graph)parseError !== null — frame has nothing useful for them; use Read insteadframe generate or frame update — those are user-driven write operationsframe write-purposes — that's the frame-populate skill's job