From agent-port
Use when driving AgentPort through the `ap` command-line tool — listing installed integrations, describing tool schemas, and executing tool calls from a code-running agent that doesn't speak MCP natively. Read agentport-overview first.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agent-port:agentport-cliThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Read **agentport-overview** first. This skill covers how to drive AgentPort through the `ap` command-line tool when your runtime can run shell commands but doesn't speak MCP directly.
Read agentport-overview first. This skill covers how to drive AgentPort through the ap command-line tool when your runtime can run shell commands but doesn't speak MCP directly.
ap is installed and on PATH.ap auth login). You can check this with ap auth status.If ap auth status reports auth_mode: none or the email field is blank, stop and ask the human to run ap auth login. Do not try to authenticate on their behalf.
Every command accepts -o json|toon|human. For programmatic use always pass -o json — it produces stable, machine-readable output. The default (human) is for terminal use and is not safe to parse.
When you need to accomplish something via a third-party service, work through these steps in order. Do not skip ahead — each step answers a question you need answered before the next one makes sense.
ap integrations list --installed -o json
This returns the integrations the user has already connected. Look for the integration_id you need (e.g. github, resend, slack). Each row also has a connected field — only connected: true integrations are usable.
ap tools list --integration <id> -o json
Each tool row has tool_name, description, and mode. The mode field tells you the approval policy: auto_approve, require_approval, or denied.
Skim the descriptions to find the tool(s) you want. If the descriptions don't give you enough to decide, describe them individually.
If the required integration is not in the installed list, do not try to install it yourself. Fetch the available list:
ap integrations list --available -o json
Confirm the integration exists, then tell the human what you need. A good message looks like:
I'd like to use the
githubintegration to open that issue, but it isn't connected yet. Can I connect to it via AgentPort and run the authentication flow? You can also run this yourself withap integrations add github.
Wait for the human to confirm before proceeding. Don't run ap integrations add on their behalf — the install flow is interactive (OAuth browser redirect or token paste) and needs a human at the keyboard.
Before calling any tool, fetch its parameter schema:
ap tools describe --integration <id> --tool <tool_name> -o json
This returns the tool's inputSchema — a JSON Schema describing every parameter, which are required, their types, enums, and descriptions. Do not guess parameter names or shapes. If a field is listed in required, you must provide it. If it's optional, omit it unless you have a concrete value.
ap tools call --integration <id> --tool <tool_name> --args '<json>' --info '<why>' -o json
The --args value must be valid JSON that conforms to the inputSchema you just fetched. Always include --info — see the next section for what to put in it.
--info--info is a free-text string that is not forwarded to the upstream tool. It is recorded in the audit log and shown to any human who reviews the call (especially on approval-gated tools). Include it on every call.
A good --info answers two questions for a reviewer who sees the call without your conversation context:
create_refund".One sentence is usually enough.
Many tool arguments are vendor IDs that mean nothing on their own: cus_OaBc…, Gmail message IDs, PostHog dashboard IDs, Slack channel IDs, Stripe invoice IDs. A reviewer cannot safely approve a call whose target is only identified by a random-looking string.
When an argument is an opaque ID, make it verifiable inside --info:
cus_OaBc… → https://dashboard.stripe.com/customers/cus_OaBc…42 → https://us.posthog.com/dashboard/42#417 in owner/repo → https://github.com/owner/repo/issues/417<id> → https://mail.google.com/mail/u/0/#inbox/<id>customer Alice Jordan (cus_OaBc…).Do not fabricate URLs you aren't sure are valid — a wrong link is worse than none. If you can't confidently link the ID, describe it instead.
Example:
ap tools call --integration stripe --tool create_refund \
--args '{"charge": "ch_3ObC…"}' \
--info "Refunding the duplicate \$49 charge for customer Alice Jordan (cus_OaBc…, https://dashboard.stripe.com/customers/cus_OaBc…) that she flagged in support ticket #812." \
-o json
ap tools call exits 0 and prints the tool's result on stdout. Parse and use.
ap tools call exits with code 2 and writes Approval required: <url> to stderr. Treat this as a stop condition. Follow the approval handling described in agentport-overview — share the URL with the human, wait for confirmation, then retry the identical command with the identical --args. Changing the args invalidates the pending approval.
ap tools call exits with code 1 and writes Denied: … to stderr. There is no path forward — do not retry, do not try a different tool to reach the same outcome.
| Goal | Command |
|---|---|
| Am I logged in? | ap auth status -o json |
| What's installed? | ap integrations list --installed -o json |
| What's available? | ap integrations list --available -o json |
| What tools does X expose? | ap tools list --integration <id> -o json |
| What does tool Y take? | ap tools describe --integration <id> --tool <name> -o json |
| Run tool Y | ap tools call --integration <id> --tool <name> --args '<json>' --info '<why>' -o json |
ap integrations add or ap integrations remove without the user's explicit instruction — installation is a user-authentication flow.ap tools describe is cheap; use it.-o json flag when automating; parsing the human output is brittle.exit 1 (denied) or fabricate workarounds. Ask the human.--info, and don't fill it with generic filler ("calling tool"). Write a real sentence of intent.--args without also naming or linking them in --info so a reviewer can verify them.Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub yakkomajuri/agentport-skills --plugin agent-port