setup-my-iq

name

setup-my-iq

description

Create, set up, or update the personal context portfolio: structured markdown files describing who you are, how you work, your teams, and your tool/ADO configuration. Runs the interview workflow for first-time setup and targeted edits for updates. Trigger this skill when the user asks to: set up their context, create or update their context portfolio, "create my IQ", "set up my IQ", edit their profile, add/remove a stakeholder, update ADO config, change team info, update pillars, or set up any plugin configuration. Trigger when another skill fails to find context (missing files or TODO markers) and needs context populated. Also trigger when the user mentions a context change in passing (e.g., "my manager changed", "we added someone to the team") to offer a context file update. Do NOT trigger for read-only questions like "who's on my team?" or "what's my ADO config?". Those are answered directly from the context files referenced in the loaded custom instructions; no skill is needed.

Setup My IQ: Create and Update Context Portfolio

Create and maintain the personal context portfolio: a set of structured markdown files that represent who you are, how you work, and what matters to you. The files can live anywhere on disk (OneDrive folder, a git repo, a local directory, etc.). What ties them into the agent is a pointer in one of the user's custom instructions files (AGENTS.md, copilot-instructions.md, CLAUDE.md, or any *.instructions.md that the host loads into the session).

How This Skill Works

When invoked, determine the current state and take the right action.

Discovering existing context

Scan the session for references to the files this skill creates. The host has already merged all relevant custom instructions files into the session: AGENTS.md (workspace or user-scope), copilot-instructions.md, CLAUDE.md, any *.instructions.md file, and similar host-specific equivalents. It doesn't matter which file the pointer came from, just look for the filenames:

• identity.md
• role-and-responsibilities.md
• team.md
• tools-systems-and-config.md
• communication-style.md
• preferences-and-constraints.md

For each, find an @<absolute-path> (or equivalent path reference) anywhere in the loaded instruction text. That's the file's location. Don't rely on the label or variable name next to the path: users may name pointers differently (identityProfile, me, who-i-am, etc.). Match on the filename at the end of the path.

For each filename, classify as:

• NOT REFERENCED — no path to this filename is loaded in the session.
• REFERENCED, FILE MISSING — a path is loaded but the file doesn't exist on disk.
• PRESENT — path is loaded and the file exists. Read it to check for placeholders.

If the six filenames are in mixed states, handle them in this priority order: first create any NOT REFERENCED files via the interview, then fill REFERENCED, FILE MISSING entries, then fix incomplete fields in PRESENT files. Summarize the combined state to the user before starting so they know what to expect.

Concrete example. Suppose identity.md and team.md are PRESENT and complete, tools-systems-and-config.md is PRESENT but has TODO placeholders in the ADO section, role-and-responsibilities.md and communication-style.md are REFERENCED but the files don't exist on disk, and preferences-and-constraints.md is NOT REFERENCED. The skill should tell the user: "You have identity and team done. Tools-config has gaps. Role and communication-style are referenced but missing. Preferences isn't set up at all. I'll interview you for preferences first, then create role and communication-style, then fill the gaps in tools-config. OK?"

1. No context files referenced

None of the expected filenames appear anywhere in the loaded instructions. Treat this as first-time setup. Run First-Time Setup below.

2. Some files referenced but missing on disk

The user started setup previously and didn't finish, or paths exist without files behind them. Resume where they left off:

• List which files exist and which are missing.
• Tell the user: "You have {existing files}. Still need: {missing files}. Want to pick up where you left off?"
• When choosing the next file to interview for, the priority order from Discovering existing context still applies. Within a tie, use this default sequence: identity -> role -> team -> tools -> communication-style -> preferences-and-constraints.

3. Files exist but have incomplete fields

Files exist but some contain unfilled placeholder values. Fill gaps:

• Scan all referenced files for any of these incomplete-field patterns:
  • <!-- TODO --> — explicit placeholder
  • HTML comments of the form <!-- ... --> used as stand-in values (e.g., <!-- your name -->, <!-- org name -->, <!-- manager name -->)
  • Any table cell or field whose only content is an HTML comment
