Set Up the Business-First AI Framework Skills

Seven skills and an agent implementing the Business-First AI Framework — from analyzing where AI fits in your workflows through building, testing, running, and improving working AI workflows. Find your platform below and follow the setup instructions.

Set Up These Skills

Find your platform below and click to expand the setup instructions. Each section has everything you need — no jumping between pages.

Skill Support by Platform

For a full comparison of platforms — skill support status, directory locations, execution environments, and filesystem access — see Platform Implementations and Where Skills Run on the Skills building block page.

---

Chat & Desktop Platforms

Use AI through a browser or desktop app? Find your platform and click to expand.

Claude Chat (claude.ai) — ✅ Native skill support

Claude.ai officially supports Agent Skills. You upload a skill file and Claude uses it automatically in your conversations.

Official docs: Use Skills in Claude

What you need first: A Claude Pro, Max, Team, or Enterprise subscription.

Step 1 — Turn on code execution

1. Go to claude.ai in your web browser
2. Look at the bottom-left corner of the screen and click the gear icon (⚙️) to open Settings
3. In Settings, click Capabilities in the left menu
4. Find the toggle next to Code execution and make sure it’s turned on (it should appear blue/active)

This setting lets Claude run skills — it does not give Claude access to your computer.

Step 2 — Download a skill

1. Open the skill downloads page in your web browser
2. Scroll down to the Assets section — you’ll see a list of .zip files, one for each skill
3. Click analyze.zip to download it (start with Analyze — it’s Step 1 of the framework)

The file downloads to your computer (usually to your Downloads folder). You can download multiple skills at once if you like.

Step 3 — Upload the skill to Claude

1. Go back to claude.ai in your browser
2. Open Settings (gear icon in the bottom-left) → Capabilities
3. Scroll down and click Upload skill
4. Select the analyze.zip file you just downloaded

Step 4 — Turn the skill on

After uploading, find “analyze” in your Skills list and make sure the toggle next to it is on (blue/active).

Step 5 — Test it

Start a new chat on claude.ai and type:

Help me analyze AI workflow opportunities

Claude should begin a structured interview process — asking about your role, your workflows, and where AI might help.

Step 6 — Add more skills as you need them

Go back to the skill downloads page and download the next skill you need. Repeat Steps 3–4 for each one.

Framework Step	Skill	Direct download
1	Analyze	analyze.zip
2	Deconstruct	deconstruct.zip
3	Design	design.zip
4	Build	build.zip
5	Test	test.zip
6	Run	run.zip
7	Improve	improve.zip

Start with Analyze and Deconstruct — add the rest as you progress through the framework.

For advanced management (updates, troubleshooting), see Using Plugins.

Claude Cowork (Desktop App) — ✅ Native skill support

Cowork has a built-in plugin directory — no files to download or copy. This is the simplest setup path.

Official docs: Use Plugins in Cowork

What you need first: The Claude Desktop app installed, with a Claude Pro, Max, Team, or Enterprise subscription.

Step 1 — Turn on code execution

Skills require code execution to be enabled. If you haven’t already:

1. In the Claude Desktop app, click the gear icon (⚙️) in the bottom-left to open Settings
2. Click Capabilities
3. Make sure the toggle next to Code execution and file creation is turned on (blue)

This lets Claude run skills — it does not give Claude access to your computer. See Use Skills in Claude for details.

Step 2 — Open Cowork

1. Open the Claude Desktop app
2. At the top center of the window, you’ll see three tabs: Chat, Cowork, and Code. Click Cowork.

Step 3 — Go to Customize

1. In the left sidebar, click Customize (near the bottom of the sidebar)
2. Click Browse plugins — this opens the plugin directory

Step 4 — Add the marketplace (one-time setup)

If this is your first time, you need to add the Hands-on AI marketplace:

1. In the plugin directory, click the Personal tab at the top
2. Click the + button (next to the marketplace name area)
3. Click Add marketplace
4. In the “Add marketplace” dialog, type jamesgray-ai/handsonai-plugins in the URL field
5. Click Sync

You only need to do this once — the marketplace is remembered.

Step 5 — Install the Business First AI plugin

1. After syncing, you should see Business first ai as a plugin card in the Personal tab
2. Click the + button on the Business first ai card to install it

Checking for updates

Plugins don’t update automatically. To get the latest skills, go back to Customize → Browse plugins → Personal tab, click the … menu next to handsonai-plugins, and choose Check for updates.

Step 6 — Start using it

Skills are available immediately — no restart needed. Go back to Cowork and describe what you need in plain language. For example, type:

Help me analyze where AI fits in my work

Cowork automatically activates the right skill based on your request.

Claude Code (Desktop App) — ✅ Native skill support

The Claude Desktop app includes a Code tab that supports plugins and skills.

Official docs: Extend Claude with Skills · Discover and Install Plugins

What you need first: The Claude Desktop app installed, with a Claude Max subscription (the Code tab requires Max).

Step 1 — Open the Code tab

1. Open the Claude Desktop app
2. At the top center of the window, you’ll see three tabs: Chat, Cowork, and Code. Click Code.

Step 2 — Add the marketplace (one-time setup)

1. In the left sidebar, click Customize
2. Click Browse plugins
3. Click the Personal tab at the top
4. Click the + button, then click Add marketplace
5. In the “Add marketplace” dialog, type jamesgray-ai/handsonai-plugins in the URL field
6. Click Sync

You only need to do this once.

Step 3 — Install the plugin

1. After syncing, you should see Business first ai as a plugin card in the Personal tab
2. Click the + button on the Business first ai card to install it

