SKILL: Shipping Operational Experience as Code

This is a 10-part series sharing how Apidog developed Apidog CLI, a command-line tool for API testing and API lifecycle management. Read in order or jump to any post that interests you:

A SKILL is not just a command reference. It's an operating guide for AI Agents: when to use a command, which comes first, what fields shouldn't be guessed, when to validate, when to read back.

CLI Alone Isn't Enough

CLI commands give an Agent execution power.

But power without judgment leads to problems:

Agents need more than commands. They need operating judgment.

What Is SKILL?

A SKILL is an operating guide written for AI Agents.

It's not:

• A simple command list
• A reference manual
• A help page

It is:

SKILL gives Agents operating judgment.

Installation

SKILL is a companion to Apidog CLI:

# Install SKILL for your AI Agent
apidog skill install

This installs 8 companion Skills that help Agents understand:

• CLI command semantics
• Resource structures
• Task workflows
• Error handling
• Verification patterns

Why SKILL Matters: Hidden Workflows

The Agent still needs to know how tasks should be decomposed into cross-business execution flows.

This experience cannot be:

• Comprehensively written into tool descriptions (would consume too much context)
• Scattered in chat context (would be lost between sessions)
• Memorized by the model (product-specific, not general knowledge)

Hidden workflows and "business pitfalls" require explicit guidance.

Example: Test Scenario Maintenance

Consider maintaining a complex test scenario.

Wrong approach (Agent hand-writes from scratch):

Agent: "I'll create the test scenario structure manually"
Agent: Writes complete steps array with assertions, extractors, processors
Result: Field errors, wrong comparators, missing required fields
CLI: Rejects write or creates incomplete scenario

Correct approach (encoded in SKILL):

SKILL doesn't just say "there's a test-scenario update command."

It says:

"Complex scenarios are not suitable for hand-writing complete structures from scratch. A more stable path is to first import existing endpoint or case steps, then read back the complete structure, and finally make local modifications."

The Commands Behind SKILL Guidance

Here are the actual commands SKILL guides Agents to use:

# Step 1: Import steps from endpoints
apidog test-scenario import-steps <scenarioId> --project <projectId> \
  --source endpoint --ids <endpointIds> --sync manual

# Step 2: Read back with full detail
apidog test-scenario get <scenarioId> --project <projectId> \
  --with-case-detail

# Step 3: Update specific parts (Agent generates update JSON)

# Step 4: Validate before update
apidog cli-schema validate test-scenario-update --file ./scenario-update.json

# Step 5: Execute update
apidog test-scenario update <scenarioId> --project <projectId> \
  --file ./scenario-update.json

# Step 6: Run verification
apidog run --project <projectId> --test-scenario <scenarioId>

SKILL tells the Agent when to use each command and why.

Key Insight: get--with-case-detail

SKILL emphasizes:

"Use get--with-case-detail to get the real structure, not imagine the case inside steps."

Why this matters:

Getting real structure prevents imagination-based updates.

Evolvability: SKILL Can Change

Apidog SKILL is evolvable and versionable operational experience.

Why This Matters

How It Works

Agents are granted write permissions to SKILL.

If SKILL falls behind or becomes hard to use:

• Agent can modify it
• Agent can suggest improvements
• SKILL evolves through usage

SKILL is not frozen documentation. It's living operational code.

The Compatibility Layer

We learned this from real bugs:

Problem discovered:

Some scenario steps, during secondary updates, had outer steps updated successfully, but internal HTTP cases were not correctly updated.

Root cause:

• Internal case update markers needed special handling
• Agents didn't know about these markers
• Product semantics required specific flags

Solution:

• Compatibility logic put into CLI
• CLI handles internal markers automatically
• Users and Agents don't need to know internal details

The constraint meaning is layered into SKILL:

SKILL tells the Agent to use the right commands. CLI handles the product semantics behind those commands. The Agent doesn't need to understand internal markers.

On-Demand Loading

SKILL follows the same principle as cli-schema:

Complexity should be absorbed by execution and documentation, not fully exposed to the model.

SKILL approach:

• Agent warms up SKILL on demand
• SKILL loaded when task type is identified
• Only relevant workflow guidance enters context

SKILL vs. Documentation

The 8 Companion Skills

Apidog provides 8 companion Skills:

Each SKILL contains:

• Task type identification
• Command sequence guidance
• Field safety boundaries
• Validation checkpoints
• Verification patterns

What's Next

Now that we've established all three core components:

• cli-schema validate — Quality gate
• agentHints — Next-step navigation
• SKILL — Workflow judgment

The next question is:

Does this actually work? What are the numbers?

In Part 6, The Numbers Don't Lie: 30% Fewer Tool Calls, 25% Fewer Tokens, we'll share quantitative results from our internal comparisons—and explain where the savings come from.

Key Takeaways

• CLI gives execution power; SKILL gives operating judgment
• SKILL is an operating guide, not a command reference
• Hidden workflows require explicit guidance
• Import steps → read back → update locally is safer than hand-writing
• --with-case-detail prevents imagination-based updates
• SKILL is evolvable—Agents can modify it
• CLI absorbs product semantics, SKILL guides workflow
• On-demand loading prevents context burden

Download Apidog to design, mock, test, and document APIs in one workspace. Learn more about Apidog CLI for command-line API testing, CI automation, and AI Agent workflows.