SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsapi-to-agent-cli

api-to-agent-cli

Coding & development

View repository

Updated 10-15 17:22

About this skill

API → Agent-Friendly CLI

Refactor internal APIs into a CLI that agents can actually call efficiently.Core constraints: no 1:1 wrapping allowed; you must first merge by business workflow; you must ship a companion SKILL.md; you must pass an 11-dimension audit.

When to use

  • The user says "turn this pile of internal APIs into a CLI agents can use"
  • The user already has a CLI and wants an agent-readiness retrofit
  • The user wants to score an existing CLI (skip straight to Phase 5)
  • The user is designing a new tool and wants it to be agent-native from the start

When not to use

  • The user wants a CLI for humans (every tradeoff in this Skill leans toward agents)
  • The user wants to build an MCP server (refer to the Anthropic MCP docs, not this Skill)
  • The user wants to build an LLM eval pipeline (that comes after Phase 5)

Workflow (5 phases)

First read references/principles-checklist.md to burn the 10 principles into your brain, then start.

Phase 1 · Inventory

Goal: list both "what APIs exist" and "what tasks the agent needs to do".

Steps：

  1. Read the user's API materials: OpenAPI spec, Swagger, Postman collection, SDK docs, source code, or even a purely verbal description will do
  2. Key step: have the user list the Top 20 high-frequency tasks the agent needs to solve. The user will slack off on this step, and you must insist on a complete list—without this list, Phase 2 is just blind merging
  3. Use assets/inventory.template.md to write inventory.md, including:
    • endpoints list (grouped by resource)
    • agent task list (one line per task: trigger scenario / expected input / expected output / how many endpoints it currently takes)

Hard constraints：

  • The number of agent tasks must be ≥ 10; below that means the user hasn't thought it through, so push them to fill it in
  • Each task must be describable as "in what conversation/scenario would the agent initiate this call", otherwise it's not a real task

Gate: after inventory.md is written, only proceed to Phase 2 once the user has reviewed and confirmed it.

Phase 2 · Workflow Merge ⭐ Core stage

Goal: merge N endpoints into 30–50 agent-facing commands, each command corresponding to one agent task.

This is the core value this Skill exists for. Skipping this step is the 1:1 wrapping trap, and agent performance will crash through the floor.