Step 4 — Test it

Go back to the Code tab and type:

/handsonai:analyze

Press Enter. The Analyze skill should start running and begin asking you questions. You can also just type “Help me analyze AI workflow opportunities” and Claude will activate the right skill automatically.

Alternative: install using slash commands

You can also install directly from the Code tab’s input area using slash commands. Type the first command and press Enter:

/plugin marketplace add jamesgray-ai/handsonai-plugins

Then type this command and press Enter:

/plugin install handsonai@handsonai

This achieves the same result as the visual method above.

For updates, uninstalling, and troubleshooting, see Using Plugins.

ChatGPT — 🟡 Beta / Limited native support

There are three ways to use these skills with your ChatGPT account, listed from best to simplest:

Option 1: Native Skills (Best — if your plan supports it)

ChatGPT is rolling out native skill support using the same SKILL.md format. Skills work directly in ChatGPT and output files can be downloaded from the chat. This is the best option if available on your plan (currently Enterprise, Edu, and some Team/Business plans — admins may need to enable it).

If you don’t see a Skills option in your ChatGPT settings, try Option 2 or 3 below.

Step 1 — Download the skills

1. Open the skill downloads page in your web browser
2. Scroll down to the Assets section — you’ll see a list of .zip files, one for each skill
3. Click each skill .zip to download it. Start with analyze.zip and deconstruct.zip — add the rest as you progress through the framework.

The files download to your computer (usually to your Downloads folder).

Framework Step	Skill	Direct download
1	Analyze	analyze.zip
2	Deconstruct	deconstruct.zip
3	Design	design.zip
4	Build	build.zip
5	Test	test.zip
6	Run	run.zip
7	Improve	improve.zip

Step 2 — Upload the skills to ChatGPT

Follow OpenAI’s official guide to upload the .zip files you just downloaded: Skills in ChatGPT. The guide walks through enabling Skills in your workspace and uploading skill .zip files from your computer.

Step 3 — Test it

Start a new ChatGPT conversation and type:

Help me analyze AI workflow opportunities

ChatGPT should activate the Analyze skill and begin a structured interview process.

Option 2: OpenAI Codex in a Code Editor

Use OpenAI Codex in a code editor like Cursor or VS Code. Codex uses your existing ChatGPT login (Plus, Pro, or any paid plan), supports skills natively, and saves output files directly to your computer — so when a skill creates a Workflow Definition or Building Block Spec, you get an actual file instead of text in a chat window.

See the OpenAI Codex section under Code Editors & Terminal below for setup instructions.

Option 3: ChatGPT Projects (Simplest — works on all paid plans)

Official docs: Projects in ChatGPT

What you need first: A ChatGPT Plus, Team, or Enterprise subscription.

A Project in ChatGPT is like a folder where ChatGPT remembers specific instructions for all conversations inside it. You’ll create one Project per skill, and paste the skill’s instructions into it.

Step 1 — Copy the skill instructions

1. Scroll down to the Skill Files table on this page
2. Click the SKILL.md link for Analyze (the first skill in the framework) — this opens a page on GitHub showing the skill’s text

Step 2 — View the raw text

1. On the GitHub page, look near the top-right of the file content area
2. Click the button that says Raw — this shows you the plain text without any GitHub formatting

Step 3 — Select and copy all the text

1. Click anywhere on the page, then:
   • Mac: Press Cmd+A (this selects all the text), then press Cmd+C (this copies it)
   • Windows: Press Ctrl+A (selects all), then press Ctrl+C (copies it)

Step 4 — Create a new Project in ChatGPT

1. Go to chatgpt.com in your web browser
2. In the left sidebar, look for Projects and click it
3. Click New Project

Step 5 — Name the Project

Give it a clear name that matches the skill, like “Analyze Workflows” or “Step 1 — Analyze”.

Step 6 — Add the instructions

1. Click Instructions (or “Custom Instructions”) — a text box appears
2. Click inside the text box
3. Paste the text you copied:
   • Mac: Press Cmd+V
   • Windows: Press Ctrl+V

Step 7 — Save

Click Save or Done.

Step 8 — Use the skill

1. Open your new “Analyze Workflows” Project from the sidebar
2. Start a conversation by typing:

Help me analyze where AI fits in my work

ChatGPT will follow the skill’s structured interview process — asking about your role, workflows, and where AI might help.

Step 9 — Add more skills later

Repeat steps 1–7 for Deconstruct (the next step in the framework). Add the remaining skills as you progress.

About file saving with Projects

When a skill says it will “save output to a file,” ChatGPT Projects will show the output in the chat instead — copy and save it yourself. For automatic file saving, use Option 1 (Native Skills) or Option 2 (OpenAI Codex) above.

Google Gemini (app) — 🟠 Workaround using Gems

The Gemini app does not natively support Agent Skills yet. These instructions use Gems — Gemini’s custom AI personas — to achieve the same result. You paste the skill’s instructions into a Gem, and Gemini follows them.

Official docs: Use Gems in Gemini Apps

What you need first: A Gemini Advanced subscription (required for the Gems feature).

Step 1 — Copy the skill instructions

1. Scroll down to the Skill Files table on this page
2. Click the SKILL.md link for Analyze (the first skill) — this opens a page on GitHub

Step 2 — View the raw text

1. On the GitHub page, look near the top-right of the file content area
2. Click the button labeled Raw — this shows the plain text

Step 3 — Select and copy all the text

1. Click anywhere on the page, then:
   • Mac: Press Cmd+A (selects all), then Cmd+C (copies)
   • Windows: Press Ctrl+A (selects all), then Ctrl+C (copies)

