Ninjo

View saved version →

---
name: build-agent
description: Create a new Ninjo sales agent from a brief, or iterate an existing one from real conversations. Use when the operator says "quiero crear un agente", "armá el agente para mi lanzamiento", "cambiá cómo responde cuando preguntan el precio", "el agente suena muy vendedor", "agregá esta objeción", or asks to rewrite, tune or deploy a prompt. Builds the full SDK (system prompt plus the 8 v5Config fields) through the Ninjo MCP tools and deploys with deploy_agent_sdk.
---

# Build or iterate a Ninjo agent

A Ninjo agent is a **system**: a system prompt, eight v5Config fields, the triggers that route
messages to it, and the automation wired around it. This skill covers the prompt and the
eight fields. Automation is the `wire-automation` skill; run it after every new agent.
Reply in the operator's language. Prompts are written in the creator's own dialect.

## 0. Load the playbook first

Call `get_playbook_index`, then `get_playbook_doc` on:

- `templates/principles`: the single prompt architecture ("fewer rules, more examples").
- The motion flavor that matches how the creator closes:
  `templates/principles-express` (low ticket, drop the resource fast),
  `templates/principles-consultative` (mid ticket, discovery then link in DM),
  `templates/principles-deep-nurture` (premium, empathy plus video, DM closes),
  `templates/principles-book-the-call` (high ticket, the call closes, DM only qualifies).
- `knowledge/best-practices-top10`: the quality rubric and the only home of the numbers
  (example cap, principle count, hard-rule count).
- One worked sample in a similar vertical (`sample-wellness-bookcall`,
  `sample-petcare-consultative`, `sample-finance-bookcall`, `sample-prodev-consultative`).
  Pass `section` to read one file, for example `examples`.

## 1. Start from what is live

- **Iterating:** `get_agent_config(agent_id)` is the source of truth. Never edit from memory
  or from a pasted copy; the operator may have changed the agent in Ninjo since.
- **Creating:** `get_me` gives the `influencer_id`. If `scope` is `multi-influencer`, pass
  `influencer_id` on every call. `get_self_serve_data` may already hold the creator's bio,
  program and Instagram posts; use them.
- Gather the brief: identity, voice (5 or 6 real messages the creator wrote), conversation
  flow, resources with real URLs, program and pricing, happy-path examples, edge cases. If
  the operator shared a style guide or example conversations, **that is the source of truth
  for tone**; examples must be adaptations of it, not inventions.

## 2. Author the SDK

- `system`: identity and mission, voice, one simple flow, at most 7 principles, tools.
  No hard-rule lists; style lives in examples. Principles beat rules.
- `examples`: the highest-leverage field. Real or adapted conversations that show the flow
  end to end, including the moment the link or resource goes out. Pure dialogue, no
  instructions inside.
- `knowledge_base`, `objections`, `personal_story`: prose. `keywords`, `program`,
  `resources`, `case_studies`: JSON values (arrays or objects), never JSON-encoded strings.
- **All eight fields on a first deploy.** `system`, `examples` and `knowledge_base` must carry
  real content; at least one of `keywords` or `program` must be populated. A keywords-only
  config runs but is not a real agent, and nothing stops it from going live.
- Cross-check before deploying: every URL in the prompt exists in `resources`; examples obey
  the system prompt; no two files disagree on a price, a date or a link (BP-5); no action the
  agent can take is unguarded (BP-7).
- **Do not solve platform problems with prompt rules.** The agent does not know what a
  "bubble" is; message splitting, delays, stopping after a purchase and follow-ups are
  platform settings and automation, not prose.
- Custom properties are set by the platform's evaluator reading the transcript afterwards.
  The agent cannot set them; never write "el agente marca la propiedad

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: connect-channels
description: Connect or repair the channels and integrations a Ninjo agent answers through, including Instagram, Facebook, WhatsApp, ManyChat, GoHighLevel, HubSpot, Kommo and Calendly. Use when the operator asks "cómo conecto mi Instagram", "cómo conecto el WhatsApp del negocio", "conectá GoHighLevel", "el agente está activo pero no le llegan los DMs", "ManyChat recibe pero el agente no contesta", "el primer mensaje sale y el segundo falla", or asks which agent owns which inbox.
---

# Connect channels and integrations

Everything here runs through connect links and status reads. **Never ask the operator for a
password, an API key or a token**; none of these flows needs a credential typed to you. The one
key that exists (ManyChat) is typed by the operator into Ninjo, never through the model. Reply
in the operator's language.

## 0. Read what the agent answers today

`list_agent_channels(agent_id)` is the one unified view. Each channel has a `source`:

- `direct`: a Meta account (Instagram, WhatsApp, Messenger) connected straight in Ninjo. The
  agent owns that inbox.
- `crm`: a relay. A CRM (GoHighLevel, Kommo, HubSpot, Airtable) or a ManyChat connection
  forwards messages in and the agent answers only those. A `crm` row with `channel_type:
  UNKNOWN` is ManyChat.

**A relay channel with no assigned agent never replies.** "ManyChat (or GHL) receives the
messages but the agent stays silent" is almost always `agent_id` null on that connection:
`list_crm_connections`, then `set_agent_crm_channel`.

`list_connected_accounts` shows the Meta accounts; `diagnose_agent` flags an active agent with
no linked account, which means DMs never reach it.

## 1. The link flow (Meta, CRM, booking)

1. `create_connect_link(provider)` returns a single-use URL that lasts a few minutes.
   Providers: Meta accounts, `gohighlevel_crm`, `hubspot_crm`, `kommo_crm`,
   `gohighlevel_booking`, `calendly`.
2. Hand the URL to the operator. Do not open it yourself. If it expires, mint another.
3. The operator authorizes at the provider.
4. `get_connection_status`. **Read `setup_complete`, not `connected`**, and act on
   `pending_step`: `authorize_with_connect_link` (send another link), `reconnect` (link with
   `reconnect: true`), `select_calendars` (`list_booking_calendars` then
   `set_booking_calendars`), `enable_integration_in_studio`, `paste_api_key_in_studio`
   (ManyChat only), or `null` when genuinely done.

GoHighLevel appears twice and they are different things: the CRM sync (contacts and
opportunities) and the booking integration (tracking scheduled calls). Ask which one before
sending a link. Booking is fail-closed: until calendars are selected, no booking is tracked.

## 2. Link the agent to the inbox

A connected account is not enough. The agent must be linked to it (`set_connected_account`)
and active (`set_agent_status`). Trigger mode decides which DMs reach it: all DMs, or only
those matching a keyword or comment trigger (`list_triggers`). "Active but silent on every
conversation" is the `knowledge/runbooks/agent-not-answering` runbook, hypotheses 1 to 4.

## 3. Instagram with two apps on the same inbox

Meta lets several apps subscribe to one Instagram inbox but only **one app owns each DM
thread**. If ManyChat (or another tool) already answers DMs on that account, Ninjo's replies
are rejected: `get_conversation_decisions` shows `send_failed` with `THREAD_OWNER_MISMATCH`,
and the message shows `status: FAILED` in the transcript. Typical shape: the private reply to a
comment goes out, then every follow-on message fails. Fixes, in order of preference:

1. Make Ninjo the only app answering DMs on that account (remove the other app's DM
   subscription in Meta, or turn off its DM automations).
2. Or relay through the CRM/ManyChat instead of connecting Instagram directly: create the
   channel, confirm the connection has an `agent_id` via `list_crm_connections`, then unlink
   the direct Instagram account.

