Update to Cheerful

{
  "description": "Turn a creator brief into a Cheerful search on Instagram, TikTok or YouTube, report the creators actually found, shortlist the best fits and save them to a list when asked. Searches use Cheerful credits. Use when the user says \"find creators\", \"find influencers\", \"search for TikTok/Instagram/YouTube creators\", \"creators like @handle\", \"build a shortlist\", \"who should I reach out to for this brief\", or \"find 20 US skincare creators with 10k-100k followers\". Not for general influencer-marketing advice, captions or scripts where the user has not asked to find creators.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 550
    }
  ],
  "name": "cheerful-find-creators",
  "skill_md_contents": "---\nname: cheerful-find-creators\ndescription: \"Turn a creator brief into a Cheerful search on Instagram, TikTok or YouTube, report the creators actually found, shortlist the best fits and save them to a list when asked. Searches use Cheerful credits. Use when the user says \\\"find creators\\\", \\\"find influencers\\\", \\\"search for TikTok/Instagram/YouTube creators\\\", \\\"creators like @handle\\\", \\\"build a shortlist\\\", \\\"who should I reach out to for this brief\\\", or \\\"find 20 US skincare creators with 10k-100k followers\\\". Not for general influencer-marketing advice, captions or scripts where the user has not asked to find creators.\"\n---\n\n# Find creators\n\nTurn a brief into one Cheerful creator search, show what came back, and help the user pick a\nshortlist. Every search uses credits from the user's Cheerful plan, so run one search per request\nand don't re-run it to \"get more\" unless the user asks.\n\n## When not to search\n\nA question about influencer marketing in general (\"what is a good engagement rate?\", \"write a\ncaption\") is not a search request. Answer it directly and spend no credits. Search only when the\nuser wants actual creators.\n\n## Step 0: Check the connection\n\nIf a Cheerful tool is unavailable, or a call answers \"Tool not found\" or asks to reconnect, stop\nand tell the user: \"Connect Cheerful from the plugin page, then ask me again.\" Don't retry.\n\n## Read this first: what the data can and can't tell you\n\n- **Count only the rows you received.** `creator_search` returns a `total` that is the provider's\n  pool before filtering, often tens of thousands. Never report it. \"Found 8\" means 8 rows came back.\n- **Most creators have no public email.** That is normal, not a failed search, and not a reason to\n  search again. Emails are found later, when creators are added to a campaign in Cheerful.\n- **Don't drop what the brief didn't exclude.** No invented follower or engagement floors. A\n  1k-follower creator who fits the niche is a valid result.\n- **Every note is evidence or an honest gap.** A row's note says WHY it fits, from what came back:\n  the account's name or category, or, for the shortlist, a bio phrase or recent post topic from\n  `creator_profile` (\"bio: 'Giants fan since '86'\"). Never write \"search match\" or \"related\n  account\": if nothing shows the fit, write \"fit not confirmed\" and keep it out of the shortlist.\n- **A place in the brief is checked per row.** If the brief names a city or country, say per row\n  whether the data confirms it (\"NYC in bio\", \"US\", \"location not shown\"). One sentence that\n  says \"location isn't confirmed\" for the whole table hides which rows are right.\n- **Fan pages, brand pages and media accounts are not creators by default.** If the brief asks\n  for fan accounts, they are the target; otherwise label a page that only reposts, a team or a\n  publisher as \"media/fan page\" so the user can decide.\n- **Low engagement is a flag, not a filter.** Under about 0.5% on 50k+ followers often means a\n  bought audience. Say so next to that creator; keep them in the list.\n- **Some searches are slow on purpose.** A keyword search takes a few seconds, a smart search\n  about a minute, and a YouTube search runs in the background for 10-45 minutes. Tell the user it is working; don't\n  start a second search over the top of one that is still running.\n- **Out of credits.** If the search reports the user is out of credits, call `billing_usage` and\n  say how many credits are left and when they renew. Nothing more.\n\n## Workflow\n\n1. **Read the brief.** Pull out platform (default Instagram — say so), who the creator is (describe\n   the person: \"vegan meal prep mom\", not the product), country, follower range, engagement floor\n   if given, and how many creators (default 10). Ask one question only if the brief has no niche\n   at all.\n2. **Pick the search.** Call `creator_search`:\n   - `action=\"keyword\"` when the brief has hard filters (country, follower range, engagement), or\n     names a country the smart search can't bind (the tool description lists the ones it can).\n     Put countries in `location` as full names: \"United States\", not \"US\".\n   - `action=\"smart\"` for an open, descriptive brief with no hard filters.\n   - `action=\"similar\"` for \"creators like @handle\", with the handle as `query`.\n   - Leave apostrophes out of `query` (\"womens health\", not \"women's health\").\n   - Set `limit` to the number asked for (up to 50).\n3. **YouTube only.** `creator_search` with `platform=\"youtube\"` starts a background search and\n   returns a run id, not creators. It vets each channel's videos and usually takes 10-45 minutes.\n   Tell the user it is running in the background and that results are saved to a new list\n   automatically (give them the list link). Don't poll in a loop: call `creator_search_status`\n   with that `run_id` when the user asks how it is going. If it failed to start, report why and\n   stop.\n4. **Read the result.** Count the creators returned. If fewer than asked, relax one thing\n   (follower range first, then engagement, then country), search once more, and label the extra\n   creators \"relaxed: <what changed>\". Still short? Stop and say how many you have and what you\n   would relax next.\n5. **Shortlist.** Pick the 3 best fits for the brief and call `creator_profile` for each, with the\n   same `platform` the search used. Each can take up to a minute the first time; say so. If a\n   profile comes back not enriched yet, say \"not enriched yet\" rather than \"no followers\".\n   Only promise one minute if you actually call it; skip this step when the user asked for a\n   quick list.\n6. **Save — only when asked.** If the user asks to save or keep creators, call `list_read` to see\n   their lists, then `save_creators_to_list` with the creator rows, `platform` set to the platform\n   the search used (always pass it; there is no default), and either `list_id` (one of their own\n   lists) or `new_list_name`. One call per platform. Report how many were saved, how\n   many were already on the list, any that couldn't be saved (by handle), and the link to the\n   list. Only the user's own lists can take new creators; if a list is refused, offer a new one.\n   Never save without being asked.\n7. **Next step.** Offer what fits: save them to a list, vet one in depth, or (when\n   `create_campaign_draft` is listed) put them in a campaign. \"Add them to the campaign\" means\n   `campaign_add_creators`, through the launch-campaign workflow.\n\n## Output layout\n\nIn ChatGPT the search results appear as a creator card automatically. After the card, write at\nmost 2 sentences: the count you got, anything relaxed or flagged, and the next step. Don't list the\ncreators again in prose.\n\nWhere no card is shown (for example in Codex), use this layout:\n\n```\n**Found 8 US vegan cooking creators on Instagram** (asked for 10; follower range widened to 5k-100k for 2 of them)\n\n| Creator | Followers | Engagement | Country | Note |\n|---|---|---|---|---|\n| @daguiltyvegan · Chef Derek | 24.3k | 0.6% | not shown | bio: \"plant-based chef, NYC\" |\n| @healthmylifestyle · Rachel | 40.0k | 2.1% | US | weekly vegan meal-prep reels · relaxed: followers |\n| @plantpowerpage | 31.0k | 0.3% | not shown | fit not confirmed · low engagement |\n\n**Shortlist:** @healthmylifestyle — weekly recipes, steady engagement; ...\nThis search used credits from your plan. Want me to save these to a list or add them to a campaign?\n```\n\n## Rules\n\n- Plain language: no ids, field names, status codes or \"tool\" in the reply.\n- Never email or message a creator yourself. Outreach is a campaign: with `create_campaign_draft` listed,\n  offer to set one up (the user sends it from the launch card); otherwise it is set up in\n  Cheerful at https://app.cheerful.ai.\n- Credits, never dollars. Don't promote plans or purchases.\n- Never show a creator's email address in the shortlist; say \"has a public email\" if one exists.\n"
}