Step 4 — Create a new Gem

1. Open gemini.google.com in your browser
2. In the left sidebar, click Gem manager
3. Click New Gem (or Create Gem)

Step 5 — Name the Gem

Type a name that matches the skill, like “Analyze Workflows”.

Step 6 — Paste the instructions

1. Click inside the large Instructions text box
2. Paste the text you copied:
   • Mac: Press Cmd+V
   • Windows: Press Ctrl+V

Step 7 — Save the Gem

Click Save.

Step 8 — Use the Gem

1. Find your new Gem in the left sidebar and click it to open a conversation
2. Type:

Help me analyze where AI fits in my work

Gemini will follow the skill’s structured interview process.

Step 9 — Add more Gems later

Repeat these steps for Deconstruct (Step 2). Create additional Gems as you progress through the framework.

About file saving

When a skill says it will “save output to a file,” Gemini will show the output in the chat instead. Copy and save it yourself.

M365 Copilot — ✅ Native skill support (via Copilot Cowork)

M365 Copilot now natively supports Agent Skills through Copilot Cowork. Cowork reads SKILL.md files directly from a folder on your OneDrive — no plugin install or paste step required. Each skill loads automatically when relevant to your conversation.

Official docs: Cowork skills (Microsoft Learn)

What you need first: An M365 Copilot license and enrollment in the Frontier preview program (Cowork is currently a Frontier preview feature). Ask your IT admin if you’re not sure whether your tenant is enrolled.

Step 1 — Open OneDrive

Open OneDrive in whichever way is easiest:

• Windows: Open File Explorer → click OneDrive in the left sidebar
• Mac: Open Finder → click OneDrive in the sidebar (install the OneDrive app if needed)
• Browser: Go to onedrive.live.com and sign in with your Microsoft 365 account

Step 2 — Create the Cowork Skills folder

Inside Documents/, create the path Cowork/Skills/ if it doesn’t already exist:

1. Open the Documents folder
2. Create a new folder named Cowork
3. Open Cowork and create a new folder inside it named Skills

The full path should now be Documents/Cowork/Skills/.

Step 3 — Create a folder for the Analyze skill

Inside Documents/Cowork/Skills/, create a new folder named analyze.

Step 4 — Download the SKILL.md

1. Scroll down to the Skill Files table on this page
2. Click the SKILL.md link for Analyze — this opens GitHub
3. Right-click the Raw button (top-right of the file content area) and choose Save link as…
4. Name the file SKILL.md and save it inside the Documents/Cowork/Skills/analyze/ folder you just created

If your browser doesn’t show a Save link as… option, click Raw, then copy all the text on the page and paste it into a new plain-text file named SKILL.md inside the same folder.

Step 5 — Test it

1. Open M365 Copilot Cowork and start a new conversation

2. Type:

   Help me analyze where AI fits in my work

3. Cowork loads the skill automatically. You’ll see it appear as a chip in the side panel Skills section, and Cowork follows the skill’s structured interview.

Step 6 — Add more skills

Repeat Steps 3–4 for Deconstruct (Step 2) and any other framework skill you need. Each skill goes in its own subfolder under Documents/Cowork/Skills/.

Limits

You can create up to 20 custom skills, and each SKILL.md can be up to 1 MB.

---

Code Editors & Terminal

Use AI through a code editor or terminal? Find your tool and click to expand.

Claude Code (Terminal) — ✅ Native skill support

Claude Code in the terminal has full plugin and skill support. One command installs all 7 skills plus the orchestrator agent.

Official docs: Extend Claude with Skills · Discover and Install Plugins

What you need first: Claude Code installed and running in your terminal, with a Claude Pro, Max, Team, or Enterprise subscription. If you haven’t installed Claude Code yet, see the Claude Code setup guide.

Step 1 — Add the marketplace (one-time setup)

In your Claude Code session, type this command and press Enter:

/plugin marketplace add jamesgray-ai/handsonai-plugins

This tells Claude Code where to find the skills. You only need to do this once — it’s remembered across sessions.

Step 2 — Install the plugin

Type this command and press Enter:

/plugin install handsonai@handsonai

This downloads and installs all 7 skills plus the orchestrator agent.

Step 3 — Verify it worked

Type /plugin list and press Enter. You should see business-first-ai in the list with all its skills.

Step 4 — Test it

Type /handsonai:analyze and press Enter. The Analyze skill should start running and begin asking you questions. You can also just type “Help me analyze AI workflow opportunities” and Claude will activate the right skill automatically.

For updates, uninstalling, and troubleshooting, see Using Plugins.

Cursor — ✅ Native skill support

Cursor reads Agent Skill files from your project folder automatically.

Official docs: Agent Skills — Cursor

What you need first: Cursor installed and a project folder open. If you haven’t installed Cursor yet, see the Editor Setup guide for step-by-step instructions. Your project root is the top-level folder you have open in Cursor — this is where Cursor looks for skills.

Step 1 — Download a skill

1. Open the skill downloads page in your web browser
2. Scroll down to the Assets section — you’ll see a list of .zip files, one for each skill
3. Click analyze.zip to download it (start with Analyze — it’s Step 1 of the framework)

The file downloads to your computer (usually to your Downloads folder). You can download multiple skills at once if you like.

Step 2 — Extract (unzip) the file

1. Find analyze.zip in your Downloads folder
2. Double-click it — this creates a folder called analyze containing the skill file

Step 3 — Create the skills directory in your project

1. Open your project folder (the one you have open in Cursor) in Finder (Mac) or File Explorer (Windows)
2. Create a new folder called .agents inside your project folder
3. Inside .agents, create another folder called skills
4. You should now have: your-project/.agents/skills/

