How to use the ISA: Ideal State Artifact agent skill

What is an agent skill, and what does the ISA skill make the agent do?

An agent skill is a folder of instructions that an AI agent loads when a task matches it. The ISA skill is one of these. Its job is to create and maintain an Ideal State Artifact: a document that says what finished work looks like before anything is built.

The agent writes the ISA in layers: a one-sentence summary (L3), a short summary with one sentence and exactly four bullets (L2), and a full articulation (L1). It also writes a list of testable criteria, each with a way to check it, plus a test strategy. The agent then restates, discusses, and rates the document so you and the agent agree on direction before building.

• Scaffolds a new ISA from a prompt or extends an existing one in place
• Restates the direction back to you to confirm it
• Runs discovery interviews and questionnaires to fill gaps
• Rates an ISA's quality and checks whether its criteria still add up to the top-level summary
• Renders an ISA as HTML and upgrades older ISAs to the current format

What you need before installing

The skill is part of a larger personal AI framework called LifeOS. The SKILL.md file is mostly routing instructions that point to other documents, and the skill calls scripts such as LIFEOS/TOOLS/IsaLadder.ts, IsaAlign.ts and ContextLoad.ts. Those scripts, along with ISAFormat.md and References/CompleteGuide.md, are not included in this folder.

Without a LifeOS install providing those tools, many steps will fail or be skipped. The scripts run with Bun, so you need the Bun runtime as well.

• A LifeOS install that provides the LIFEOS/TOOLS scripts
• The Bun runtime to execute the bundled tool commands
• The referenced files ISAFormat.md and References/CompleteGuide.md

Install the ISA skill from the ZIP

Download the ZIP for the ISA skill from this page and unzip it. Then place the folder in one of two locations, depending on how you want to use it.

For a personal setup available across projects, put it in your user skills folder, ~/.claude/skills/. To limit it to a single project, put it in that project's .claude/skills/ folder instead.

Alternatively, you can upload the skill in the Claude apps. Go to Settings → Capabilities → Skills and upload it there.

• Personal (all projects): ~/.claude/skills/
• Single project: the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills

Trigger the ISA skill with natural requests

You do not need a special command. The skill loads when your request matches its trigger phrases. Ordinary wording works, such as asking the agent to confirm direction or to write down what done means.

Good triggers include words like ISA, ideal state, restate, say it back, are we building the right thing, drift check, discovery interview, are we aligned, and rate this ISA. Ask in plain language and name the outcome you want.

• "Write an ISA for this feature before we build it."
• "Restate the ideal state back to me so I can confirm the direction."
• "Are we aligned on what done means for this project?"
• "Rate this ISA and tell me what is weak."
• "Render this ISA as HTML and open it in the browser."

Work through an example session

Suppose you want an agent to add a feature to a project. Start by asking for a new ISA from your prompt. The agent scaffolds the ladder and criteria, then asks you to restate the direction. If your reply is more than a clean yes, the agent runs a Discuss round to settle the open points before building.

Once the direction is agreed, the criteria become the checklist the agent builds against. The example files in the skill show this shape with small teaching projects, such as a command-line flag and a backup verification feature.

• Ask for a new ISA for the feature
• Confirm or correct the restated direction
• Answer the open questions the agent raises
• Build against the agreed criteria
• Run a drift check later if the work drifts from the summary

Safety notes: scripts and network

The skill runs scripts. Read the bundled commands before letting the agent run them in a sensitive project, and make sure you trust the LifeOS tools they call. The skill's metadata lists it as running scripts and not using the network.

Because the skill depends on tools outside this folder, check which scripts exist in your LifeOS install before relying on the workflow.

• Runs scripts: yes
• Uses network: no
• Review the LIFEOS/TOOLS scripts it calls before first use

Tips for getting good results

The process is heavy by design. For a quick one-off change, a written done-definition may cost more time than it saves. Use the ISA for work where agreeing on direction matters more than speed.

Answer the restate question carefully. The skill treats a vague yes as a reason to keep discussing, which is the intended behaviour.

• Use it before new projects or changed directions, not for every small edit
• Keep the ISA in place and extend it rather than creating a second document
• Ask for a rating to find weak criteria before building