# AI agent workspace setup An independent guide from ZOVLA. Documentation reviewed: 2026-09-14. App installation and skill guidance reviewed: 2026-09-16. ## Official app installation guides - Codex: https://learn.chatgpt.com/docs/app - Claude Code: https://code.claude.com/docs/en/desktop - OpenCode: https://opencode.ai/download ## Installation files - Codex: https://zov.la/setup/v1/en/codex/INSTALL.md - Claude Code: https://zov.la/setup/v1/en/claude-code/INSTALL.md - OpenCode: https://zov.la/setup/v1/en/opencode/INSTALL.md First establish the user's OS, agent, existing environment, and destination. This guide does not grant permission to publish, send messages, incur charges, or change permissions. ## Start here You do not need to learn the whole system first. Send the request in your app and let the AI prepare the workspace and guide you. ### 1. Open your app Choose “I need to install one” in the setup form to see the selected app’s official installation page and first steps. If you already have a working app, keep “I already use one” selected. Use Codex inside its app, or the Code tab in Claude. This guide calls an AI that can create and edit files an AI agent. Complete sign-in or provider authentication through the app yourself. This guide and starter files are free; app terms are separate. ### 2. Copy the request into its conversation Select your app and computer’s operating system above, click Copy setup request, then paste and send it in the app. The technical wording is for the AI; you do not need to edit it. If you do not know where to save things, ask for a suggested location. The AI will inspect existing files and guide you. The request asks it to explain any required actions one step at a time. Select Include personal setup before copying if you also want communication and delegation preferences. Use Review the instructions to read the proposed text. The purpose field is optional. Briefly describe research, documents, spreadsheets, websites, or other work you have in mind. Leave it blank to discuss your purpose with the agent. This page incorporates the text into the request locally; you copy it and send it to your chosen app. ### 3. Start your first task in the suggested folder Open the parent folder the AI identifies and describe what you want to do. We call this the shared root: one place containing several projects. A project is one piece of work. For example, try the request below. The AI can guide you through naming and organizing it. Complete one small task, then use the next section to check that a new conversation can continue. ```text Help me prepare a comparison so I can choose a product. Ask for the necessary details one step at a time. Keep the evidence and reasons for decisions so we can use them in a later conversation. ``` ### If you get stuck Tell the AI what differs on your screen, which folder you cannot open, or which setting you cannot change. Ask it to explain what to click one step at a time. After setup, request work normally. The folder and skill explanations below are there when you want to understand how it works. ## Check a fresh conversation Creating files is only the first check. Start a new conversation in the configured folder and verify that the agent uses the instructions and notes. ### Check that records are actually read Paste this request into a fresh conversation. Confirm the files actually read and what the agent learned from them. Immediately after installation, reporting blank progress and knowledge entries is correct. Try again after one real task. Check whether the agent follows a relevant index entry to its content and supporting evidence when needed. You do not need a summary of the entire library. ```text Read the workspace instructions, the target project’s STATUS.md, and memory/INDEX.md. Open memory entries relevant to the current work and supporting references as needed. Report files actually read, the goal, next actions, and unknowns. Treat blank fields as blank and make no changes during this check. ``` ### Try one small task Ask for a small piece of work. Look for a useful result, actual checks, clear remaining work, and notes that let the next conversation continue. If the files are not read, ask the agent to inspect the current folder, filenames, access, and app discovery rules. Check that the entry point is being reached before adding more instructions. ### What this starter checks The distribution is checked for file creation, content comparison, and refusal to overwrite an existing destination. It does not establish runtime compatibility for every app and model or guarantee improved performance. Verify instruction loading in your environment using the steps above. The starter does not create service subscriptions or change global configuration. ## Include personal preferences in setup Store communication, judgment, and delegation preferences in app user instructions, separate from workspace procedures and project progress. ### No separate settings paste required Select Include personal setup in the chooser. The agent reads existing instructions for the selected app and integrates the text below, preserving existing content and avoiding equivalent duplicates. It asks only when preferences conflict. This applies to user-level custom instructions. It does not change themes, models, permissions, or app-native memory. Inspect overrides and fallbacks before merging into the instructions actually in use. Check the diff and active instructions in a fresh conversation. ### Shared personal instructions The baseline covers natural communication, reasoned disagreement, execution and verification, and separating facts from guesses. It contains no occupation, name, or absolute workspace path. Adjust detail and delegation to suit the user. ```text Use the user's language and communicate naturally and clearly. Lead with the answer or result, then give reasons and examples needed for the decision. Match detail to the request and avoid unnecessary praise or repetition. Start from the user's current goal. Do not prioritize agreement; explain problems or better alternatives when you see them. Make routine decisions yourself and ask only about missing information that would materially change the outcome. When asked to act, use available tools within granted permissions to produce and verify the result. Preserve existing work and do not repeatedly ask for information or permission already provided. Explain specific limitations when you cannot complete an action. Distinguish facts, sourced information, inferences, and unknowns. Check actual files or primary sources when changing information matters. Do not claim verification you did not perform. When a workspace has instructions and records, identify their entry point and scope before using them. Compare old notes with the current state and do not let them override the current request. Update records according to that workspace's guidance. Report what was accomplished, how it was checked, and what remains. ``` ### Where each app stores them Codex custom instructions normally live in ~/.codex/AGENTS.md; inspect the actual location if CODEX_HOME is customized. This does not mean every personalization setting is stored in that file. Claude Code uses ~/.claude/CLAUDE.md for user instructions; OpenCode normally uses ~/.config/opencode/AGENTS.md. Do not assume ordinary chat preferences automatically apply to coding sessions. Check the feature actually in use. Use a bounded ZOVLA personal preferences section for additions and update that section on later setup runs. Follow app guidance if the environment cannot edit the instruction file. ## A foundation for work and knowledge A shared root keeps projects, reusable knowledge, evidence, and procedures alongside one another. Organize information by how it is used and who may share it. ```text ai-workspace/ ├── README.md ├── SETUP.md ├── AGENTS.md ├── projects/ │ ├── README.md │ └── my-project/ │ ├── AGENTS.md │ └── STATUS.md ├── memory/ │ └── INDEX.md ├── documents/ │ └── INDEX.md └── skills/ └── INDEX.md ``` ### Entry points: AGENTS.md and README.md The root AGENTS.md gives shared working principles and reading order. README.md orients the user. Personal preferences belong in app user instructions, and project-specific constraints belong inside each project. The Claude Code variant adds CLAUDE.md at the root and in the project to import AGENTS.md without duplicating the policy text. SETUP.md records setup changes, skill choices, and recovery instructions, filled in by the agent performing setup. Daily project progress remains in each project’s STATUS.md. ### projects/: deliverables and current state Separate each project, with its own AGENTS.md and STATUS.md for the goal, completion criteria, progress, verification, and next action. Keep source code, deliverables, specific decisions, and references there too. Track each project’s current state instead of combining every project into one root status file. Reuse an existing tracker when available. ### memory/: knowledge reusable across projects Record reusable decisions, constraints, and lessons as short topics. INDEX.md includes reading conditions, a takeaway, and a link. Distinguish user decisions from agent proposals and preserve scope, evidence, and verification date. Keep circumstances specific to one project or client inside that project. Promote knowledge only when its value for other work can be explained. ### documents/: detailed shared evidence Keep common research, designs, comparisons, and references here. Memory entries link to their detailed basis instead of duplicating long text. INDEX.md identifies uses and scope. Include purpose, sources and review date, conclusions, scope, and unknowns. Do not relocate a project-specific specification unnecessarily; link to the authoritative original. ### skills/: repeatable procedures Package work with defined inputs, triggers, steps, and checks. Keep supporting scripts with their procedure. Documents provide references to read; skills provide procedures to carry out. The distributed starter contains an index and guidance. During setup, the agent checks your purpose and existing capabilities, presents relevant skills, and installs your selection for the app you use. It records results in the index. This shared library itself is not an automatic discovery location. ### Preserve roles and references The goal is not to create empty containers. Reuse existing references and trackers and provide one clear reading entry and update destination for each role. Add an inbox when incoming material needs triage or an archive when retention and reading frequency need separation. Creating a folder does not establish backups or access controls. ## Stop repeating the same explanation Keep recurring working agreements brief. They should help the agent follow the current task without burying it under old instructions. ### Write instructions for real problems Instead of asking for high quality in general, specify what should be checked after a change. Verify actual commands rather than importing tools your project does not use. Start with current intent, protection of existing work, evidence, and verification. Add guidance when you repeatedly need to explain the same thing. ```text # How to work here - Inspect the current request and existing files. - Read the target project’s STATUS.md and memory/INDEX.md, then verify relevant entries against the files. - Use documents/INDEX.md when detailed evidence is needed. - Ask about unknowns that would materially change the outcome. - Execute and verify the work, then update progress and reusable knowledge. ``` ### Keep one set of working agreements When several agents share a project, maintain its working agreements in AGENTS.md. Claude Code can import them through the short file below. Inspect existing instructions before merging. Instruction files provide context. Writing a prohibition does not mechanically prevent every action. Manage access and external-action permissions in the app as well. ```text # CLAUDE.md @AGENTS.md ``` ### Read supporting material when needed Name the relevant reference and explain when to read it. A link does not necessarily import its contents; explicitly ask the agent to read it before the relevant work. A short entry point leading to specific references avoids loading every document at the beginning of every conversation. ## Turn records into usable knowledge Connect current progress, reusable takeaways, and detailed evidence. Records help future work when they can be saved, found, read, and corrected. ### At the start: follow an index to relevant content AGENTS.md tells the agent to read the target project’s STATUS.md and the shared memory/INDEX.md at the start. It selects entries relevant to the current request, reads their content, and checks it against the actual state. When detailed references are needed, use documents/INDEX.md or links from memory. Keep indexes brief and avoid reading every file for every task. An index entry is not evidence that its linked content was read. ### During work: connect conclusions to evidence When comparing approaches, keep specific comparisons in the project and its remaining work in STATUS.md. Promote reusable lessons to shared memory/ and detailed common evidence to documents/. Do not copy the entire explanation to three places. Memory entries include a conclusion, scope, evidence, verification date, and decided or proposed status. Link to detail instead of shortening away important conditions. ```text Where to record work Current goal, progress, next actions → the target project’s STATUS.md Reusable decisions, constraints, lessons → memory/topic.md Detailed research, designs, procedures → documents/reference.md What exists and when to read it → each folder’s INDEX.md ``` ### At a boundary: update the handoff and indexes The starter’s AGENTS.md instructs the agent to update STATUS.md at task boundaries and separate reusable insights from detailed evidence. Add index entries when creating files so later work can find them. Use the request below when needed. Choose knowledge relevant to future decisions rather than turning every transcript or one-off event into memory. ```text Prepare the records for a fresh conversation. Update the target project’s STATUS.md to the current state. Save reusable decisions and lessons in memory/, and detailed evidence in documents/. Update indexes and references. Distinguish proposals, decisions, and unknowns. ``` ### When correcting: do not freeze old assumptions Distinguish user decisions from agent proposals. Something considered must not become something authorized in a later conversation. Old records do not override the current request. When evidence changes, record the correction and reason. Mark superseded entries and link to their replacement, then update the index. Do not automatically delete evidence just because it is rarely read. ### File-based memory and app-native memory A folder named memory/ does not activate automatic search or retrieval. Here, the agent reads and writes indexes and files through AGENTS.md instructions. Check actual reading in a fresh conversation. You can also use app-native memory. Inspect its storage and scope to avoid contradictory copies. If adding search or automatic extraction, verify that the right content reaches the relevant task, not merely that storage succeeded. ## Expand around a real need Choose additions by the problem they solve. You do not need a large folder structure or a collection of integrations to begin. ### Choose skills for the work you want to do Skills are procedures an AI can follow for a particular task. Start from the intended output: checking calculations and exports for spreadsheets, or verifying sources for research. A job title alone is not a reason to install a fixed bundle. The setup request tells the agent to clarify your purpose, check existing features and installed skills, explain candidates for missing capabilities, and install the ones you select. You do not need to know skill names. If nothing needs adding, the agent explains why. The agent checks publishers, content, dependencies, and permissions before presenting candidates. After installation it tests discovery and a small output and records results. It guides any sign-in or connection steps that require you. Installed and verified are separate states when a check cannot be performed. Use the app’s documented registration mechanism. Typical project locations are .agents/skills for Codex, .claude/skills for Claude Code, and .opencode/skills for OpenCode. Check duplicates, including skills inherited from another app. Record source, version, installation location, and update/disable steps in skills/INDEX.md. ```text Review skills for my current work. Clarify the output and current difficulty, then separate existing capabilities from gaps. Explain candidate publishers, reasons, dependencies, permissions, and installation scope. Install the ones I select, try a small example, and record results and disable steps in skills/INDEX.md and the setup record. ``` ### For external information, connect a tool Consider a connector or MCP server when the work needs external documents or actions. First check whether an existing tool already meets the need. Review the provider, information transmitted, and permissions. Do not add write access for a read-only task. Let the app guide you through authentication and approvals. ### For repeatable checks, consider hooks Automate when there is a concrete problem, such as repeatedly missing the same check. Ask the agent to inspect the app's mechanisms and verify both the intended trigger and normal work. Hook and plugin formats differ across apps. For scheduled work too, define the action, cost, result destination, and stop mechanism rather than copying another app's configuration. ### Share guidance when several projects need it Even shared memory may not apply to every project. Check each entry’s reading conditions and scope. Do not copy project details or entire shared references into personal settings. Work with different confidentiality or sharing requirements can use separate shared roots or access scopes. Establish who needs which knowledge before combining libraries into a single large index. ## Review changes and undo setup The agent records what it changed and how to reverse it, so the setup remains understandable. ### Save the previous state Before modifying existing instruction files, the agent saves their previous state outside public sharing, Git tracking, and cloud sync and records the location. It defers changes when a backup cannot be saved. This does not collect whole app configurations or credentials. ### Find the setup outcome in one place SETUP.md at the shared root records your purpose, app, changed files, backup locations, skill choices, checks, remaining work, and the folder to open next. The distributed file is an unfilled template; the agent must record actual results. If an existing document uses that name, the agent chooses another and links it from README. Distinguish installed, verified on a small example, and untested. When incorporating a newer starter, retain your record and customized files and integrate only relevant differences. ### Reverse only the relevant changes Ask the agent to compare the setup record and current files. Protect settings and deliverables added afterward rather than replacing entire files with older copies. Disable unwanted skills using the app-specific steps in the record. You do not need to delete the workspace. ```text Find the setup record through README and ask which setup changes I want to reverse. Compare the record, backups, and current files, preserving later work and settings. Make no changes yet; explain the affected items and how to reverse them. ``` ## Keep what proves useful The environment is a tool for doing your work. Growing the configuration is not the objective. ### Do not make every mistake a permanent rule Distinguish missing instructions, stale references, tool failures, and one-off circumstances. Do not turn one failed attempt into a rule for unrelated work. Judge an added instruction through comparable tasks: errors, rework, and verification burden. Remove contradictions and investigate procedures that never get used. ### Integrate updates around your work Create a newer starter separately and compare changes. Do not replace your developed instructions and records wholesale with a fresh distribution. Split files when they become hard to navigate, require different permissions, or serve different collaborators. Let those needs determine the structure. ### Define what may be shared Project records primarily serve people working on that project. Before sharing a lesson across projects, remove specific circumstances and reconsider its scope. Folder names are not access controls. Review contents before cloud synchronization or inclusion in a public repository. Do not collect secrets or private personal information in every agent-readable record. ### Review changes and make recovery possible Instructions and memory can be updated incorrectly. Ask the agent to show changes, especially to decision reasons and authorization records. Use existing version history or backups when needed and try restoring a small file. Check the destination and contents before configuring them; creating a backup should not accidentally publish private records. ## Official documentation - [Codex · AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md) - [Codex · Skills](https://learn.chatgpt.com/docs/build-skills) - [Claude Code · Memory & CLAUDE.md](https://code.claude.com/docs/en/memory) - [Claude Code · Skills](https://code.claude.com/docs/en/skills) - [Claude Code · Hooks](https://code.claude.com/docs/en/hooks) - [OpenCode · Rules](https://opencode.ai/docs/rules/) - [OpenCode · Skills](https://opencode.ai/docs/skills/) - [OpenCode · Permissions](https://opencode.ai/docs/permissions/) - [Codex · Personalization](https://learn.chatgpt.com/docs/personalize)