Can’t see the folder?

On Mac, folders starting with . are hidden by default. In Finder, press Cmd+Shift+. (period key) to show hidden folders.

Step 4 — Move the skill folder into your project

Move (or copy) the analyze folder from Step 2 into the .agents/skills/ folder you just created. You should now have: your-project/.agents/skills/analyze/SKILL.md

Step 5 — Restart Cursor

Close and reopen Cursor (or reopen your project). Cursor discovers skills automatically when they’re in the right folder.

Step 6 — Test it

In Cursor’s chat, type: “Use the analyze skill to help me find AI workflow opportunities.”

Step 7 — Add more skills

Go back to the skill downloads page and download the next skill you need. Repeat Steps 2–4 for each one.

Framework Step	Skill	Direct download
1	Analyze	analyze.zip
2	Deconstruct	deconstruct.zip
3	Design	design.zip
4	Build	build.zip
5	Test	test.zip
6	Run	run.zip
7	Improve	improve.zip

Cross-platform shortcut

The .agents/skills/ folder is recognized by Cursor, Codex CLI, Gemini CLI, and VS Code Copilot — place skills there to share them across tools.

OpenAI Codex — ✅ Native skill support

OpenAI Codex reads Agent Skill files from your project folder automatically. This works across all Codex environments — the CLI, desktop app, and IDE extension (VS Code, Cursor).

Official docs: Agent Skills — Codex

What you need first: OpenAI Codex installed (CLI, desktop app, or IDE extension). If you haven’t set it up yet, see Getting Started with OpenAI for installation steps. Your project root is the top-level folder you’re working in — the folder open in your editor or that you navigated to in your terminal.

Step 1 — Download a skill

1. Open the skill downloads page in your web browser
2. Scroll down to the Assets section — you’ll see a list of .zip files, one for each skill
3. Click analyze.zip to download it (start with Analyze — it’s Step 1 of the framework)

The file downloads to your computer (usually to your Downloads folder). You can download multiple skills at once if you like.

Step 2 — Extract (unzip) the file

Double-click analyze.zip in your Downloads folder — this creates a folder called analyze containing the skill file.

Step 3 — Create the skills directory in your project

In your project folder, create a .agents/skills/ directory. From a terminal you can run:

mkdir -p .agents/skills

Or create the folders manually in Finder/File Explorer: create a folder called .agents inside your project, then create skills inside that.

Step 4 — Move the skill folder into your project

Move (or copy) the analyze folder from Step 2 into .agents/skills/ in your project. You should now have: your-project/.agents/skills/analyze/SKILL.md

Step 5 — Test it

Open your project in Codex (CLI, desktop app, or IDE extension) and say: “Use the analyze skill to help me find AI workflow opportunities.” Codex discovers skills automatically.

Step 6 — Add more skills

Go back to the skill downloads page and download the next skill you need. Repeat Steps 2–4 for each one.

Framework Step	Skill	Direct download
1	Analyze	analyze.zip
2	Deconstruct	deconstruct.zip
3	Design	design.zip
4	Build	build.zip
5	Test	test.zip
6	Run	run.zip
7	Improve	improve.zip

Gemini CLI / Antigravity — ✅ Native skill support

Google’s developer tools — Gemini CLI (command-line) and Antigravity (AI-native IDE) — both read Agent Skill files from your project folder automatically. (For the Gemini web app, see the Google Gemini (app) section above under Chat & Desktop.)

Official docs: Agent Skills — Gemini CLI · Getting Started with Antigravity Skills

What you need first: Gemini CLI or Antigravity installed. If you haven’t set these up yet, see Getting Started with Google Gemini for Gemini CLI installation, or download Antigravity from antigravity.google. Your project root is the top-level folder you’re working in — the folder open in Antigravity or that you navigated to in your terminal.

Step 1 — Download a skill

1. Open the skill downloads page in your web browser
2. Scroll down to the Assets section — you’ll see a list of .zip files, one for each skill
3. Click analyze.zip to download it (start with Analyze — it’s Step 1 of the framework)

The file downloads to your computer (usually to your Downloads folder). You can download multiple skills at once if you like.

Step 2 — Extract (unzip) the file

Double-click analyze.zip in your Downloads folder — this creates a folder called analyze containing the skill file.

Step 3 — Create the skills directory in your project

In your project folder, create a .gemini/skills/ directory. From a terminal you can run:

mkdir -p .gemini/skills

Or create the folders manually in Finder/File Explorer: create a folder called .gemini inside your project, then create skills inside that.

Cross-platform alternative

You can also use .agents/skills/ instead — both Gemini CLI and Antigravity recognize it, and it’s also compatible with Cursor, Codex, and VS Code Copilot.

Step 4 — Move the skill folder into your project

Move (or copy) the analyze folder from Step 2 into .gemini/skills/ (or .agents/skills/) in your project. You should now have: your-project/.gemini/skills/analyze/SKILL.md

Step 5 — Test it

Open your project in Gemini CLI or Antigravity and say: “Use the analyze skill to help me find AI workflow opportunities.” Skills are discovered automatically.

Step 6 — Add more skills

Go back to the skill downloads page and download the next skill you need. Repeat Steps 2–4 for each one.

Framework Step	Skill	Direct download
1	Analyze	analyze.zip
2	Deconstruct	deconstruct.zip
3	Design	design.zip
4	Build	build.zip
5	Test	test.zip
6	Run	run.zip
7	Improve	improve.zip

---

