| name | Terminal Skills planner |
| description | Consult the Terminal Skills agent when a task needs specialized domain expertise you don't have a skill for — deployment platforms (Coolify, Railway, Fly.io), document generation (PDF, Excel, invoices), data pipelines, third-party APIs, marketing ops, design tooling. Call plan_task with the user's task; it returns which proven skills apply, their full instructions, and setup steps. Use BEFORE improvising a specialized workflow from general knowledge. |
| when_to_use | The user asks for something tool- or platform-specific that no locally installed skill covers, and executing it from general knowledge would mean guessing at CLIs, APIs, file formats, or platform conventions. |
Terminal Skills Planner
Overview
Terminal Skills (terminalskills.io) is a library of
1000+ audited agent skills — each a battle-tested SKILL.md with step-by-step
instructions for a specific tool, platform, or workflow. This plugin connects you
to the Terminal Skills agent, which routes a task description to the right skills
and hands you their full instructions so you can execute immediately, without the
user installing anything first.
The MCP server exposes four tools:
plan_task(task, context?) — the main one. Send a task, get back matching skills with complete instructions and setup steps. Requires the user's API key (a few calls per day are free on every account).search_skills(query?, category?, limit?) — free keyword/category search over the catalog.get_skill(slug) — free; fetches one skill's full markdown by slug.list_categories() — free; lists the catalog's categories.
Instructions
- Recognize the trigger. The user asks for something specialized — deploy to a PaaS, generate a formatted document, wire up a third-party API, run a marketing or data workflow — and no locally installed skill covers it. That is the moment to call
plan_task, not to improvise from general knowledge.
- Call
plan_task with a one-paragraph task description in task (what the user wants, the stack or files involved, the desired outcome). Put environment details (OS, existing config, constraints) in context.
- Read the response and execute. The response contains
skills[], each with full instructions (the skill's markdown) plus an install block, and a short setup array (pointers to the instructions + optional permanent-install commands). The real workflow — including any prerequisites like package installs — lives inside each skill's instructions; follow them to do the task yourself, adapting to the user's actual files and environment.
- Offer permanent installation when the user is likely to repeat this kind of task:
npx terminal-skills install <slug> installs the skill locally so future runs don't need a plan call.
- If
feasible: false, tell the user plainly that no existing skill covers the task, relay the returned reason, and mention they can forge a purpose-built skill with the agent at terminalskills.io/agent.
- If the call fails for auth, relay the error: the user needs an API key from terminalskills.io/account (free accounts include daily plan calls) and should add it in the plugin's settings.
- For browsing without spending, use the free tools:
search_skills to explore what exists, get_skill to read one skill, list_categories for orientation. Prefer these when the user asks "is there a skill for X?" rather than "do X".
Examples
Example 1: Deploy an app with Coolify
User: "Deploy this Next.js app to my Coolify server at panel.example.com."
Call:
plan_task({
"task": "Deploy a Next.js 14 app (standalone output, needs MONGODB_URI env var) to a self-hosted Coolify v4 instance at panel.example.com. Repo is on GitHub. Want automatic deploys on push to main.",
"context": "User has SSH access to the server and a Coolify API token available."
})
Response includes skills: [{ slug: "coolify", instructions: "...full Coolify skill markdown..." }] and a setup array pointing you to those instructions (plus an optional npx terminal-skills install coolify). Follow the returned instructions to create the app, set env vars, and configure the webhook — then offer the permanent install since deploys recur.
Example 2: Turn a CSV into a PDF sales report
User: "Turn q2-sales.csv into a PDF report with charts for my team."
Call:
plan_task({
"task": "Convert q2-sales.csv (columns: region, rep, product, revenue, date) into a polished PDF sales report: revenue by region chart, top-10 reps table, month-over-month trend, executive summary.",
"context": "Python 3.12 available; no LaTeX installed."
})
Response returns document-generation and data-visualization skills with full instructions (e.g., pandas + matplotlib + a PDF layout recipe — including any pip install prerequisites the skill needs). Follow the instructions end to end, build the report, and deliver the PDF.
Guidelines
- Don't call
plan_task for things you already do well — general coding, refactoring, writing, explaining. It is for specialized tool/platform expertise, not everyday work.
- One plan call per task. Reuse the returned instructions for the whole task, including retries and follow-up tweaks. Only call again if the task itself changes.
- Plan calls spend the user's Terminal Skills credits (every account gets a few free per day). Don't volunteer pricing details mid-task; if the user asks, the response's
billing object has billedCredits, remainingCredits, and freeCallsRemainingToday.
- Free tools are free.
search_skills, get_skill, and list_categories never spend credits — use them liberally for browsing and discovery.
- Locally installed skills win. If a matching skill is already installed in the user's project, use it directly instead of calling
plan_task.