• List the gaps: "I found incomplete fields in {files}. Want to fill them in?"
• For each gap, ask the specific question for that field (not the full interview).
• Update the file in place with the user's answer.

4. Files are complete, user wants to update

The user asked to change something, or mentioned a context change in passing (e.g., "my manager changed", "we hired someone new", "I moved to a different team"). Targeted update:

• If the user mentioned the change in passing during another task, offer: "It sounds like your {file} may need updating. Want me to fix that now?"
• If the user explicitly asked, proceed directly.
• Read the file from the path resolved in Discovering existing context.
• Make the edit and confirm with the user.

5. Files are complete, user wants a full refresh

The user wants to redo a file from scratch. Re-run the interview for that specific file following the same steps as first-time setup.

---

First-Time Setup

All assets/... paths in this skill are relative to this SKILL.md's directory. Use your file-read tool to load the bundled templates from those paths. If for some reason a template isn't readable, fall back to the field structure shown in the example walkthrough at the bottom of this file.

1. Choose context directory

Ask: "Where should your context files live? Anywhere persistent works: a synced cloud folder (OneDrive, Dropbox, iCloud), a local directory, or a git repo. Just pick a path you can find again later."

• Create the directory if it doesn't exist.
• Store the path for later steps.
• On macOS or Linux, suggest ~/my-iq-context or ~/OneDrive/my-iq-context as defaults. Substitute $HOME for %USERPROFILE% in any path the skill produces later.

2. Begin the interview

Introduce the process:

"I'm going to interview you and produce your personal context portfolio: a set of markdown files that represent who you are, how you work, and what matters to you. Any AI skill, agent, or plugin can read these files and immediately understand what it's working with.

We'll go one file at a time. I'll ask you questions, draft the file, and then ask you to tell me what I got wrong. You can skip any file you don't want right now. Ready to start?"

3. Pre-fill factual fields from available data sources

This step is MANDATORY before asking any interview questions. Do not skip it, even if you expect it to return nothing.

Before asking the user anything, attempt to gather factual data from whatever connected sources your environment provides. The user should never have to type information a connected system already knows.

What to look for (per file):

File	Factual fields to pre-fill
identity.md	Name, role/title, organization, team, manager
role-and-responsibilities.md	Teams supported, cadences (from calendar), reporting line
team.md	Direct reports, frequent collaborators, org chart data
tools-systems-and-config.md	ADO org/project/team/area path, repos, tools in use
communication-style.md	Writing samples from mail/docs (ask permission first)
preferences-and-constraints.md	No pre-fill (these are subjective boundaries)

How to execute:

1. Check what data sources are available in your environment (work profile, directory, calendar, ADO, mail, etc.). Use only sources already authorized.
2. Query them for the relevant factual fields for the file you're about to interview for.
3. Present findings as a proposal: "I pulled some information from your work profile. Here's what I found -- confirm or correct before we continue."
4. Mark each value as auto-filled so the user knows what came from a system vs. what you're asking them to provide.
5. Only after the pre-fill proposal is confirmed (or if no sources are available), proceed to ask the remaining questions.

If no data sources are available: State that explicitly ("I don't have access to a work profile or directory in this environment, so I'll ask you directly") and proceed to the interview questions. Do not silently skip this step.

See the full rules and constraints in the Pre-fill from available data sources before asking section under Interview Rules.

4. Interview for identity.md

Load the template from assets/templates/identity.md in this skill bundle for the file structure.

First: apply step 3 (pre-fill). Query available sources for name, role, org, team, and manager. Present any findings for confirmation. Then proceed to the questions below for fields not covered by pre-fill.

Open-ended questions to ask (these always need the user):

• If you had to explain what you actually do to someone at a dinner party, what would you say?
• What do people come to you for?

Factual questions to ask only if pre-fill didn't cover them:

• What's your name and current role?
• What organization or company are you with?
• What team are you on?
• Who's your manager?

Once you have enough to draft (don't keep asking past that point), draft the file. Present it with the reaction pass (see Interview Rules below). Revise, then write to the context directory.

Transition: "That's identity done. Next is role-and-responsibilities, which captures what your weeks actually look like. Ready?"

5. Interview for role-and-responsibilities.md

Load the template from assets/templates/role-and-responsibilities.md.

First: apply step 3 (pre-fill). Query available sources for teams supported, recurring calendar cadences, and reporting line. Present any findings for confirmation before asking questions.

Key questions:

• Walk me through a typical week. What are the recurring things?
• What teams or groups do you support?
• For each team: what are you accountable for? What cadences do you run?
• What decisions do you make regularly? Not big strategic ones, the routine ones.
• What do you produce? Reports, emails, dashboards?
• Who do you report to?
• Are there monthly or quarterly rhythms that shape your work?

Once you have enough to draft, draft. Organize by team: each team gets its own section with responsibilities, cadences, and deliverables. Present, revise, write.

Transition: "That's role-and-responsibilities done. Next is team, which covers the key people in your work life. Ready?"

6. Interview for team.md

Load the template from assets/templates/team.md.

First: apply step 3 (pre-fill). Query available sources for direct reports, org chart, frequent collaborators (from calendar/chat). Present any findings for confirmation before asking questions.

Key approach:

• Who are the people you interact with most? Start with your own team.
• Ask for team rosters (the user may paste email lists)
• For each team, identify the lead and hierarchy
• For key people: what do they need from you, what do you need from them?
• Capture focus areas or pillars per person where known
• Note interaction patterns (1:1s, scrums, syncs)
• Is there anything an agent should know about working with or preparing for interactions with specific people?

Use information from earlier files. If they mentioned collaborators during the roles interview, reference them here rather than re-asking. Draft, present, revise, write.

Transition: "That's team done. Last one: tools, systems, and configuration. This is where we capture how everything is set up. Ready?"

7. Interview for tools-systems-and-config.md

Load the template from assets/templates/tools-systems-and-config.md.

First: apply step 3 (pre-fill). Query available sources for ADO org/project/team/area path, repos, and tool configuration. Present any findings for confirmation before asking questions.

Key questions:

• What tools and platforms do you use daily?
• How do you organize meeting notes? Where do they live?
• What tags or patterns classify your meetings by type and by team?

Then for each workstream/team the user supports (use information from the role-and-responsibilities interview):

If the user supports more than three workstreams, ask first whether they want to configure all of them now or start with the most important one or two and add the rest later. For similar workstreams, ask if the same config applies and only interview for differences.

• Does this workstream use Azure DevOps? If yes: what org, project, team, area path? If no, skip the ADO section for this workstream.
• (ADO workstreams only) Are there work item title patterns to exclude from sprint scorecards? (e.g., estimation or review placeholder items)
• What are the strategic pillars or sections for this workstream? These are used as grouping headers in weekly updates and sprint reports. Define them even if the workstream doesn't use ADO.
• For ADO workstreams: which ADO Epics map to each pillar?
• Where do sprint updates get saved? What file prefix?
• Where do weekly updates get saved? What file prefix?
• Is there a roadmap file for this workstream?

Organize with common settings at top, workstream-specific config in sections below. Draft, present, revise, write.

Transition: "That's tools and config done. Next is communication style, so any agent writing on your behalf can sound like you. Ready?"

8. Interview for communication-style.md

Load the template from assets/templates/communication-style.md.

This section is harder than the others. People describe their own voice in clichés. Two stronger paths: ask about negatives, and offer to analyze real writing samples. Use both.

Start by offering the samples path:

"Want to share a few samples of your real writing? Paste 2 to 5 things you've sent: weekly status updates, leadership emails, Loop updates, a review entry, a Teams message you're proud of. I'll read them, extract the voice traits I see, and propose what should go in your file. You approve before anything gets written. I won't copy the raw content, only the style patterns."

If the user shares samples:

• Read each sample for style only: register, sentence length, openings, transitions, specific words used or avoided, framing patterns, how they handle credit, how they handle bad news.
• Do not copy raw sample text into the file. Extract patterns and present them back as proposed bullets in the file's structure.
• Present the proposed draft: "Here's what I extracted. Tell me what's wrong or missing."
• Apply the reaction pass as normal.

If the user doesn't share samples (or in addition to them), ask these questions one at a time:

1. "If a colleague described how you write in one sentence, what would they say?"
2. "Read this sentence: 'I'd encourage you to lean into the opportunity to be a genuine force multiplier for the team.' What's wrong with it for your voice?" (Surfaces the avoid-list faster than positive questions.)
3. "When you write a weekly status to leadership, what do you wish you could automate, and what do you always end up rewriting?"
4. "Who's the hardest audience for you to write to? What changes when you write to them?"
5. "When you write about yourself in a Connect or performance review, what's a phrase you've caught yourself writing and immediately deleted?"

Draft, present, revise, write.

After writing, tell the user:

"I won't automatically pick up on patterns over time. If you notice me repeating a mistake, swapping phrases, or fighting your edits, ask me to update this file and I'll fold the correction in. This file evolves when you tell it to."

Transition: "Last one: preferences and constraints. This is how you want AI to behave around you. Ready?"

9. Interview for preferences-and-constraints.md

Load the template from assets/templates/preferences-and-constraints.md.

Most rules here are about what an agent shouldn't do unilaterally. Surface them by recalling concrete frustrations rather than asking for abstract rules. Ask one question at a time:

1. "When was the last time an AI tool did something you didn't want? What did it do, and what should it have done instead?" (One answer often produces 3 boundary rules.)
2. "What's safe for an agent to do without asking you? What absolutely requires your approval?"
3. "Speed or thoroughness. If you had to pick one, which?"
4. "Are there any decisions you want AI to make for you, or do you always want options surfaced?"
5. "Where do you not want an AI speaking on your behalf?" (Teams, email, meetings, public chats.)
6. "Do you use any tool with persistent memory (VS Code session memory, an agent memory feature, etc.)? If yes, anything you want stored there, or specifically not stored there?" Skip the memory section if the answer is no.

Draft, present, revise, write. Apply the reaction pass.

Transition: "That's the interview done. Now I'll wire the files into your custom instructions so every agent can find them."

10. Wire the files into a custom instructions file

Add pointer entries to one of the user's custom instructions files so other skills and agents can find the new files. Recommend user scope, not workspace scope. The whole point of this context is that it's available everywhere, not tied to one repo.

Quick map: 10a detect harnesses, 10b pick the target file, 10c (only if more than one harness) offer to symlink them to a canonical file, 10d write the pointers using the bundled template.

On macOS or Linux, every command and path below has a POSIX equivalent. Substitute $HOME for %USERPROFILE% in every path, use ln -s <canonical-target> <harness-file> instead of New-Item -ItemType SymbolicLink, and skip the Developer Mode check entirely (symlinks don't require elevation on macOS or Linux).

Step 10a. Detect which harnesses the user uses. Check whether any of these user-scope paths exist (use the filesystem; no need to ask first):

Harness	User-scope custom instructions path
VS Code Copilot Chat / Claude Code	%USERPROFILE%\.claude\CLAUDE.md
GitHub Copilot CLI	%USERPROFILE%\.copilot\copilot-instructions.md

VS Code Copilot Chat does not natively read %USERPROFILE%\.agents\AGENTS.md, but it does read %USERPROFILE%\.claude\CLAUDE.md, which is the same file Claude Code uses. So .claude\CLAUDE.md is the shared user-scope file for those two harnesses.

If %USERPROFILE%\.agents\AGENTS.md exists, treat it as the canonical target. In some setups the harness-specific files above are symlinked to it, so a single write flows to every wired-up harness.

Step 10b. Pick the target. Apply the first rule that matches:

1. If %USERPROFILE%\.agents\AGENTS.md exists, default to it. The harness-specific files are symlinks to it, so a single write flows to every wired-up harness. Confirm with the user before writing.
2. Else if exactly one harness-specific file exists, propose writing to it. Confirm. Also mention the canonical-plus-symlink option in step 10c.
3. Else if both harness-specific files exist (copilot-instructions.md and CLAUDE.md), list them and ask which to update. Strongly recommend creating .agents\AGENTS.md as the canonical file and symlinking the others to it so a single edit reaches all harnesses (step 10c).
4. Else (no user-scope custom instructions files exist anywhere), ask: "Which AI harness do you use most: VS Code Copilot Chat, Claude Code, GitHub Copilot CLI, something else?" Then create the matching user-scope file (.claude\CLAUDE.md for the first two, .copilot\copilot-instructions.md for Copilot CLI) with a ## Personal Context section.

If the user explicitly asks for workspace scope instead, write to <workspace>\AGENTS.md and tell them the trade-off: it only applies to that repo.

Step 10c. Offer to symlink other harnesses to the canonical file. Only relevant when the user has (or wants) more than one harness. Ask: "Want me to make %USERPROFILE%\.agents\AGENTS.md the canonical file and symlink your other harness files to it? That way you edit once and every harness sees the change."

If yes, for each other harness file the user wants linked:

1. Prerequisites. File symlinks on Windows need either Developer Mode enabled or an elevated PowerShell. Check Developer Mode with:

   Get-ItemPropertyValue 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' AllowDevelopmentWithoutDevLicense -ErrorAction SilentlyContinue
   

   Returns 1 if Dev Mode is on. If it isn't, offer the user two options and let them pick:

   • Option A: Enable Developer Mode (one-time, no restart needed). Settings -> Privacy & Security -> For developers -> turn on Developer Mode. Or run this in an elevated PowerShell:

     New-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' -Name AllowDevelopmentWithoutDevLicense -Value 1 -PropertyType DWord -Force
     

   • Option B: Run the symlink command yourself in an elevated PowerShell. Hand them the exact command (filled in with the real paths) and ask them to run it in a PowerShell window opened as Administrator. Then continue once they confirm it succeeded:

     New-Item -ItemType SymbolicLink -Path '<harness-file>' -Target "$env:USERPROFILE\.agents\AGENTS.md"
     

   Don't keep going without either Dev Mode on or confirmation that the user ran the elevated command.

2. Back up the existing file to <file>.bak-<yyyyMMddHHmmss> so nothing is lost. Never delete.

3. Create the symlink pointing to %USERPROFILE%\.agents\AGENTS.md (skip if the user already ran it themselves under Option B):

   New-Item -ItemType SymbolicLink -Path '<harness-file>' -Target "$env:USERPROFILE\.agents\AGENTS.md"
   

The inline symlink steps above are enough for context wiring.

If the user declines symlinks, proceed with the per-harness write and move on. Don't push twice.

Step 10d. Write the pointers. Use the bundled AGENTS.md template at assets/templates/AGENTS.md (relative to this SKILL.md) as the source of truth for the ## Personal Context block structure (header, entry labels, routing table, rules). Don't reinvent the format.

Behavior:

• If the target file doesn't exist on disk yet, create it. Make any missing parent directory (e.g., %USERPROFILE%\.copilot\ or %USERPROFILE%\.claude\), copy the entire bundled template into the target path, replace <CONTEXT_DIR> with the absolute path to the context directory chosen in step 1, and write it.
• If the target file exists but has no ## Personal Context section, append the section to the end of the file (and add the ## Safety section from the template if it's missing too), with <CONTEXT_DIR> replaced. Don't touch existing content above it.
• If the ## Personal Context section already exists, only add or update the specific entries that changed. Do not rewrite the whole section. Keep the existing labels and ordering; only swap the @<path> lines.
• Only wire up files that actually exist on disk. Don't add @<path> pointers for files the user skipped.

11. Confirm and summarize

"That's your context portfolio. Any AI skill, agent, or plugin that reads your custom instructions can find these files and immediately understand what it's working with.

The files will get better as you update them over time. Projects change, priorities shift, and your communication style file in particular will evolve as you catch me repeating mistakes and ask me to fold the correction in. Treat these as living documents, not a finished product."

Show the user:

• List of files created and their paths.
• The custom instructions file path where the pointers were written.

---

Context Files

File	Purpose	Consumed By
identity.md	Name, role, org, team, manager, what you do	Any skill that needs to know who the user is
role-and-responsibilities.md	Responsibilities per team, cadences, deliverables	Status, reporting, and planning skills
team.md	Team rosters with roles and focus areas	Skills that prepare for or summarize interactions with people
tools-systems-and-config.md	Tools, meeting tags, ADO config per team, pillars, reporting settings	Skills that read meeting notes, run reports, or talk to ADO
communication-style.md	Voice, tone, formatting rules, words to avoid, audience-specific adjustments	Any skill that writes content on the user's behalf
preferences-and-constraints.md	Hard boundaries, approval rules, working preferences, memory rules	All skills (especially ones that write or send)

Consumers find these files by reading the pointers loaded from any custom instructions file (AGENTS.md, copilot-instructions.md, CLAUDE.md, *.instructions.md). No MCP or dedicated reader skill is required.

---

Interview Rules

Tone

Be direct, warm, and specific. You're an interviewer, not a coach. Don't editorialize, compliment, or offer opinions about the user's answers.

Pre-fill from available data sources before asking

Before walking the user through a question list, check whether any of your available tools or data sources can answer the factual fields for you. The user shouldn't have to type things a connected system already knows.

Common examples (use whatever your environment actually provides):

• A connected work profile or directory may know the user's name, title, organization, team, manager, and direct reports — useful for identity.md and team.md.
• Calendar, mail, or chat history may surface frequent collaborators and recurring cadences — useful for team.md and role-and-responsibilities.md.
• Project management or source control integrations may know the user's org/project/area path or repos — useful for tools-systems-and-config.md.
• Existing writing samples in mail or documents (with the user's permission) may inform communication-style.md without requiring fresh samples.

Rules:

1. Only use sources the user has already authorized. Don't reach for anything new mid-interview without asking.
2. Pre-fill is a proposal, not an answer. Present what you found, label it as auto-filled, and ask the user to confirm or correct each value before it goes into a file.
3. Don't enumerate tool names to the user. Say something like "I can pull some of this from your work profile" rather than listing specific product names.
4. Fall back to asking when no source is available, or when the data is ambiguous, stale, or sensitive.
5. Open-ended fields (what you actually do, what people come to you for, voice, boundaries) still need to be asked. Don't fabricate them from indirect signals.

Questions

• Ask one question at a time. Never present lists of questions.
• Never ask compound questions.
• Use what you learn in earlier files to inform later interviews. Don't re-ask things you already know.
• If the user goes on a tangent useful for a later file, note it and use it when you get there.
• When the user gives a vague answer, push for specifics: "Can you give me an example?" or "What does that actually look like day to day?"
• When you have enough to draft, say so and draft. Don't keep asking. "Enough" means you have answers covering the core fields in that file's template (for identity: name, role, org, team, manager, and what they do). You don't need to walk every listed question if earlier answers already covered the information.

The Reaction Pass

After drafting each file, present it and say: "Here's my draft. Read through it and tell me what doesn't sound right. Anything that feels off, anything I assumed wrong, anything that's missing."

If the user says it looks good with no changes, push once: "Pick one sentence that's the weakest or most generic. What would make it more specifically you?"

If they push back a second time and say it's fine, accept it and move on.

File Quality

• Keep files concise. One page, not five.
• The files should sound like the user, not like an AI writing about them.
• Use their language, their framing, their level of formality.
• Never use em dashes.
• If the user wants to skip a file, let them.
• If the user needs to stop mid-file, tell them where you are so they can resume.

---

Example: Identity Interview Walkthrough

This shows what a complete identity.md interview looks like from first question through final written file.

Agent: What's your name and current role?

User: Dana Kim, Senior Program Manager.

Agent: What organization are you with, and what team?

User: Contoso, Cloud Engineering. I'm on the Platform Operations team under Jordan Rivera.

Agent: If you had to explain what you actually do to someone at a dinner party, what would you say?

User: I keep the data platform teams running. Sprint planning, status reporting, making sure leadership knows what's happening without everyone drowning in update emails. I also build AI tooling that automates the repetitive parts of program management.

Agent: What do people come to you for?

User: Two things: getting a clear picture of where a project actually stands (not the sanitized version), and figuring out how to use AI tools to cut busywork out of their workflows.

Agent: I have enough to draft. Here's my draft:

# Identity

- **Name:** Dana Kim
- **Role:** Senior Program Manager
- **Organization:** Cloud Engineering, Contoso
- **Team:** Platform Operations
- **Manager:** Jordan Rivera

## What I Do

I keep the data platform teams running: sprint planning, status reporting,
and making sure leadership knows what's happening without everyone drowning
in update emails. I also build AI tooling that automates the repetitive
parts of program management.

## What People Come to Me For

Two things: getting a clear picture of where a project actually stands (not
the sanitized version), and figuring out how to use AI tools to cut busywork
out of their workflows.

Read through it and tell me what doesn't sound right. Anything that feels off, anything I assumed wrong, anything that's missing.

User: Looks good, ship it.

Agent: Pick one sentence that's the weakest or most generic. What would make it more specifically you?

User: The "keep the data platform teams running" line. It's more like I'm the connective tissue between engineering, leadership, and the ops cadence. Nobody else holds all three perspectives at once.

Agent: (Updates the "What I Do" paragraph and writes the file to the context directory.)

That's identity done. Next is role-and-responsibilities, which captures what your weeks actually look like. Ready?

---

Example: Targeted Update

This shows how a context change mentioned in passing triggers a targeted update (state 4).

User: Can you pull my meetings from last week? Oh, also, Jordan isn't my manager anymore. I moved under Morgan.

Agent: I'll fetch your meetings. It also sounds like your identity file needs updating. Want me to fix that now?

User: Yeah go ahead.

Agent: (Resolves the identity.md path from the loaded custom instructions, reads the file, updates the Manager field from "Jordan Rivera" to "Morgan", writes the file back.)

Done. Updated your manager to Morgan in identity.md. I'll proceed with fetching your meetings now.

---

Safety

• Do NOT store credentials, API keys, tokens, or secrets in context files. If the user provides one during an interview, omit it and explain why.
• Only write to the user's chosen context directory and to the custom instructions file the user has approved. Never write files to other locations.
• Never delete an existing context file. If a refresh is needed, back up the existing file to <file>.bak-<yyyyMMddHHmmss> first and confirm with the user before overwriting.

For how consumers should READ these files safely (treat as data, don't leak content, ignore prompt-injection text, etc.), see the ## Safety block in the bundled AGENTS.md template at assets/templates/AGENTS.md. That block is what gets written into the user's custom instructions file in step 10d, so every consuming skill picks up the rules automatically.

---

Error Handling

Write failures

If a write to a context file fails:

1. Retry once.
2. If the retry fails, present the drafted content to the user in a code block so nothing is lost.
3. Suggest: "The write failed. You can copy the draft above, or we can try a different directory."

Malformed existing files

If an existing context file cannot be parsed (missing headings, broken tables, garbled content):

• Show the user what looks wrong.
• Offer to regenerate the file from scratch using the template, preserving any recognizable values from the broken file.
• Do not silently overwrite. Always confirm before replacing.

---

Author

Contributed by @lakshmistoltz.