The Yirlo skill for AI agents

What a skill is

A skill is a small folder with one markdown file in it. The file starts with a name and a short description, followed by instructions written for the agent. The agent reads the name and description at startup and loads the full instructions only when your request matches, so a skill costs almost nothing until it is needed.

Think of it as a runbook the agent carries with it. A tool list tells an agent what it can do. A skill tells it how a person who knows the product would go about the job. The Yirlo skill uses the Claude skills format, which Claude Code reads directly from a skills folder.

What the Yirlo skill teaches an agent

The skill covers three things. First, how to connect: it points the agent at the Yirlo MCP server first and falls back to the public API when MCP is unavailable. Second, how to work through an account in a sensible order. Third, a reference for all 33 tools, so the agent picks the right one on the first try.

The working order is the part that saves you from sloppy answers. The agent looks at the account and balance, then the projects, then the campaigns inside a project, then the inbox and hot leads. Asked how outreach is going, it starts with analytics and the account state instead of guessing from a single campaign.

The skill also sets a rule for anything with consequences. Before the agent sends an email, starts a campaign, changes a budget or invites a teammate, it tells you what it is about to do and waits for your yes.

Where to put the skill file

For Claude Code, create a folder called yirlo inside your personal skills directory and save the file there as ~/.claude/skills/yirlo/SKILL.md. That makes it available in every session on your machine. To keep it with a single codebase or workspace, save it as .claude/skills/yirlo/SKILL.md inside the project instead, and teammates who open the project get it too.

From a terminal:

mkdir -p ~/.claude/skills/yirlo
curl -o ~/.claude/skills/yirlo/SKILL.md https://yirlo.com/skills/yirlo/SKILL.md

Other agents that read the Claude skills format work the same way: put the folder where that agent looks for skills.

Once the file is in place, there is nothing to run. Ask about your outreach and the agent picks up the skill from its description.

Create the API key

A key comes first, since the skill has no access to your account without one. The complete key appears at the moment of creation and begins with yk_live_, so copy it somewhere safe right away, such as a shell environment variable or the secret store your agent uses.

Your key works with both SDKs, the MCP server and the plain API alike, so going from an agent to a script later needs no extra setup. To shut an agent out, revoke the key in the app.

How the skill works with the MCP server

Any client that speaks MCP can reach the server at https://yirlo.com/mcp over Streamable HTTP (spec revision 2025-06-18). There are 33 tools available, and calling any of them results in a single public Yirlo API request behind the scenes. For credentials, send the key in an Authorization header as Bearer <key>, or pass it in X-API-Key.

Claude Code users register the server by running the claude mcp add command with the HTTP transport, the name yirlo, the endpoint URL and an Authorization header carrying the Bearer key. Tools come from the server. Knowing which one to pick, how to interpret what comes back and when to stop and ask you first comes from the skill.

Once both are installed, a one-line ask like "what's the hot lead count for this week" gets translated into the right calls, and you never name a tool yourself. Where MCP is not available in your setup, the skill sends the agent to the plain API with the same key. Full reference: yirlo.com/api-docs.

The 33 tools, grouped

The skill lists every tool with a one-line purpose. Here they are by area:

• Account: get_account, get_balance
• Projects: once your first project exists (it begins on yirlo.com with your website), create_project adds further ones from a domain, with their campaigns paused until you start them, and get_project reports progress until each is ready. To review your projects and their results, call list_projects, get_project or project_analytics. Read the daily budget with get_project_budget, and change it with set_project_budget.
• Campaigns: create_campaign makes one, then start_campaign, stop_campaign or archive_campaign manages its life. For reading, use list_campaigns, get_campaign and campaign_analytics. Spending is handled by set_campaign_budget.
• Inbox and leads: list_inbox and list_hot_leads show what has arrived, read_conversation opens a thread, and reply sends an answer. set_lead_status and set_lead_note log what happened afterward.
• Suppression: suppress_emails blocks individual addresses, and suppress_domains blocks entire company domains.
• Webhooks: list_webhooks, add_webhook, test_webhook
• Team: list_team, invite_teammate

Where the agent asks before acting

Reading is free to do at any time. Listing campaigns, pulling analytics, opening a conversation and checking the balance change nothing, so the agent runs them without interruption.

A few tools change things in the real world. Sending a reply delivers a live message to the lead, so the skill makes the agent put the complete wording and the addressee in front of you before anything goes out. Launching a campaign, adjusting spend limits at the project or campaign level, and adding a colleague follow the same routine: the agent describes the change, waits for your approval, then carries it out.

The starting point is yirlo.com. Type in your site's URL there, and Yirlo reads through what you sell. From then on, an agent can handle the daily work.

Example requests

These are the kinds of asks the skill is written for. Each one maps to a short chain of tool calls.

• "Tell me how many hot leads we got this week." The agent calls list_hot_leads and totals them per campaign.
• "Pause the campaign for dentists." It finds the campaign with list_campaigns, confirms the match with you, then calls stop_campaign.
• "Set the daily budget to $30." The agent looks up the current amount, tells you what will change, and once you confirm, applies it with set_project_budget or set_campaign_budget.
• "Reply to our newest interested lead and suggest Tuesday." Given that instruction, the agent pulls up the thread using read_conversation, writes a proposed answer and puts it in front of you. The message goes out through reply only once you give the okay.
• "Block my competitor's website from ever being emailed." The agent runs suppress_domains with the domain you give it.
• "Forward each fresh hot lead to my Zapier webhook." The agent registers the endpoint with add_webhook, then fires test_webhook, which gives Zapier, n8n or Make sample data for field mapping.

Keeping an agent useful over time

A good routine is a weekly check-in. Ask the agent for analytics per campaign, the hot leads that arrived, and any conversations waiting on an answer. Because Yirlo already shifts budget toward campaigns that earn replies, your agent's job is mostly review, replies to warm leads, and the occasional budget or list change.

Add notes and statuses as you go. Asking the agent to record a note on a lead or mark its status keeps the account readable for you and your teammates, and it carries through to the lead CSV export.

Questions

Related