AI-SHIPR — FAQ

AI-SHIPR has a clear folder structure. The core folders are:

S-Strategy/ — your vision, KPIs, and strategic bets
I-Initiatives/ — active work items linked to bets
H-Hypotheses/ — falsifiable hypotheses
P-Proof/ — experiments, launches, performance reads
R-Relationships/ — your PM profile, personas, stakeholders
I-Information/ — resources, templates, integrations
A-AI/ — agents, skills, workflows, playbooks

Start with the Setup Worksheet — it walks you through filling in each section in the right order. Then run the Half-Sprint Guide for a 5-day activation plan.

First move: open Half-Sprint-Guide.md and follow Day 1. It takes about 30 minutes.

If you manage multiple teams, enable Lead Mode by setting team_mode: lead in your Settings.md. This activates portfolio-level agents and skills.

Use the Portfolio-Strategist agent for cross-team bet coverage and resource allocation, and the Team-Manager agent for 1:1 prep and team health.

Each team can have its own initiatives folder or sub-folder. The Portfolio-Priority-Stack skill lets you rank initiatives across PMs and product areas from a single view.

Tip: keep one shared S-Strategy/ layer for the portfolio, and separate I-Initiatives/ sub-folders per team.

There are two common approaches depending on how separate the products are:

Option A — One vault, multiple strategy folders. Keep a shared AI-SHIPR root, but create separate S-Strategy/ sub-folders per product (e.g. S-Strategy/ProductA/, S-Strategy/ProductB/). Best when you own both products personally.

Option B — Separate vaults per product. Each product gets its own Obsidian vault and AI-SHIPR setup. Best when different PMs manage each product or the products are fully independent business lines.

When in doubt, start with Option A. You can always split later once you feel where the friction is.

AI-SHIPR has a built-in Figma integration. Once you add your Figma token to the integrations config, you can run /figma to pull your design assets directly into the session.

This lets you use design context inside PRD generation, edge case analysis, and hypothesis building — Claude can reference actual component names and flows from your Figma files.

You can also add a Designer agent to your A-AI/AI-Agents/ folder. Design it around your specific use case — UI review, accessibility checks, or design critique.

See I-Information/Integrations/Figma/ for setup instructions and the /figma skill for usage.

Open the playbook When-Creating-an-Agent from your A-AI/AI-Playbooks/ folder and paste it into Claude Code. It walks you through the full agent definition step by step.

An agent file lives in A-AI/AI-Agents/ and defines: the agent's name, its purpose, when to invoke it, how it thinks, and what it produces. You can also use the create-agent script to scaffold the file automatically.

Good agents have a single, specific purpose. If you're tempted to give it more than one job, split it into two agents.

Open the playbook When-Creating-a-Skill from your A-AI/AI-Playbooks/ folder. Skills live in A-AI/AI-Skills/ and are triggered by slash commands like /skill-name.

A skill is a single-task prompt file: it receives an input, applies a structured thinking process, and produces a specific output. Use the create-skill script to generate the boilerplate.

The difference between an agent and a skill: agents are persistent personas with broad judgment; skills are single-task tools you invoke on demand.

Obsidian is built around local markdown files — which is exactly how AI-SHIPR stores everything. There's no database, no sync lock-in, no proprietary format. Your files are yours.

Obsidian also makes it easy to navigate between files, see your folder structure, and open the system alongside Claude Code in a split view. VS Code works too, but it's optimized for code — Obsidian is optimized for knowledge and documents.

The deeper reason: files are the right interface for Claude Code. Claude reads and writes files natively. Obsidian lets you see and manage those files without friction.

You can use VS Code if you prefer. The system works the same — Obsidian is a recommendation, not a requirement.

Skills from other frameworks (like awesome-pm-skills or community repos) are not drop-in compatible — they need to be rewrapped into the AI-SHIPR skill format before they will work correctly inside the system.

The process: copy the skill's prompt content, open When-Creating-a-Skill, and ask Claude to reformat it using the AI-SHIPR skill structure. This takes about 20–30 minutes per skill and ensures it integrates properly with your strategy context and other workflows.

Don't import skills blindly. Each skill you add has a maintenance cost. Prioritize the ones that solve a real gap in your current workflow.

New versions of AI-SHIPR are distributed as a zip file. When a new version arrives, unzip it into a temporary folder alongside your existing vault — then let Claude handle the merge.

Paste this prompt into Claude Code, with the correct paths filled in:

I have two versions of AI-SHIPR:
- My current vault: [path to your current AI-SHIPR folder]
- New version (unzipped): [path to the new version folder]

Compare the system files and update my current vault. Follow these rules:

UPDATE only these folders:
- A-AI/ (agents, skills, workflows, playbooks)
- Root CLAUDE.md

DO NOT touch or overwrite:
- S-Strategy/, I-Initiatives/, H-Hypotheses/, P-Proof/
- R-Relationships/, Learning.md, Settings.md
- Any file I have customised

For each file you update, tell me what changed.
If a new system file conflicts with a customisation I've made, flag it and ask before overwriting.

When done, give me a summary: files added, files updated, files skipped.

Claude will diff the two versions, apply only the system-level changes, and leave your personal data untouched. It will also flag any conflicts before acting on them.

Your data files (Strategy, Initiatives, Learning.md) should never be overwritten by an update. If Claude flags a conflict on one of those, choose "skip" — your version wins.

Both are agentic — they can take multi-step actions autonomously — but they're built for different contexts.