Steps：

  1. Read references/workflow-merge-examples.md to see 5 real merge cases
  2. For each agent task, answer:
    • To complete this task, how many endpoints does the agent currentlyhave to call?
    • Can they be merged into 1 command that chains them internally?
    • Does the merged command's input use semantic identifiers(name/email/slug), not UUIDs?
  3. Use assets/commands.spec.template.md to write commands.spec.md, with each command including:
    • command name (verb-noun, e.g. schedule-meeting, not events-create）
    • description (a single sentence the agent can understand: "what task does this command solve")
    • input parameters (semantic identifiers preferred)
    • internal fan-out (which endpoints this command calls behind the scenes)
    • Whether mutation (if yes → Phase 3 must add --dry-run）

Hard constraint — Merge Ratio：

  • Calculate merge_ratio = endpoint_count / command_count
  • If merge_ratio < 3: alarm, tell the user "this still looks like a 1:1 wrapper, please rethink whether every command corresponds to a real agent task"
  • The target ratio is 3-10. A few hundred APIs → 30-50 commands is the normal range

Gate: commands.spec.md is written, merge_ratio meets the target, and only after user review confirms can you proceed to Phase 3.

Phase 3 · Command Stub

Goal: generate a Python (Typer) code stub for each command by template, with all 10 principles reflected in the template.

Steps：

  1. Read references/cli-template-python.md to learn the Typer style (type hints automatically produce the schema,--help、validation）
  2. Read assets/example-hello-cli/ to see a complete example (a mini CLI demonstrating all 10 principles)
  3. Read references/error-schema.md to get the JSON schema for structured errors
  4. Write a stub for each command,mustinclude:
    • --output flag (default table, optional json, automatically switch to json when stdout is not a TTY)
    • --fields flag（field mask）
    • --limit and --page-token(for list-type commands)
    • --dry-run flag (for mutation-type commands)
    • input validation（control chars / path traversal / ? # % reject）
    • structured error JSON output (including suggestion field)
    • semantic exit codes（0/1/2/3/4/124）
    • schema subcommand (runtime introspection)
  5. Use comments as placeholders for the business logic (the part that actually calls the endpoint), for the user/follow-up agent to fill in

Hard constraints：

  • Every command must have --output json flag
  • mutation-type commands must have --dry-run flag
  • There must not be any input("Are you sure? (y/n)") interactive prompt
  • Errors must return error-schema.md the JSON structure defined

Phase 4 · SKILL.md (companion agent guide)

Goal: write a companion SKILL.md, loaded together when the agent gets this CLI.

--help tells the agent the parameter format,SKILL.md tells the agent the invariants and workflow—this is the vehicle for progressive disclosure.

Steps：

  1. Read assets/SKILL.template.md to get the template
  2. Sections that must be included:
    • Invariants(invariants that must be satisfied before every operation, e.g. "ALWAYS use --output json"）
    • Common Workflows(complete execution sequences for 3-5 typical agent tasks)
    • Authentication(how to get the token, where to put it)
    • Rate Limits & Pagination(how the agent should handle it)
    • Examples(real usage examples for each high-frequency command)
  3. Put SKILL.md at the root of the CLI repository, so it is loaded together when the agent loads this tool

Hard constraints：

  • SKILL.md must ship; without SKILL.md it does not count as complete
  • The "Common Workflows" section must have ≥ 3 complete cases
  • Do not write empty talk (e.g. "Make sure to handle errors gracefully"—tell the agent how handle）

Phase 5 · Self-Audit (11-dimension rubric)

Goal: use references/audit-rubric.md to score the generated CLI.

Steps：

  1. Read audit-rubric.md to get the 11-dimension scorecard
  2. Use assets/audit-report.template.md to output the scoring report
  3. Give each dimension a score of 0/1/2 (0=not done, 1=partially done, 2=fully done), total score 22
  4. List the specific gaps and fix suggestions for items that did not pass

Hard constraints：

  • A total score < 18 (≈ the equivalent of a full score on 9 items) does not count as passing, and you must go back to the corresponding phase to fix it
  • Antipattern hits (see antipatterns-quickref.md) deduct 2 points for each hit

Standalone invocation mode

audit-rubric canbe used independentlyof the 5-phase process:

User: "Help me check how the existing internal-cli agent-readiness is"

Skip directly to Phase 5: read audit-rubric.md, run the scoring, and output audit-report.template.md a report in the format. There is no need to go through Phase 1-4.

References index

File Which phase it is used in What it is
principles-checklist.md Throughout 10 principles quick check
workflow-merge-examples.md Phase 2 ⭐ 5 real merge cases
antipatterns-quickref.md Phase 2-3 7 antipatterns + solutions
cli-template-python.md Phase 3 Typer writing guide
error-schema.md Phase 3 Structured error JSON schema
audit-rubric.md Phase 5 (can be invoked independently) 11-dimension agent-readiness scorecard

Assets index

File When it is produced What it is
inventory.template.md Phase 1 Endpoints + agent tasks checklist template
commands.spec.template.md Phase 2 Merged command design template
SKILL.template.md Phase 4 Accompanying SKILL.md template
audit-report.template.md Phase 5 11-dimension scoring report template
example-hello-cli/ Phase 3 reference Complete runnable example (demonstrates all 10 principles)

Gotchas

  • Phase 2 is the core of this Skill — do not compromise. If the user wants to skip it or wants to "generate a stub first and then merge", you must refuse. The essence of the 1:1 wrapper trap is that the user wants to cut corners, and the existence of the OpenAPI spec makes "generate first" look reasonable
  • The Merge ratio check is not decoration. Below 3:1 is a problem, and you must really refuse to continue, not "warn once and let it through"
  • Do not pursue "automatic one-click conversion". Justin Poehnelt at Google also hand-designs every command. OpenAPI varies endlessly (auth, nested ref, polymorphic schema), and an automatic converter will never be good enough. The value of this Skill is the prescriptive workflow, not codegen
  • type hints are the soul of Typer. In Phase 3, all parameters must have complete type hints (including Optional, Literal, Annotated). Typer will automatically convert them into schema, help, and validation — 5 of the 10 principles are provided to you automatically
  • The "Common Workflows" section of the Phase 4 SKILL.md is the part that produces the highest value density. The core source of Will Steuk (CWC #14)'s improvement from 62% to 92% was migrating the business processes in the system prompt to SKILL.md for progressive disclosure
  • The Phase 5 audit is not for letting projects that "look good" pass. A total score < 18 must go back to be fixed, not just issue a warning. If this gate is loosened, the entire Skill loses its meaning

Source