Cookiy

Cookiy gives your AI agent user-research capabilities: interview guides, AI-moderated interviews with real or simulated participants, and insight reports — driven through terminal commands against the Cookiy hosted service.

Progressive disclosure

Stay in this file first. Do not load all
```
references/*.md
```
or the full
```
cli/commands.md
```
unless the user asks for a deep read.
Credentials + health: follow
```
cli/commands.md
```
(environment variables, default credential paths). Then run
```
cookiy doctor
```
via
```
scripts/cookiy.sh
```
or a globally linked
```
cookiy
```
binary from the
```
cookiy-mcp
```
package. Do not paste raw tokens or OAuth authorization codes into chat — only into the terminal that is running
```
cookiy login
```
if that fallback is needed (see Login runbook below).
Route by intent (one reference): open exactly one workflow file from the Intent Router below. For natural-language progress questions, start with
```
cookiy study progress
```
or
```
cookiy study show
```
.
Cross-cutting rules: billing, HTTP 402, identifiers, pacing, and server hints →
```
references/tool-contract.md
```
.
Quantitative studies:
```
cookiy help quantitative
```
and the quantitative section in this file, then
```
tool-contract.md
```
.
Shell execution: agents should invoke
```
skills/cookiy/scripts/cookiy.sh
```
(or
```
./cookiy
```
at the repo root) with
```
run_terminal_cmd
```
when executing Cookiy.
Pure methodology (no Cookiy API): use
```
../pm-research/SKILL.md
```
only when the user wants general research methods, not platform operations.
Packaged layouts: the same skill tree ships under
```
packages/cookiy-mcp/skill-assets/
```
; keep paths in sync when editing.

Part 1 — Setup and health

Before business operations

Always confirm Cookiy is reachable with valid credentials:

Ensure credentials exist (see
```
cli/commands.md
```
).
Run
```
cookiy doctor
```
(introduce / connectivity). If it fails, run cookiy login
(browser OAuth to the default credentials path) or repair via
```
npx cookiy-mcp --client …
```
when the user also needs IDE/skill install.
If the user’s goal is exclusively setup or repair, stop after a short, plain-language success message — do not jump into research intake.

Login runbook (agents — avoid an extra chat turn)

cookiy login

blocks until OAuth finishes (local browser callback to

127.0.0.1

, or paste-in-terminal fallback). The process exits only after tokens are written; there is no separate “tell the agent authorization completed” step if the command is allowed to run to completion.

When the user needs login and a follow-up (e.g.

doctor

, billing, or a study command), prefer one foreground terminal invocation that chains after success, for example:

bash

cookiy login && cookiy doctor

(or

./cookiy.sh login && ./cookiy.sh doctor

from this repo).

Rules for agent

run_terminal_cmd

(or equivalent):

Do not run
```
cookiy login
```
in the background — the tool must wait for exit.
Ask for a long enough command timeout when the host allows it (OAuth often needs several minutes while the user uses the browser). Short defaults can kill the process mid-flow; then the user must send another message.
After
```
login
```
exits 0, continue with the next Cookiy command in the same agent turn when possible (e.g. the chained
```
&&
```
above already did
```
doctor
```
).
Remind the user once: complete approval in the browser; normally no code paste is needed. If a terminal still asks for paste, use that terminal — not chat.

When

cookiy doctor

is only used as a smoke test, summarize the outcome in one sentence for the user. Do not dump raw JSON unless debugging.

Capability overview (when the user asks what Cookiy does)

Present Cookiy’s six modules in plain language (qualitative and quantitative are parallel — same agent, complementary methods):

Study creation — describe a goal; get an AI-generated discussion guide.
AI interview — simulate interviews with AI personas.
Discussion guide — review and edit the script before going live.
Recruitment — recruit participants for AI-moderated interviews.
Report and insights — generate reports and shareable links.
Quantitative survey — structured questionnaires and analysis when enabled for the workspace (see
```
cookiy help quantitative
```
).

Avoid listing low-level server identifiers in user-facing prose.

Part 2 — Workflow orchestration

Intent Router

User wants to…	Workflow	Reference file
Create a study or research project	Study creation	`references/study-creation.md`
Simulated or AI-to-AI interviews	AI interview	`references/ai-interview.md`
View or edit the discussion guide	Guide editing	`references/guide-editing.md`
Recruit real participants	Recruitment	`references/recruitment.md`
Report status or share link	Report and insights	`references/report-insights.md`
Quantitative questionnaires	Quantitative survey	`cookiy help quantitative` + `references/tool-contract.md`
Natural-language study progress	Prefer `cookiy study progress` / `cookiy study show`	`references/tool-contract.md`
Add cash credit (USD cents)	`cookiy billing checkout`	`references/tool-contract.md`
Check balance	`cookiy billing balance`	`references/tool-contract.md`
List studies	`cookiy study list`	`cli/commands.md`
Platform overview / connectivity blurb	`cookiy doctor`	—
Workflow help by topic	`cookiy help <topic>`	`cli/commands.md`

Multipart requests

When the user’s goal spans workflows (for example “create a study and run interviews”), execute them in a sensible dependency order: study creation → guide readiness → interviews or recruitment → reporting.

Universal rules

See

references/tool-contract.md

for the full specification. In short:

Responses: prefer
```
structuredContent
```
; fall back to
```
content[0].text
```
only if needed.

Hints: honor

next_recommended_tools

status_message

, and

presentation_hint

Progress questions: prefer
```
cookiy study progress
```
before drilling into atomic operations.
Quantitative default chain unless the server directs otherwise:
```
cookiy quant list
```
or
```
cookiy quant create
```
→
```
cookiy quant detail
```
→
```
cookiy quant patch
```
(if editing) →
```
cookiy quant report
```
after responses exist; use
```
cookiy quant results
```
only when raw exports are explicitly required.

Recruitment evidence order:

cookiy interview list

→

cookiy recruit status

→ latest

cookiy recruit start

response →

cookiy study get

state.

Identifiers: never truncate or rewrite

study_id

job_id

interview_id

base_revision

confirmation_token

, etc.

Payments (HTTP 402): follow

structuredContent.data.payment_summary

and

checkout_url

when present; otherwise parse

error.details

Checkout outside a 402 flow:

cookiy billing checkout

, then

cookiy billing balance

URLs: only use URLs returned by Cookiy; never guess undocumented REST paths.
Constraints: interview duration cap (15 minutes), persona text limits, attachment limits — see workflow docs.

Canonical reference

If the live hosted service disagrees with this skill, the service wins. Use the developer portal / public specification referenced from

tool-contract.md

when you need field-level truth.

CLI and docs index

Resource	Path
Command tree, flags, environment	`cli/commands.md`
Wrapper (repo)	`scripts/cookiy.sh`
Cross-cutting API semantics	`references/tool-contract.md`

cookiy

NPX Install

Tags

SKILL.md Content