Using a different tool (VS Code Copilot, Perplexity, or another platform)? See How to Add Skills to Your Platform for additional platforms.

Skill Files

These are the direct links to each skill’s instruction file on GitHub. Used by the ChatGPT, Gemini, and M365 Copilot Cowork setup instructions above — and useful for any platform where you need to copy or download the skill text.

How to copy a skill: Click the SKILL.md link → click the Raw button (top-right of the file) → select all text (Cmd+A on Mac, Ctrl+A on Windows) → copy (Cmd+C / Ctrl+C).

Step	Skill	File
1	Analyze	SKILL.md
2	Deconstruct	SKILL.md
3	Design	SKILL.md
4	Build	SKILL.md
5	Test	SKILL.md
6	Run	SKILL.md
7	Improve	SKILL.md

About the Build skill

The Build skill (Step 4) also has reference files that it uses. On platforms with native skill support (Claude, Cursor, Codex CLI, Gemini CLI), these are included automatically. M365 Copilot Cowork’s documented format only describes a single SKILL.md per skill folder, so until Microsoft documents reference-file support you’ll need to paste the references/agent-spec.md and references/skill-spec.md contents into the body of SKILL.md after the main instructions. On paste-based platforms (ChatGPT Projects, Gems), copy and paste the references/agent-spec.md and references/skill-spec.md files after the SKILL.md content when you set up Build.

Using These Skills

Once you’ve installed or set up the skills for your platform, here’s how to use them:

Platform	How to start
Claude Chat	Start a new chat. Claude uses your installed skills automatically. Say “Help me analyze AI workflow opportunities.”
Claude Cowork (Desktop App)	Describe what you need. Cowork activates the right skill automatically.
Claude Code (Desktop App)	Type /handsonai:analyze in the Code tab, or describe your need. Same commands as the terminal.
Claude Code (Terminal)	Type /handsonai:analyze (or any slash command below). Or just describe your need — Claude picks the skill.
ChatGPT	Open the Project you created for the skill. Type your request.
Google Gemini (app)	Click the Gem in your sidebar. Type your request.
M365 Copilot	Start a Cowork conversation. Type your request — Cowork loads the matching skill from OneDrive automatically.
Cursor / OpenAI Codex / Gemini CLI / Antigravity	Ask by skill name — e.g., “Use the analyze skill.” Skills are discovered automatically.

Claude Code slash commands:

Command	Skill
/handsonai:analyze	Analyze — Step 1
/handsonai:deconstruct	Deconstruct — Step 2
/handsonai:design	Design — Step 3
/handsonai:build	Build — Step 4
/handsonai:test	Test — Step 5
/handsonai:run	Run — Step 6
/handsonai:improve	Improve — Step 7

Recommended Path

1. Run Analyze — say “Help me analyze AI workflow opportunities” — Step 1
2. Run Deconstruct — say “I want to deconstruct my [workflow] into AI building blocks” — Step 2
3. Run Design to design the AI workflow architecture — Step 3
4. Run Build to generate platform artifacts — Step 4
5. Run Test to evaluate and establish a quality baseline — Step 5
6. Run Run to deploy and operationalize — Step 6
7. Run Improve to evaluate and evolve running workflows — Step 7

Claude Code users

You can also invoke skills directly with slash commands like /handsonai:analyze. See the table above.

Components

---

Step 1-7 — Full Orchestration

---

framework-orchestrator

What it does: Orchestrates the end-to-end framework process across all seven steps. Runs candidate discovery, deep deconstruction, design, build, test, run, and improve sequentially, with file-based handoffs between stages so you can also run each step individually in separate conversations.

When to use it: Use this when you want to go through the entire process in one session. The agent manages the flow between steps, saves intermediate files, and keeps you involved at each stage. If you prefer to work step-by-step across separate conversations, invoke the individual skills instead.

How it works: The agent runs seven skills across the full lifecycle:

1. Analyze (analyze) — Audit your workflows, interview you about your work, and produce an opportunity report with structured candidates. If you already know which workflow to deconstruct, this step is brief.
2. Deconstruct (deconstruct) — Interactive deep-dive that decomposes the workflow into refined steps using the 6-question framework. Produces the Workflow Definition.
3. Design (design) — Gather architecture decisions, assess workflow autonomy level, choose an orchestration mechanism and involvement mode, classify steps, map building blocks, identify skill candidates, configure agents, and produce the AI Building Block Spec.
4. Build (build) — Resolve context needs and generate platform-appropriate artifacts (prompts, skills, agents, configs) based on the approved spec.
5. Test (test) — Run structured evaluations against the criteria from Design, establish a quality baseline, and iterate with Build until the workflow is ready.
6. Run (run) — Generate a Run Guide tailored to your platform and technical comfort level, choose a run pattern, and deploy.
7. Improve (improve) — Evaluate a running workflow for quality signals, regression, and graduation opportunities.

Files are saved to outputs/ using kebab-case workflow names (e.g., outputs/lead-qualification-definition.md).

Example prompts:

“I want to deconstruct my client onboarding workflow” → Walks you through all seven steps, asking questions during discovery, presenting the analysis for review, and generating the build deliverables

“People keep dropping off during enrollment. Help me build a workflow for that.” → Starts from a problem description, proposes a candidate workflow, then deconstructs and designs it

“Help me figure out which parts of my weekly reporting process could be automated with AI” → Decomposes the reporting process, assesses autonomy, chooses an orchestration mechanism, and identifies quick wins vs. complex automation opportunities

What you’ll get: Multiple files in outputs/:

1. Opportunity Report — ai-opportunity-report.md — categorized opportunities with structured workflow candidates (if generated)
2. Workflow Definition — [name]-definition.md — structured decomposition of every step
3. AI Building Block Spec — [name]-building-block-spec.md — autonomy level, orchestration mechanism, per-step classifications, building block mapping, skill candidates, agent configs
4. Platform Artifacts — prompts, skills, agents, and configs generated for your platform
5. Run Guide — [name]-run-guide.md — step-by-step setup and first-run instructions
6. Improvement Plan — [name]-improvement-plan.md — eval results, quality signals, and recommended actions (when running Improve)

---

Step 1 — Analyze Workflows

Find which workflows are candidates for AI.

---

analyze

Command: /handsonai:analyze

What it does: Runs a structured audit of your workflows to analyze where AI can help. Supports two lenses: Individual (your personal workflows) and Organizational (your business’s value chain processes). Scans memory and conversation history, asks which lens to use, interviews you with lens-specific questions, then produces a prioritized opportunity report with structured workflow candidates ready for the Deconstruct step.

When to use it: Use this when you want to figure out where AI fits in your work. Especially useful when you’re new to AI and need a starting point, or when you want a systematic review before choosing which workflow to deconstruct.

How it works:

1. Memory & history scan — The AI reviews everything it knows about you from prior conversations, memory, and project files. Presents findings for you to confirm or correct.
2. Lens selection — The AI asks which lens to use: Individual (your personal workflows) or Organizational (your business’s value chain). Infers if obvious from context.
3. Targeted discovery interview — The AI asks focused, lens-specific questions one at a time. Individual lens: role, repetitive tasks, information synthesis, multi-step processes, quality issues, communication overhead, decision-making. Organizational lens: business objectives, value chain processes, cross-functional handoffs, bottlenecks, consistency risks, measurement gaps, scale constraints. Follows up based on your answers.
4. Opportunity analysis & report — Produces a summary table and detailed opportunity cards grouped by autonomy level (Deterministic, Guided, Autonomous) with involvement mode (Augmented, Automated), ordered by impact.
5. Workflow candidate summary — You pick your top candidates, and the AI produces structured metadata for each: name, description, trigger, deliverable, autonomy, involvement, pain point, AI opportunity, frequency, priority, reasoning, and lens. Organizational candidates also include business objective, stakeholders, and success metrics. Recommends which to deconstruct first.
6. Second lens follow-up — The AI offers to explore the other lens for a more complete picture.

Example prompts:

“Help me analyze AI workflow opportunities” → Runs the full audit and produces a categorized opportunity report with structured workflow candidates

“I want to figure out which parts of my job could benefit from AI” → Interactive discovery session followed by a structured report with specific, actionable recommendations

What you’ll get: An opportunity report (outputs/ai-opportunity-report.md) with a report header (including lens), summary table, top 3 recommendations, detailed cards for each opportunity (with organizational fields for org-lens candidates), and a structured workflow candidate summary with metadata for each candidate you select.

Platform compatibility: Claude Code ✓ | Claude.ai ✓

---

Step 2 — Deconstruct Workflows

Break workflows into structured definitions.

---

deconstruct

Command: /handsonai:deconstruct

What it does: Interactively deconstructs a business workflow into a structured Workflow Definition using the 6-question framework. This is the Deconstruct step.

When to use it: Use this when you want to thoroughly document a workflow’s steps, decisions, data flows, and failure modes. Also useful standalone when you just need a structured breakdown of a complex process — even without planning to automate it.

How it works:

1. Scenario analysis — The AI determines how you’re arriving: if you reference an opportunity report from the Analyze step, it reads the workflow candidates and pre-populates metadata. Otherwise, it asks about the business scenario, objective, high-level steps, and ownership. If you describe a problem instead of a workflow, the AI proposes a candidate workflow for you to react to.
2. Scope check — The AI assesses whether this is one workflow or multiple bundled together. If multiple, it recommends splitting and asks which to start with.
3. Name the workflow — The AI presents 2-3 name options (2-4 word noun phrases, Title Case) and confirms name, description, outcome, trigger, and type.
4. Deep dive — For each step, the AI probes six dimensions:
   • Discrete steps (is this actually multiple steps?)
   • Decision points (if/then branches, quality gates)
   • Data flows (inputs, outputs, sources, destinations)
   • Context needs (specific documents, files, reference materials)
   • Failure modes (what happens when this step fails)
   • Data readiness (can AI access, interpret, and persist the data this step needs?)
5. Propose and react — From step 4 onward, the AI proposes a hypothesis across all six dimensions and asks “What’s right, what’s wrong, what am I missing?”
6. Map sequence — The AI identifies sequential vs. parallel steps and the critical path
7. Consolidate context — The AI presents a rolled-up “context shopping list” of every artifact the workflow needs
8. Generate Workflow Definition — The AI writes the structured Workflow Definition to the output file

Example prompts:

“Use deconstruct to break down my expense reporting process” → Interactive discovery session producing outputs/expense-reporting-definition.md

“I need to document how our team handles customer escalations” → Walks through the discovery process, probing for hidden steps and decision points

What you’ll get: A Workflow Definition file (outputs/[name]-definition.md) containing: scenario metadata, refined steps (with sub-steps, decision points, data flows, context needs, and failure modes for each), step sequence and dependencies, and a context shopping list.

Platform compatibility: Claude Code ✓ | Claude.ai ✓

---

Step 3 — Design Workflows

Design your AI implementation architecture.

---

design

Command: /handsonai:design

