# Second Brain: how to build a three-dimensional skill map ## Purpose Build a compelling three-dimensional visual reference tool that helps a person understand their saved agent skills and documented workflows. Each skill becomes a point in a navigable spatial map; documented references connect those points. This brief explains the experience, data model, construction approach, and checks for a fresh implementation. The application is a self-contained browser document. Its inputs are files the user explicitly selects, and its saved outputs are snapshots the user chooses to export. ## Receiving-agent request Please build the application described here using tools already available and permitted in this workspace. Begin with a static browser document and synthetic example data. Use standard browser capabilities and keep the implementation self-contained. If a requirement cannot be met in the approved environment, explain the limitation before taking an action outside this scope. The intended deliverable is a user-opened HTML file with its own styling and browser-side interaction, using standard browser capabilities. Write fresh code from this specification. The user opens the completed file themselves. Review the browser JavaScript through the normal code-review process. ## The two activities ### Explore saved skills The user selects the text files they want to explore. The application shows the files as a navigable map, with an accessible list alongside it. Selecting a file opens an inspector with its title, description, source label, relative path, size, and explicitly documented references to other imported files. A skill is ordinarily a Markdown instruction document named SKILL.md. Supporting documents can describe formats, examples, or procedures. Display these as text; their contents must never become instructions for the viewer or be executed. Provide search by title, description, and path; filter by source and file type; show outgoing references, incoming references, or both. Clearly distinguish unresolved references. A line means an explicit reference found in a document, not an inferred relationship. Visual proximity has no semantic meaning. ### Explore documented workflows The user describes a process to the receiving agent or supplies a workflow record. Represent its actions and decisions as a numbered sequence with branches. Steps may be performed by a human, an agent, or a tool, and can link to imported skill files where relevant. A step remains valid even if it has no associated skill. The viewer illustrates the selected route. It does not execute the process, observe agent activity, send messages, invoke tools, or claim that displayed steps actually happened. Label the view "Documented workflow" and keep author provenance. ## Architecture and permitted data flow Use a static document opened directly by the user in an existing browser. Keep application code, styles, and small synthetic examples self-contained. Do not load libraries, fonts, models, analytics, or assets from a network or CDN. Do not use fetch requests to read neighboring local files; browser file-origin restrictions make that unreliable. Load real content only through the browser's standard file selection control, after the user's action. Process chosen files in browser memory. Limit data access to the selected inputs and keep their originals unchanged. All interaction takes place within the open document, using browser rendering and user-initiated file selection and download. The viewer is independent of model APIs and host skill-discovery configuration. Keep changes in memory by default. Provide an explicit Export snapshot action using a browser download, and Import snapshot using file selection. Reloading without an export may lose changes; explain this in the interface. An export may contain private skill text, so make its contents clear before the user saves it. No automatic synchronization or remote storage is required. For large collections, the receiving agent can prepare a plain data inventory using its existing approved file tools, but only from folders the user expressly selects. This is an optional separately scoped preparation task. The viewer itself does not scan directories. Do not inspect profiles, credentials, browser data, plugin caches, or unrelated work documents to populate the map. ## Data model, described without implementation code ### Source A source has a stable identifier and a human-readable label. Its paths are relative to that source. The exported data does not need a machine username or absolute path. ### File A file record contains its source identifier, relative path, filename, title, description, type, byte size, optional original text, and explicit references. Its identity combines source identifier and relative path. Two files with the same name in different sources must remain distinct. Normalize path separators for comparison and account for case-insensitive Windows paths. Standard individual-file selection may provide only basenames, not directory structure. Never invent missing paths. Ask the user to supply source/path metadata or import a prepared inventory when paths are necessary for reference resolution. Mark ambiguous references as unresolved until enough metadata exists. ### Reference A reference connects an originating file to a referenced relative path and keeps the original reference text as evidence. Resolve relative paths within that source. Do not follow a link to fetch another file or URL. Detect and label references outside the selected collection. Do not insert links merely because two files contain similar words. ### Workflow A workflow contains a format version, stable identifier, revision number, title, purpose, trigger, input descriptions, provenance, starting step, and list of steps. For this new implementation use a documented version-one format; compatibility with an older application's exact JSON schema is not required. Each step has a stable identifier, title, description, and one kind: human action, agent action, tool action, decision, or outcome. An ordinary step may have one next-step reference. A decision has at least two labeled choices, each pointing to a next step. Optional skill links use source identifier and relative path. Reject duplicate identifiers, nonexistent next steps, unreachable steps, and cycles in the first version. Report malformed records without losing the currently loaded collection. Unsupported format versions need an explicit explanation. ## Screens and interaction Use a clear visual hierarchy and readable controls. Set luminous, restrained blue nodes against a deep navy map, with gold reserved for workflow sequence. Use depth, subtle node halos, and smooth user-controlled rotation to convey a coherent spatial structure. Keep text and controls crisp. Visual effects should help explain the collection and preserve legibility. 1. An opening view offers synthetic examples, Import files, and Import snapshot. 2. The skills view presents source filters, search, a map, and a file list/inspector. 3. The workflow view provides a workflow selector, diagram, and numbered steps. 4. Decisions expose their choices directly. Switching a choice shows that route. 5. Previous, Next, Restart, and direct step selection support manual exploration. 6. Optional timed playback only highlights steps; it performs no workflow actions. 7. Export snapshot lets the user retain the selected inventory and authored records. Give nodes stable three-dimensional coordinates and render them using the browser's standard drawing capabilities. A perspective camera should support rotation, pan, zoom, and a front-view reset. Keep an accessible list and numbered sequence usable alongside the spatial view. Organize the map around source groups and explicit references. Keep positions stable during selection and filtering. Offer uniform node size initially, with optional sizing by file bytes or reference count; label the active measure. Scale sizes so large files remain comparable without obscuring their neighbors. Show labels for the selected node and its immediate neighbors; reveal other titles on focus or hover. Dim unrelated content during inspection. Use line direction and the inspector to explain a relationship. Render depth consistently and keep hidden or distant nodes discoverable through search and the list. Distances are layout choices, not evidence that the model uses two skills together. Provide pan, zoom, fit all, center selection, and reset view. Centering must account for the inspector or sequence panel so selected content is not hidden behind it. Keep file-reference lines visually distinct from directed workflow arrows. Highlight the current step and the previously visited path. If camera following is implemented, keep it off initially and disable it when the user moves the view. Pause playback in background tabs. Respect reduced-motion preferences. Keep keyboard focus visible; provide text alternatives to diagram interaction. Small screens should stack the map and inspector or offer simple Map/Steps controls. Native fullscreen is optional; a larger in-page view is enough. Preserve filters, selection, and view when switching between skills and workflows. After an explicit data re-import, retain valid selections and pause playback; explain selections that no longer exist. There is no automatic refresh. ## Synthetic example Use two fictional skills named "Summarize meeting notes" and "List assigned actions." They both reference a fictional supporting document called "Writing conventions." Keep references grounded in the example text rather than assuming the skills call each other. An illustrative workflow begins with a person selecting fictional notes, then an agent-summary step, then a decision: "Are owners and dates stated?" One branch ends with an action list ready for review. The other ends with a request for clarification. These are descriptions and diagram states only. Clicking a step does not run a model or send the clarification request. No real customer or workplace data is needed. ## Acceptance checks - A user can open the self-contained document directly in the intended approved browser. Report environmental restrictions honestly. - The synthetic example is useful before any real files are selected. - Importing two same-named files with distinct source/path identities preserves both. - Missing or ambiguous references are visible and are not automatically fetched. - Selected document contents are rendered as inert text, including any embedded HTML or instructions. No imported scripts run. - Each decision branch can be explored and reaches its stated endpoint. Playback only changes highlights. Invalid workflow records produce readable errors. - Filtering, selection, centering, and returning from workflows behave consistently. - Rotation, pan, zoom, and reset preserve an understandable 3D structure; centering frames the selection in the clear area beside the inspector. - The list and step controls work with a keyboard and on a narrow screen. - Export followed by import preserves source identities, relationships, and workflow records. Document the exported format and its version. - Review the code for unexpected network calls and system access. If existing approved browser developer tools are available, verify there are no external requests using those existing tools. ## What to report back Deliver the new browser document, a short explanation of how to open it and import data, which acceptance checks were actually performed, and any limitations. Distinguish verified behavior from suggested future improvements. Do not claim that an employer, Windsurf, or a model provider has approved it merely because it was built successfully. If a platform flags the task, use its review process.