SKILL: Đóng gói Kinh nghiệm Vận hành thành Code

Đây là phần 5 trong chuỗi 10 bài về cách Apidog phát triển Apidog CLI, công cụ command-line để test API và quản lý API lifecycle. Bạn có thể đọc theo thứ tự hoặc nhảy đến phần phù hợp với workflow của mình.

Dùng thử Apidog ngay hôm nay

	Tiêu đề	Trọng tâm
1	Chúng tôi Xây 126 MCP Tools. Nhưng Không là Giải pháp Tốt nhất cho Agent	Phát hiện vấn đề
2	Tại sao Chúng tôi Phát triển Apidog CLI Mới hoàn toàn	Phát triển architecture
3	Quy tắc Vàng: CLI Tạo Facts, Model Hành động trên Facts	Triết lý cốt lõi
4	agentHints: Dạy CLI Giao tiếp với Agents	Structured output
5	SKILL: Đóng gói Kinh nghiệm Vận hành thành Code	Kinh nghiệm vận hành
6	Con số Không Nói dối: 30% Ít Tool Calls, 25% Ít Tokens	Kết quả định lượng
7	Từ PRD đến Testing Loop: Workflow Agent Hoàn chỉnh với Apidog CLI	Tutorial thực tế
8	Tại sao CI/CD Compatibility Không thể Thiếu cho Agent Tools	Góc nhìn DevOps
9	AI Branch: Thay đổi Project An toàn hơn với AI Agents	Lớp bảo mật
10	Spec-First là Quá khứ. Chào Skill-First	Tầm nhìn & tương lai

---

SKILL không chỉ là command reference. Nó là hướng dẫn vận hành cho AI Agents: khi nào dùng command, command nào chạy trước, field nào không được đoán, khi nào validate, khi nào read back.

CLI Độc Không Đủ

CLI command cho Agent quyền thực thi.

Nhưng quyền thực thi không tự tạo ra judgment vận hành. Ví dụ:

Quyền CLI	Rủi ro nếu thiếu judgment
Tạo test case	Tạo trong sai project
Update test scenario	Update mà không read back
Import steps	Import mà không kiểm tra structure hiện tại
Run tests	Run mà không validate changes

Agents cần nhiều hơn commands. Agents cần operational judgment.

---

SKILL là gì?

SKILL là hướng dẫn vận hành viết cho AI Agents.

SKILL không phải là:

• Danh sách command đơn giản
• Trang help
• Sách tham khảo CLI

SKILL mô tả:

Nội dung SKILL	Mục đích
Khi nào dùng command	Map task type → command
Command nào chạy trước	Hướng dẫn sequence
Field nào không được đoán	Tạo safety boundary
Khi nào validate	Đặt quality gate
Khi nào read back	Xác định thời điểm verification
Khi nào run tests	Xác nhận workflow đã đúng

Nói ngắn gọn: CLI cho execution power, SKILL cho workflow judgment.

---

Cài đặt SKILL

SKILL là companion layer cho Apidog CLI.

# Install SKILL cho AI Agent
apidog skill install

Lệnh này cài 8 companion Skills để Agents hiểu:

• CLI command semantics
• Cấu trúc resource
• Task workflows
• Error handling
• Verification patterns

Sau khi cài, Agent không chỉ biết command tồn tại. Agent có thêm hướng dẫn về cách dùng command trong workflow thực tế.

---

Vì sao SKILL quan trọng: Hidden Workflows

Trong API workflows, nhiều task không thể được xử lý an toàn chỉ bằng một command đơn lẻ.

Agent cần biết cách decompose task thành execution flow cross-business.

Những kinh nghiệm này khó đặt ở các vị trí sau:

• Tool descriptions: quá dài, consume nhiều context
• Chat context: dễ mất giữa sessions
• Model memory: product-specific, không phải general knowledge
• CLI help: phù hợp cho humans hơn là workflow planning

Vì vậy, hidden workflows và business pitfalls cần được mã hóa thành hướng dẫn explicit.

---

Ví dụ thực tế: Bảo trì Test Scenario

Giả sử Agent cần update một test scenario phức tạp.

Cách sai: Agent tự viết toàn bộ structure

Agent: "Tôi sẽ tạo structure test scenario thủ công"

Agent viết:
- steps array
- assertions
- extractors
- processors
- nested HTTP cases

Kết quả:
- Field errors
- Comparator sai
- Missing required fields
- CLI reject write hoặc tạo scenario incomplete

Vấn đề nằm ở chỗ Agent đang đoán structure nội bộ thay vì làm việc từ dữ liệu thực.

Cách đúng: Workflow được mã hóa trong SKILL

Step	Mục tiêu
1. Import existing steps từ endpoints hoặc test cases	Không tự viết structure phức tạp từ đầu
2. Read back structure hoàn chỉnh	Lấy format thực sau khi import
3. Modify local JSON	Chỉnh trên base chính xác
4. Validate trước khi update	Catch lỗi schema trước khi ghi
5. Run scenario	Verify behavior sau update

SKILL không chỉ nói:

Có command test-scenario update.

SKILL nói rõ hơn:

Scenarios phức tạp không phù hợp để tự viết structure hoàn chỉnh từ đầu. Path ổn định hơn là import existing endpoint hoặc case steps, read back structure hoàn chỉnh, rồi make local modifications.

---

Commands phía sau SKILL workflow

Một workflow bảo trì test scenario có thể chạy như sau:

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

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

# Step 3: Agent tạo file update local
# Ví dụ: ./scenario-update.json