What it does: Takes a Workflow Definition and runs the Design phase: architecture decisions, autonomy assessment, orchestration mechanism with involvement mode, per-step classification, building block mapping, skill candidates, agent configuration. Produces an AI Building Block Spec for approval.

When to use it: Use this when you have a Workflow Definition (from the Deconstruct step) and want to design your AI workflow’s architecture. The spec must be approved before moving to Build.

How it works:

1. Load Workflow Definition — The AI reads the Workflow Definition from outputs/
2. Confirm understanding — The AI summarizes the workflow and asks you to confirm
3. Architecture decisions — Confirm platform (the one question), then extract tool integrations, trigger/schedule, and constraints from the Workflow Definition and present a confirmation block
4. Autonomy assessment — The AI assesses where the whole workflow sits on the autonomy spectrum (Deterministic, Guided, Autonomous)
5. Orchestration mechanism — The AI recommends a mechanism (Prompt, Skill-Powered Prompt, or Agent) with an involvement mode (Augmented or Automated)
6. Classify each step — Per-step autonomy level, AI building blocks, tools, human review gates
7. Identify skill candidates — Steps tagged for skill creation with generation-ready detail
8. Agent configuration (when applicable) — Platform-agnostic agent blueprint
9. Generate AI Building Block Spec — Complete design document
10. Spec Approval Gate — Present the spec for approval. No artifacts are generated until you confirm.

Example prompts:

“Design the AI workflow from my Workflow Definition” → Reads the most recent Workflow Definition, runs Design, produces the AI Building Block Spec for approval

“Design the expense-reporting workflow” → Reads outputs/expense-reporting-definition.md, recommends an orchestration mechanism, and generates the spec

What you’ll get:

• AI Building Block Spec (outputs/[name]-building-block-spec.md) — architecture decisions, autonomy level, orchestration mechanism with involvement mode, step classifications, skill candidates, agent configs, implementation order

Platform compatibility: Claude Code ✓ | Claude.ai ✓

---

Step 4 — Build Workflows

Generate platform artifacts from your approved spec.

---

build

Command: /handsonai:build

What it does: Takes an approved AI Building Block Spec and generates platform-appropriate artifacts: prompts, skills, agents, configs, and connectors. Starts with a Prepare Context phase to resolve the context needs identified during Deconstruct and Design. Researches integration availability and resolves deferred platform decisions.

When to use it: Use this when you have an approved AI Building Block Spec (from the Design step) and want to generate the actual building blocks for your platform. Also useful when re-platforming — run Build again with the same spec but a different platform target. If returning from Test with issues, Build helps you fix the specific building blocks that need adjustment.

How it works:

1. Load Building Block Spec — The AI reads the approved spec from outputs/
2. Prepare Context — Resolve the Context Shopping List and Data Readiness Summary — find existing documents, create missing materials, format for AI consumption
3. Build path choice — Choose “I’ll build it” (model generates artifacts) or “I’ll build it myself” (get a Construction Guide with build sequence and creation skill recommendations)
4. Mechanism-specific build path — Only the steps relevant to your chosen orchestration mechanism
5. Discover creation tools — The AI scans your environment for skills that can create other building blocks (e.g., skill-creator, agent-development). Presents a Creation Tools Map for confirmation — matched skills get delegated to, unmatched types are generated inline.
6. Integration research — Web search to verify platform availability for every tool in the spec
7. Generate platform artifacts — For each building block, either delegates to the matched creation skill or generates inline using format specifications

Example prompts:

“Build the workflow from my Building Block Spec” → Reads the most recent spec, researches integrations, generates all platform artifacts

“Build the expense-reporting workflow for Claude Code” → Reads the spec, generates Claude Code-specific artifacts

What you’ll get:

• Platform Artifacts — prompts, skills, agents, and configs in whatever format your platform needs

Platform compatibility: Claude Code ✓ | Claude.ai ✓

---

Step 5 — Test Workflows

Structured testing and quality evaluation.

---

test

Command: /handsonai:test

What it does: Guides you through structured testing of your AI workflow artifacts — smoke test, full eval suite, building block evals, baseline establishment, and diagnosis. Uses the evaluation criteria and test scenarios defined during Design to measure output quality on a consistent scale.

When to use it: Use this after Build to verify that your workflow produces good output before deploying it. Also use it during Improve to re-run evals and detect regression on running workflows.

How it works:

1. Load artifacts and spec — The AI reads your Building Block Spec (for evaluation criteria and test scenarios) and locates your platform artifacts
2. Smoke test — Run the workflow once with a realistic scenario. Check: does it run, does it produce output, is the output in the right format?
3. Full eval suite — Run each test scenario from the Building Block Spec. Score each output on a 1-5 scale across the evaluation dimensions defined during Design.
4. Building block evals — Test individual components (skills, context, agents) in isolation to pinpoint weak links
5. Establish baseline — Calculate average scores across all scenarios and dimensions. Record for future comparison.
6. Diagnose and fix — Map problems to building blocks (generic output = context issue, skipped steps = prompt issue, etc.) and identify what to fix in Build
7. Readiness decision — Ready for deployment? Move to Run. Not ready? Return to Build with specific targets.

Example prompts:

“Test my workflow against the evaluation criteria” → Guides you through the smoke test, eval suite, and baseline

“My workflow output is too generic — help me diagnose” → Runs targeted building block evals to find the weak link

What you’ll get:

• Test Results — Eval scores per scenario and dimension, baseline averages, and a diagnosis of issues with recommended fixes

Platform compatibility: Claude Code ✓ | Claude.ai ✓

---

Step 6 — Run Workflows

Deploy and operate your tested workflow.

---

run

Command: /handsonai:run

What it does: Generates a plain-language Run Guide for deploying and operating your AI workflow. Covers artifact inventory, setup steps, first production run, run pattern selection, and operationalization guidance — tailored to your platform and build path.

When to use it: Use this after Test to deploy your workflow into production. Also useful independently to regenerate the Run Guide (e.g., for a teammate or after changing platforms).

How it works:

1. Load spec and artifacts — The AI reads your Building Block Spec and locates platform artifacts
2. Generate Run Guide — Artifact inventory, setup steps, first production run instructions, and next steps
3. Run pattern selection — Choose the right pattern: paste and run, run in a project, command an agent, code-first, or automate on schedule
4. Operationalization (for organizational workflows) — Sharing, training, governance, and adoption monitoring guidance

Example prompts:

“Generate the Run Guide for my workflow” → Reads the spec and artifacts, produces a deployment guide

“Help me set up my workflow to run on a weekly schedule” → Generates scheduling instructions for your platform

What you’ll get:

• Run Guide (outputs/[name]-run-guide.md) — step-by-step setup, first production run, run pattern, and operationalization guidance

Platform compatibility: Claude Code ✓ | Claude.ai ✓

---

Step 7 — Improve Workflows

Evaluate and evolve running workflows.

---

improve

Command: /handsonai:improve

What it does: Guides a structured improvement cycle for a running AI workflow — identify quality signals, re-run the eval suite for regression detection, assess whether the workflow should graduate to a more capable orchestration mechanism, and produce an Improvement Plan with specific actions.

When to use it: Use this when quality signals suggest a running workflow needs attention — increasing manual edits, changed business context, new tools available, or a scheduled review date. Also useful proactively on a regular cadence (monthly or quarterly) to catch issues before they affect output.

How it works:

1. Load history — The AI reads the Building Block Spec, previous test results, and baseline scores
2. Quality signal review — Discuss what prompted this improvement cycle. Which signals are you seeing?
3. Regression evaluation — Re-run the eval suite from Test. Compare current scores to baseline. Identify dimensions where quality has degraded or improved.
4. Graduation assessment — Should the orchestration mechanism evolve? Prompt to Skill-Powered Prompt, Skill-Powered Prompt to Agent, single agent to multi-agent? The AI assesses based on current pain points and workflow complexity.
5. Decision framework — Four outcomes: no changes needed, tune (fix specific building blocks), redesign (rework the architecture), or evolve (graduate the mechanism). Each outcome maps to a specific next step.
6. Generate Improvement Plan — Current scores, comparison to baseline, findings, decision, and specific actions

Example prompts:

“Evaluate my running workflow and help me decide what to improve” → Full improvement cycle with regression eval and decision

“My content workflow output quality has been dropping — help me figure out why” → Targeted regression evaluation focused on the quality dimensions that are degrading

What you’ll get:

• Improvement Plan (outputs/[name]-improvement-plan.md) — eval scores vs. baseline, quality signals, findings, graduation assessment, decision outcome, specific actions, and next review date

Platform compatibility: Claude Code ✓ | Claude.ai ✓

---

Recommended Workflow

These skills cover the full Business-First AI Framework. Here’s the recommended path:

1. Analyze — Run analyze to audit your workflows and identify where AI creates the most value
2. Deconstruct — Pick your highest-impact candidate and run deconstruct (or use the framework-orchestrator agent for the full end-to-end process)
3. Design — Run design to produce your AI Building Block Spec
4. Build — Run build to resolve context needs and generate platform artifacts from the approved spec
5. Test — Run test to evaluate output quality, establish a baseline, and iterate with Build until the workflow is ready
6. Run — Run run to get a Run Guide, choose a run pattern, and deploy. See the AI Workflow Examples plugin for working examples of real AI workflows.
7. Improve — Run improve periodically to catch regressions, evaluate quality signals, and evolve the workflow

FAQ

Which step should I start with? Start with Step 1 (Analyze) if you’re not sure where AI fits in your work. Browse AI Use Cases to see what types of work AI handles — content creation, research, coding, data analysis, ideation, and automation. Start with Step 2 (Deconstruct) if you already know which workflow you want to automate.

Can I start from a problem instead of a workflow? Yes. Tell the framework-orchestrator agent about your problem (e.g., “people keep dropping off during enrollment”) and it will propose a candidate workflow for you to refine during discovery.

What if I lose context mid-conversation? The file-based handoffs mean you can continue in a new conversation. Just invoke the next skill and point it at the file from the previous step (e.g., “Use deconstruct on outputs/lead-qualification-definition.md”).

What are AI building blocks? The 11 building blocks across three layers: Intelligence — Model (AI engine), Context (reference material), Memory (persistent knowledge), Project (workspace configuration). Orchestration — Prompt (single instruction), Skill (reusable routine), Agent (autonomous executor). Integration — MCP (tool connector protocol), API (programmatic interface), SDK (development framework), CLI (command-line interface). Each workflow step gets mapped to one or more of these.

How many iterations of Build-Test should I expect? Most workflows need 2-4 rounds of Build and Test before they produce reliably good output. Each iteration should be targeted — fix a specific building block, re-test, and measure improvement.

Where are the example agents and prompts? They’re in the AI Workflow Examples collection — agents for executive writing, editorial review, research, meeting prep, and AI news.

Do I need Claude Code for all of this? No. These skills work on Claude Chat, Claude Cowork, Claude Code, ChatGPT, Google Gemini, M365 Copilot, Cursor, OpenAI Codex, Gemini CLI, and Antigravity. See Set Up These Skills for step-by-step setup instructions for your specific platform.