Other `se

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: debug-agent
description: Diagnose a live Ninjo agent that is misbehaving. Use when the operator reports a symptom rather than asking a question, for example "el agente no responde", "dejó de contestar", "mirá esta conversación, algo anda mal", "le sigue escribiendo a alguien que ya compró", "el follow up no se envía", "la keyword no dispara", "no me llegan las notificaciones", "tengo cero agendas", "lo deployé y sigue igual". Runs the runbook for that symptom over the Ninjo MCP tools and stops at the first confirmed cause.
---

# Debug a live Ninjo agent

An operator arrives with a symptom, not a diagnosis. Your job is to find the one mechanism
that explains it, using the platform's own decision record, and to fix it or hand back one
exact next step. Reply in the operator's language.

## 0. Collect the ids, then read the runbook

- You need the `agent_id` and, if the complaint is about one lead, the `conversation_id`.
  `list_agents` resolves a name to an id. If you cannot get an id, say which one you need and
  why; never diagnose from a description alone.
- Call `search_playbook` with the complaint **in the operator's own words** (Spanish is fine).
  The top hit is a runbook. Fetch it with `get_playbook_doc` and work its hypotheses **in
  order**, cheapest first. Stop at the first hit. Do not collect every hypothesis.
- Runbook ids, by symptom:

| Operator says | `get_playbook_doc` id |
|---|---|
| no responde / dejó de contestar | `knowledge/runbooks/agent-not-answering` |
| le sigue escribiendo a alguien que ya compró | `knowledge/runbooks/agent-wont-stop` |
| mirá esta conversación, algo anda mal | `knowledge/runbooks/conversation-went-wrong` |
| el follow up no se envía / se manda a todos | `knowledge/runbooks/followup-never-fires` |
| la keyword no dispara | `knowledge/runbooks/keyword-not-triggering` |
| no me llegan las notificaciones | `knowledge/runbooks/notification-never-arrives` |
| no se envía el pdf / el link no llega | `knowledge/runbooks/resource-not-delivered` |
| pausé y el agente igual respondió | `knowledge/runbooks/handoff-doesnt-stick` |
| repite el saludo / manda el mensaje dos veces | `knowledge/runbooks/repeated-or-wrong-opener` |
| manda muchos mensajes / me llegó cortado | `knowledge/runbooks/too-many-or-truncated-messages` |
| cero agendas / bajaron las reservas | `knowledge/runbooks/zero-bookings` |
| qué le falta para salir en vivo / deployé y sigue igual | `knowledge/runbooks/not-live-yet` |

## 1. The three calls that settle most cases

1. **`diagnose_agent` (mode `quick`)** first. It checks the wiring in one call: linked
   account, trigger mode, contact limits, properties, workflows. Most "the agent is behaving
   wrong" reports are configuration or automation, not the prompt.
2. **`get_conversation_decisions(conversation_id)`** before forming any opinion about a silent
   or wrong conversation. The platform records *why* nothing happened:
   - `no_response` with detail `NO_RESPONSE` alone: the agent chose silence on a real message.
     Only now is the prompt a suspect.
   - `NO_RESPONSE: last_message_not_user` or a free-text reason such as `awaiting booking`:
     benign, working as designed.
   - `NO_RESPONSE - cot_filter_blocked`: the reasoning-leak filter caught a message; read
     `knowledge/reasoning-leak`, not the silence rules.
   - `contact_limit`: a limit muted this contact. That mute is **permanent** for the contact.
   - `send_failed`: the reply was sent and the channel rejected it. `THREAD_OWNER_MISMATCH`
     means another app (usually ManyChat) owns the Instagram thread; read
     `knowledge/messaging-channels`, section on thread ownership. `MESSAGE_WINDOW_EXPIRED` is
     Meta's 24h window. `INVALID_TOKEN` means reconnect the account with `create_connect_link`.
   - Empty result: also an answer. Nothing suppressed the turn, so the cause is upstream
     (routing, relay, trigger mode).
3. **`get_conversations` / `search_conversations`** to read the transcript. Ever

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: report
description: Report on how a Ninjo agent is performing. Use when the operator asks "cómo viene el agente esta semana", "cuántos agendaron", "quiénes reservaron", "armame un dashboard del funnel", "qué contenido trae mejores leads", "qué leads están calientes", or wants a weekly summary, a funnel, a booking list or a comparison between agents. Read-only; never changes the agent.
---

# Report on an agent

Two aggregate tools cover most reports; drop to conversation-level search only for a cut
the aggregates do not have. Reply in the operator's language. Numbers go in a table.

## 1. Pull the data

- `get_agent_metrics(days, min_leads)`: per agent, `leads`, `avg_funnel`, `bookings_sent`,
  `booking_send_rate`, `calls_booked`, `call_book_rate_total`, `pct_funnel_ge_4`,
  `risk_score_0_100`. KPI cards and the risk ranking across agents.
- `get_agent_insights(days)`: `quick_stats` (last 24h), `funnel_transitions` (rate per stage),
  `content_sources` (conversations, qualified leads and bookings per post or ad),
  `hot_leads` (awaiting follow-up), `stalled_by_objection`.
- `list_schedules`: who booked, filterable by status, source, agent and date. Use it for
  "quiénes agendaron"; do not reconstruct bookings from transcripts.
- `search_conversations` with structured filters (`min_funnel`, `has_booking_link`,
  `call_booked`, dates, lead score, nurturing or happy-path score) for a custom stage or a
  keyword table. It has **no message-text search**.
- `search_contacts` for segments by custom property (`custom_properties:
  [{codename, equals_boolean: true}]`), for example everyone who discussed pricing.

Gotchas: `get_agent_metrics` returns `agents: []` when there was no activity in the window,
so widen `days` before concluding zero. In conversation rows `meta.booking_link_sent` and
`meta.call_booked` arrive as strings (`"true"`); `funnel` is a 0 to 5 scale, pick an explicit
threshold. Ad attribution covers Instagram and Facebook referrals only, not click-to-WhatsApp.

## 2. The standard funnel

```
conversations  ->  qualified  ->  link sent  ->  booked or bought
```

| Stage | Source |
|---|---|
| conversations | `get_agent_metrics.leads` or `content_sources[].total_conversations` |
| qualified | `quick_stats.qualified_leads_24h`, or `search_conversations(min_funnel: 2)` |
| link sent | `bookings_sent` / `booking_send_rate` |
| booked or bought | `calls_booked` / `call_book_rate_total`, or `list_schedules` |

## 3. Shape the answer

- A quick question gets a markdown table and two lines of reading: what moved, and the one
  thing worth doing about it.
- "Armame un dashboard" gets a single self-contained HTML artifact: KPI cards on top, funnel
  bars in the middle, a table per content source below, data embedded inline, no external
  fetches. Recipe in `get_playbook_doc` on `knowledge/dashboards`.
- Every finding names the next action and the tool that does it (a stalled objection points
  at `build-agent`; an agent with no bookings and links going out points at the
  `knowledge/runbooks/zero-bookings` runbook; hot leads point at a follow-up in
  `wire-automation`).
- Compare like with like: same window, same `min_leads`, and say when a rate sits on fewer
  than 20 leads.

View saved version →

---
name: wire-automation
description: Wire or repair the automation around a Ninjo agent, which is where most agents fall short. Use when the operator wants the agent to stop after a purchase or booking, to follow up leads that went quiet, to get notified when someone converts, to push a lead into a CRM or webhook, or asks "cómo hago que deje de escribirle a los que ya compraron", "quiero que haga seguimiento a los 2 días", "avisame por WhatsApp cuando alguien agende", "la propiedad se setea pero no pasa nada". Also the mandatory activation kit for a newly created agent.
---

# Wire the automation around an agent

The prompt controls only what the agent **says**. Stopping after a conversion, following up a
stalled lead, alerting the operator, updating a CRM: all of that is a **custom property** that
an evaluator fills from the transcript, consumed by a **contact limit**, a **workflow** or a
**notification**. A property does nothing until something consumes it. Reply in the
operator's language.

## 0. Read the wiring before touching it

- `diagnose_agent` (mode `quick`) lists what exists and what is missing, with the fix tool
  for each finding. Run it first and again at the end.
- `list_custom_properties`, `list_contact_limits`, `list_workflows`,
  `list_custom_notifications`, `list_property_actions` show the current state. Read them
  before writing; several writes are **replace, not merge**, and a partial update can null the
  conditions and leave a rule firing on everyone or on no one.
- Docs: `get_playbook_doc` on `knowledge/custom-properties`, `knowledge/workflows`,
  `knowledge/follow-up-architecture`, `knowledge/property-actions`.

## 1. New agent: the activation kit in one call

`scaffold_agent_activation(agent_id, ...)` creates the terminal conversion property, the
contact limit gated on it, the follow-up for non-converters and the operator notification.
It is idempotent. The one thing it cannot guess is the client's conversion fact (booked a
call, paid, left a phone number): ask, then pass it explicitly. Loop: `diagnose_agent`,
scaffold, `diagnose_agent` again until `complete: true`.

## 2. The rules every property must satisfy

- **Boolean or number, never string**, for anything that gates automation. Text values
  compare unreliably in conditions.
- **`check_until_match` true with the terminal value** on any property that gates a shutdown,
  a follow-up lock or a conversion notification. Otherwise an early `false` freezes forever
  and the later signal never flips it. `upsert_custom_property` defaults a boolean to gated;
  pass `checkUntilMatch: false` explicitly only for a descriptive boolean, on every write.
- **Never ask a property for a fact the platform already stores** (booking link sent, call
  booked through an integration, phone number). Use the native field.
- A terminal conversion such as "call booked" should come from the booking integration, not
  from the transcript, whenever the integration is connected.
- Read the `warning` field in the `upsert_custom_property` response. It says when the tool
  healed an ungated boolean or when the property still cannot drive automation as written.

## 3. Contact limits: the stop switch

- `upsert_contact_limit` gated on the terminal property. When it fires it sets the agent
  inactive **for that contact, permanently**; nothing brings it back. Correct after a purchase
  or booking, wrong after "not right now".
- "The agent never stops messaging converted leads" is usually a frozen property (rule above)
  or a limit gated on a string. Compare the property's values against the transcripts.

## 4. Follow-ups: workflows of type FOLLOW_UP

- `upsert_workflow` with the stage delay and the property conditions that select the lead.
  Gate on data: a lead who booked or bought must be excluded by the terminal property.
- **Meta's 24h window.** On Instagram and Messenger a follow-up can only go out inside 24h
  of the lead's last message; a lead who only commented cannot be f

Preview of the first 4,000 characters. Read full instructions →