Spec-First Was Yesterday. Welcome to Skill-First.

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:

API development is changing with AI Agents. Skill-First packages specs, tests, and scenarios into executable, verifiable skills—complementing existing approaches for the Agent era.

The Spec-First Era

For years, many development teams' collaboration processes were Spec-First.

What It Was

The Value

Spec-First was the right approach for human-driven API development.

The New Consumer: AI Agents

After AI Coding appeared, the consumers of API assets changed.

Agents also started consuming these assets.

What Agents Need

In this context, API documentation, test cases, and test scenarios in Apidog are not just collaboration materials for humans.

They are deterministically callable assets for Agents.

Asset Transformation

Assets transform from "readable" to "callable."

Skill-First Definition

Building on Spec-First:

Plus:

Skill-First = Spec-First + Agent execution layer.

The System Architecture

Each layer has a specific role.

How They Work Together

User: "Generate tests for the refund API and run verification"
        ↓
Agent: Understands task type (SKILL helps)
        ↓
Agent: Calls CLI to read endpoints (CLI executes)
        ↓
Agent: Generates test cases (Agent creates)
        ↓
CLI: Validates structure (cli-schema validates)
        ↓
Agent: Writes test cases (CLI executes)
        ↓
CLI: Returns agentHints (CLI guides)
        ↓
Agent: Reads back, adjusts (Agent follows hints)
        ↓
Agent: Runs tests (CLI executes)
        ↓
CLI: Returns report (CLI provides feedback)
        ↓
Agent: Summarizes to user (Agent completes)

Workflow Transformation

Spec-First Workflow (Human-Driven)

Human designs spec
        ↓
Human documents
        ↓
Human creates mock
        ↓
Human debugs
        ↓
Human writes tests
        ↓
Human publishes

Characteristics:

Skill-First Workflow (Agent-Assisted)

Human specifies goal
        ↓
Agent reads existing assets
        ↓
Agent generates changes
        ↓
CLI validates
        ↓
Agent writes
        ↓
CLI guides next steps
        ↓
Agent verifies
        ↓
Human reviews result

Characteristics:

What Teams Should Do

Immediate Steps

First Agent Task Example

Use Apidog CLI to help me create my first API endpoint in Apidog.
First, check my Apidog CLI setup and list the projects I can access.
Ask me which project to use. After I confirm, create a simple GET /health
endpoint named Health Check with a 200 response example. Validate any
structured input before writing, then read the endpoint back and summarize
what was created.

This gives:

Getting Started Commands

# Install Apidog CLI
npm install -g apidog-cli@latest

# Install companion SKILL
apidog skill install

# Check version (need 2.2.5+)
apidog -v

# Authenticate
apidog auth login

# List projects
apidog project list

The Future

The future is Agent-assisted API development.

The Complete Series Summary

We've covered the full journey:

The Final Principle

Spec-First was for human collaboration. Skill-First is for Agent execution.

Assets become callable. Workflows become executable. Quality becomes verifiable.

Welcome to Skill-First.

Key Takeaways

• Spec-First was right for human-driven development
• Agents are now consumers of API assets
• Assets transform from readable to callable
• Skill-First = Spec-First + Agent execution
• System: Apidog (assets) → CLI (execution) → SKILL (judgment) → Agents (action)
• Human specifies goal, Agent executes, CLI validates
• Start small, learn patterns, expand scope

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.