# Step 4: Validate trước khi 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>

Điểm quan trọng: SKILL nói Agent khi nào dùng mỗi command và vì sao command đó nằm ở vị trí đó trong sequence.

---

Insight chính: dùng --with-case-detail

Một guidance quan trọng trong SKILL là:

Dùng --with-case-detail để lấy structure thực. Không tưởng tượng case structure trong steps.

Vì sao flag này quan trọng?

Không dùng --with-case-detail	Có dùng --with-case-detail
Steps chỉ show IDs	Steps show full case structures
Agent không thấy internal format	Agent thấy assertion/extractor format thực
Agent đoán field names	Agent chỉnh từ examples thực

Read back structure thực giúp tránh updates dựa trên tưởng tượng.

---

Evolvability: SKILL có thể thay đổi

Apidog SKILL là kinh nghiệm vận hành có thể evolve và version.

Vì sao điều này quan trọng?

Thách thức	Cách SKILL xử lý
CLI commands thay đổi	SKILL có thể update để match
Users có personalized workflows	SKILL có thể customize
Product features mới	SKILL có thể extend
Workflow tốt hơn được phát hiện	SKILL có thể refine

Cách hoạt động

Agents được cấp write permissions cho SKILL.

Nếu SKILL bị lỗi thời hoặc khó dùng:

• Agent có thể modify
• Agent có thể suggest improvements
• SKILL evolve qua usage thực tế

SKILL không phải documentation frozen. Nó là operational code sống.

---

Lớp Compatibility

Một bài học đến từ bugs thực tế:

Với scenario steps, trong secondary updates, outer steps update thành công nhưng internal HTTP cases không được update đúng.

Root cause:

• Internal case update markers cần handling đặc biệt
• Agents không biết các markers này
• Product semantics yêu cầu flags cụ thể

Giải pháp:

• Đưa compatibility logic vào CLI
• CLI tự handle internal markers
• Users và Agents không cần biết internal implementation details

Ý nghĩa của constraint này:

• SKILL hướng Agent dùng đúng command và đúng workflow
• CLI xử lý product semantics phía sau command
• Agent không cần hiểu internal markers

Đây là separation hữu ích: SKILL hướng dẫn workflow, CLI absorb complexity.

---

On-Demand Loading

SKILL follow cùng nguyên tắc với cli-schema:

Complexity nên được absorb bởi execution và documentation layer, không expose toàn bộ cho model.

Các cách tiếp cận khác có vấn đề:

Alternative	Vấn đề
Load toàn bộ SKILL vào context	Token burden
Đặt tất cả rules trong --help	Competes for attention
Viết rules vào prompt	Khó update và khó version

Cách SKILL hoạt động:

• Agent warm-up SKILL on demand
• SKILL được load khi task type đã được xác định
• Chỉ workflow guidance liên quan đi vào context

Kết quả: Agent có đủ hướng dẫn để làm đúng việc, nhưng không phải giữ toàn bộ knowledge trong prompt.

---

SKILL vs Documentation

Documentation	SKILL
Cho humans đọc	Cho Agents execute
Giải thích command làm gì	Giải thích khi nào dùng command
Static reference	Dynamic workflow
Comprehensive	Task-focused
External to Agent	Integrated với Agent

Documentation vẫn cần cho developers. Nhưng với Agents, command reference là chưa đủ. Agent cần workflow logic có thể execute.

---

8 Companion Skills

Apidog cung cấp 8 companion Skills:

SKILL	Coverage
Project management	Projects, metadata, resources
API design	Endpoints, schemas, definitions
Environment management	Environments, variables
Test case creation	Single-endpoint tests, assertions
Test scenario management	Multi-step tests, import, update
Test suite organization	Grouping, execution
Import/export workflows	Data migration, backup
CI/CD integration	Pipeline commands, reports

Mỗi SKILL chứa:

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

---

Checklist triển khai workflow với SKILL

Khi dùng Apidog CLI với Agent, bạn có thể áp dụng checklist sau:

1. Xác định task type
2. Load SKILL liên quan
3. Dùng command sequence được SKILL hướng dẫn
4. Không đoán field phức tạp
5. Read back resource trước khi modify
6. Validate update payload
7. Execute update
8. Run test để verify

Với test scenario phức tạp, default workflow nên là:

Import existing steps
→ Read back với --with-case-detail
→ Modify local JSON
→ Validate schema
→ Update scenario
→ Run verification

---

Tiếp theo

Đến đây, chúng tôi đã thiết lập ba components cốt lõi:

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

Câu hỏi tiếp theo là:

Cách này có thực sự work không? Con số là gì?

Trong Part 6, Con số Không Nói dối: 30% Ít Tool Calls, 25% Ít Tokens, chúng tôi sẽ share kết quả định lượng từ internal comparisons và giải thích savings đến từ đâu.

---

Key Takeaways

• CLI cho execution power; SKILL cho judgment vận hành
• SKILL là hướng dẫn vận hành, không phải command reference
• Hidden workflows cần hướng dẫn explicit
• Import steps → read back → update locally an toàn hơn tự viết structure từ đầu
• --with-case-detail giúp tránh updates dựa trên tưởng tượng
• SKILL có thể evolve và version theo usage thực tế
• CLI absorb product semantics; SKILL guide workflow
• On-demand loading giảm context burden cho Agents

---

Download Apidog để design, mock, test, và document APIs trong một workspace. Learn more về Apidog CLI cho command-line API testing, CI automation, và AI Agent workflows.