Claude Cowork runs inside Claude Desktop. It's designed for general knowledge work: organizing files, creating Excel spreadsheets, writing documents, running scheduled tasks. No terminal, no code. You describe an outcome, step away, and come back to finished work.

Claude Code runs in the terminal. It has full access to your file system, can run commands, execute scripts, and operate deeply inside a structured folder system like AI-SHIPR. It's designed for technical and systems-level work.

AI-SHIPR is built for Claude Code because it relies on reading CLAUDE.md files, running slash commands and skills, and working inside a structured folder hierarchy — none of which Cowork supports today.

Think of it this way: Cowork is great for one-off tasks you'd describe in plain language. Claude Code is the right tool when you want a persistent, structured system that compounds over time.

Agents are persistent AI personas with broad judgment. You describe a situation and they think through it. They read your strategy files before responding, so their output is specific to your product context. Examples: Problem-Framer Decision-Architect Stakeholder-Translator

Skills are single-task tools you invoke on demand. You give them an input and they produce one specific structured output. They do one thing well and stop. Examples: Assumption-Extractor Hypothesis-Builder Tradeoff-Mapper

Slash commands are triggers that run a skill or full workflow. Type the command and Claude executes the whole sequence — you don't need to know which skills are involved. Examples: /today /sprint /weekly

Quick rule: if you want to think through a complex situation → agent. If you want a specific structured output → skill. If you want to run a repeatable routine → slash command.

Skills in AI-SHIPR are invoked explicitly by slash command — they don't run automatically or compete with each other. So "priority" is really about two things: naming and scope.

1. Avoid naming conflicts. Each skill maps to a unique command name. Before adding a new skill, check A-AI/AI-Skills/ and the skills table in CLAUDE.md to confirm no existing skill uses the same name or a very similar one. A conflict won't cause a crash — Claude will just get confused about which definition to follow.

2. Define a tight scope. Each skill file should describe exactly what it does and what it does not do. If your new skill overlaps with an existing one (e.g. both structure a document), add an explicit line like: "This skill does not replace [Skill-Name] — use that for X." This tells Claude when to use which tool.

3. Don't redefine system behavior. Skills should not override voice, tone, or format rules set in CLAUDE.md or Settings.md. Those files have the highest priority in the context hierarchy. A skill that says "always respond in bullet points" will fight the system-level settings and produce inconsistent results.

4. Register it in CLAUDE.md. Add the new skill to the skills table in CLAUDE.md under the right category. This is how Claude knows the skill exists and when to suggest it. An unregistered skill still works if you call it directly — but Claude won't surface it proactively.

The safest test: after adding the skill, run it once, then run an adjacent skill you're worried it might affect. If both produce clean output, the scope is well-defined.

Don't try to evaluate them before you've used them. The right approach is to use the defaults for 2–4 weeks first. Run the workflows, use the agents on real decisions, generate real artifacts. Generic assessment is useless — you need signal from your actual work.

After that, notice the friction. If you're adding the same context every time you invoke an agent, the agent file is missing it — add it. If an agent's output structure doesn't match how you think, edit the output section. If a skill asks for inputs you never have, rewrite the input expectations.

Changing them is just editing a markdown file. Open the agent or skill in A-AI/AI-Agents/ or A-AI/AI-Skills/, make your edit, and the next invocation picks up the change immediately. You can also ask Claude to rewrite a section: "Rewrite the Behavior Rules section of Problem-Framer to be less aggressive about blocking vague statements."

The defaults are a starting point, not a standard. The agents that work best for you will be ones you've shaped to your context over time.

The process is straightforward — AI-SHIPR is just a folder structure, so adding your own pieces takes two steps:

1. Place the file in the right folder. Agent files go in A-AI/AI-Agents/. Skill files go in A-AI/AI-Skills/. The file format is markdown — your existing agents and skills will work as-is, or you can reformat them to match the AI-SHIPR structure for tighter integration.

2. Register it in CLAUDE.md. Open CLAUDE.md at the root of your AI-SHIPR folder and add the agent or skill to the relevant table (Agents or Skills section). This tells Claude it exists, what it does, and when to suggest it. Without this step the file still works if you call it directly — Claude just won't surface it proactively.

If your agent or skill references specific inputs or file paths that don't match the AI-SHIPR folder structure, update those references so it reads from the right places (e.g. S-Strategy/ instead of wherever you had them before).

Don't import everything at once. Add the one agent or skill that closes the biggest gap in your current workflow, test it for a week, then decide what else to bring in.

An agent is who is thinking. A skill is how the thinking gets done. The relationship only goes one way: agents use skills — skills never call agents.

Concretely: when the Lean-Product-Canvas agent reaches Box 6 (Hypotheses), it doesn't write the hypothesis itself. It invokes Assumption-Extractor first to surface the hidden assumptions, then invokes Hypothesis-Builder to convert each assumption into a falsifiable hypothesis. The agent orchestrates the sequence; the skills do the precise work.

Most agents in AI-SHIPR operate without calling any skills — they work through dialogue and judgment: Problem-Framer, Decision-Architect, Stakeholder-Translator. Only the two orchestrator agents — Product-Strategist and Lean-Product-Canvas — explicitly invoke skills as part of their sequence.

Skills are stateless: they receive input, produce output, and stop. They have no memory of previous invocations and no awareness of the agent calling them. This makes them reusable — the same OKR-Partner skill is called by both Product-Strategist and Lean-Product-Canvas at different points in the flow.

If you're building a new agent that needs to do multiple structured steps, consider whether each step should be its own skill. That way the steps stay reusable and testable independently.

Frequently Asked Questions