The 4-Layer CLI Architecture.
CLI tool, per-method skills, full API catalog cached locally, plus meta-skills that compose across multiple CLIs. The shape behind every CLI shipped in this repo.
- A mental model for the whole stack from the binary at the bottom to the meta-skills at the top, with each layer earning its place.
- The composition rule for skills calling other skills, and why CLIs should stay platform-specific while workflows cross them.
- A diagnostic frame for when your CLI plus skills setup feels flat. Almost always a missing Layer 3 or Layer 4 problem.
Map this to a CLI you already have.
Pick a CLI plus skills setup you've already shipped (or borrowed). Hand this framework to Claude and have it diagnose which layers are present, which are thin, and which are missing.
How this fits in the OS.
At least one shipped or borrowed CLI plus a starter skill set on top of it. The Build Your First CLI guide is the prerequisite walk.
CLIs in your OS path, skills in ~/.claude/skills/ or project-scoped folders, a method catalog cached as searchable data, and meta-skills that compose across CLIs.
Cross-CLI workflows, self-serving lookup for the long tail of an API, and a skill library that grows organically as you use it instead of one you have to hand-curate.
The shape of the problem.
A CLI on its own is a binary in your OS path. A CLI with a few skills on top is a binary with shortcuts. Neither of those is what the production fleet runs. The production fleet runs a four-layer stack where each layer earns its place, and each layer covers what the layer below it can't.
This card is the deeper read of what Build Your First CLI built. There, four phases produced a CLI, a starter skill set, and a method catalog. Here, those become layers, and a fourth layer sits on top: meta-skills that compose across multiple CLIs and propose new skills as you discover workflows.
The CLI build guide calls the first three layers L1, L2, and L3. This card adds L4 for the cross-CLI meta layer that earlier docs treated as "skills calling skills" without giving it a number. Same architecture, sharper layout. If you've already shipped a CLI plus skills, you have L1 and L2. The question is whether L3 and L4 are present, thin, or missing.
The four layers at a glance.
Layer 2 handles the 80% of operations you run regularly. Layer 3 handles the 20% long tail. Layer 4 is what makes the whole thing compound instead of staying flat.
The four layers in detail.
The CLI tool
Capability layerWhat it is. A binary in your OS path that wraps the full API of one service. Python, Node, or Rust depending on the build. The agent calls it through the Bash tool. You almost never invoke it by hand.
What it does. Exposes every endpoint the API has. Handles auth, pagination, retries, and error formatting. Returns structured JSON by default so the agent can parse the output without guessing.
- Subprocess execution. Called from Bash, returns JSON, exits with a clean status code.
- Schema introspection. A
schemasubcommand or--schemaflag returns required and optional params plus an example. The CLI documents itself. - Dry-run mode. A
--dry-runflag on every write or delete shows the request without sending it. Critical at lower autonomy levels. - Multi-account routing. Per-command credential routing, the structural reason CLIs beat MCPs (Claude Desktop calls these connectors) for any service you use with more than one account.
What lives here. One binary per service. Platform-specific. The Slack CLI doesn't know about Zoom; the Zoom CLI doesn't know about Slack. Cross-platform composition happens at Layer 4, not here.
Per-method skills
Intelligence layerWhat it is. Markdown files Claude Code reads when triggered. A skill is a multi-step workflow, not a thin wrapper around one command. The CLI gave the agent capability. Skills give the agent when and how.
The decision test. Not "do I have the command?" but "do I have a workflow I'd want to replay without explaining it again?" If yes, that's a skill. If you're tempted to write a skill that just calls one CLI command, the catalog at Layer 3 already handles that case for free.
What lives here. Two kinds of skills:
- CLI-bound skills. One per atomic operation.
/slack-post,/zoom-get-transcript,/gws-send-email. Each knows the syntax of one CLI and one common operation on it. - The starter set. Five to start, never thirty. The operations you actually run. Everything else falls through to Layer 3.
Where it lives. Cross-project utility skills live globally in ~/.claude/skills/. Project-niche skills live in <project>/.claude/skills/. Too many globally-available skills dilute the agent's selection accuracy, which is the problem Wrangle Many Skills solves at the routing layer.
Method catalog
The library cardWhat it is. The full API spec for one service, cached locally as searchable structured data. Not a folder of skills. A queryable index of every endpoint, every parameter, every required scope, every rate limit.
What it solves. The Slack API has 306 web methods. The Google Workspace API surface is larger still. You will never write a skill for every operation, and you shouldn't try. The catalog is the answer to "what about the long tail."
How the agent uses it. When the agent hits an operation it doesn't have a skill for:
- Searches the catalog:
slack-cli methods search emoji - Pulls the full schema for a match:
slack-cli methods get emoji.list. Returns parameters, required scopes, rate limits. - Composes the API call dynamically from the real spec. Calls the CLI to execute it.
The framing comes from Vercel's OpenSRC tool: don't build scaffolding, give the agent a library card. The agent isn't guessing at syntax. It's reading the actual documentation and composing the call from first principles, only loading the schema it needs.
The N8N CLI works this way already. N8N constantly adds and updates nodes. Instead of maintaining static docs for every node, the catalog pulls current node info in real time, only when the agent needs it. No wasted context window, always current.
Layer 1 is obvious (you need a CLI). Layer 2 is obvious (you need shortcuts). Layer 3 is the one that gets left out, because the first time you build a CLI you only have 5 to 10 operations you care about and writing skills for those feels like enough. Then the long tail bites: a one-off Slack reminder, an obscure Drive filter, a Notion block type you've never used. Without Layer 3, every new operation needs a new skill or a manual prompt. With it, the agent self-serves anything in the API spec. The CLI grows from "the things you wrote skills for" to "the things the API can do."
Meta-skills
Composition + self-improvementWhat it is. Skills that compose across multiple CLIs, plus skills that generate other skills. This is where the architecture stops being "a CLI plus shortcuts" and starts being a system that compounds.
Two flavors that earn the Layer 4 name.
1. Cross-CLI workflow skills. The classic "after meeting" skill is not one command. It is a workflow that crosses two CLIs:
- Pull the meeting transcript from the Zoom CLI
- Pull the Zoom chat log
- Generate a summary and action items
- Post the summary to the right channel via the Slack CLI
- Log to an activity feed
The workflow skill doesn't know CLI syntax. It calls /zoom-get-transcript and /slack-post, the Layer 2 skills that do. Skills can call other skills. That's the composition mechanism. If the Slack CLI changes, you update /slack-post once and every workflow inherits the fix.
The architectural rule: keep CLIs platform-specific, keep workflows cross-platform. Don't build an "after-meeting CLI tool" that combines Zoom and Slack functionality. Build a workflow skill at Layer 4 that orchestrates the Layer 2 skills bound to each CLI.
2. Meta-skills that propose new skills. The agent hits a workflow it doesn't have a skill for, falls through to Layer 3, composes the call from the catalog, runs it. At the end, a meta-skill notices: "you just composed a new workflow. Want me to save it as a permanent skill?" On approval, it writes the skill file, tests it, adds it to the inventory. Next time, Layer 2 picks it up directly.
Your skill library isn't static. It grows organically as you use it. The meta-skill is the immune system: every new workflow becomes a permanent capability if you approve it. Without this, the catalog at Layer 3 keeps doing the same dynamic composition over and over for workflows you've already discovered.
A second meta-skill worth knowing about. The skill-description optimizer. Reviews the front-matter description fields on existing skills and rewrites them so the agent's auto-discovery scan picks them more reliably. Skill quality and skill discoverability are different problems; a perfectly correct skill the agent never invokes because its description is too generic is wasted. The optimizer makes existing skills more findable without rewriting their underlying logic. Pairs with the librarian-agent pattern at the routing layer.
The composition rule.
Once you have all four layers, there's one rule that determines whether the system stays clean or turns into a tangle:
Skills call skills. Skills don't call CLIs directly past Layer 2.
Layer 2 skills know CLI syntax. Layer 4 skills do not. A workflow skill at Layer 4 that posts a Slack message calls /slack-post, which knows the Slack CLI. It does not call slack-cli chat.postMessage --channel ... directly. The indirection is what makes the system survive CLI version changes, account routing tweaks, and credential rotation. Update the Layer 2 skill once; every Layer 4 workflow inherits the fix.
The same rule applies to Layer 3. The catalog returns a schema. A skill at Layer 2 or 4 takes that schema and calls the CLI. The catalog never shells out itself. Each layer has one job.
What this looks like in shipped CLIs.
Three CLIs from the AI Build Lab team, each running the four-layer pattern at a different scale.
Slack CLI Toolkit
Programmatic control over Slack from the terminal. Posts as a named bot identity, not as you. The key fix vs. Slack's MCP.
Google Workspace CLI
One CLI for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, Tasks, Apps Script. Auto-discovers new APIs from Google's Discovery Service.
N8N CLI Toolkit
Workflow management, debugging, credentials, security audits, multi-instance routing. The reference template for subsequent CLI builds.
The skill counts vary because each team built the Layer 2 set they actually use. The catalog at Layer 3 covers the rest. None of these are "30 skills and we're done" builds; they're "five to ten skills plus a catalog plus meta-skills that propose more as we discover workflows."
External validation.
The pattern this card describes isn't team-internal. The Google Workspace CLI at github.com/googleworkspace/cli has 26.5k stars, ships its own Claude skills in a .claude directory, and uses dynamic capability discovery (Google's Discovery Service) as its Layer 3. It exists because Google's official MCP doesn't cover enough. Thousands of teams chose this architecture over the vendor MCP. The four-layer shape isn't a one-team preference; it's the default for production agent fleets that need full API coverage.
The Vercel OpenSRC tool that inspired Layer 3 ("give the agent a library card, don't build scaffolding") is another public reference point. The pattern is being independently re-derived by multiple teams; this card is the consolidated read.
What changes for you.
If you've shipped a CLI plus skills already, you have L1 and L2. The shift to the four-layer model is small to describe and big to feel:
- You stop writing new skills for every API operation. The catalog at L3 covers the long tail. Skills are reserved for workflows you replay, not one-off operations.
- You stop building combo CLIs. Each CLI stays platform-specific. Cross-platform workflows live at L4, calling the L2 skills bound to each CLI.
- You stop hand-curating the skill library. Meta-skills at L4 propose new skills as you discover workflows. You approve, the agent writes the file.
- You start diagnosing differently. When the system feels flat ("it can only do the things I explicitly trained it to do"), the question is almost always "which layer is missing or thin." Usually L3, sometimes L4. Rarely L1 or L2.
This is the layer of the workshop where the CLI stops being a tool the agent uses and starts being a system the agent grows.
Where to go next.
You have the architecture. The natural next moves: