AS
Standard: agentskills/agentskills

Day 1: agentskills Anatomy & YAML Frontmatter

12-Day Series
🗺️ SECTION 1 / SYSTEM BLUEPRINT & INTEGRATION

The "Where & Why": วิศวกรรม Skill Package และ Metadata Contract

🎯 Mental Map (148 Words): ยินดีต้อนรับสู่ Day 1 เรากำลังยกระดับการเขียน Prompt แบบหลวม (Hope-based prompting) สู่ Agent Skills Standard ซึ่งเป็นมาตรฐาน Declarative Software Package สำหรับ Host Agents (GitHub Copilot, Cursor, Claude Code)

ปัญหาเดิม: System Prompt ทั่วไปกิน Context Window ตลอดเวลา เกิด Token Degradation และ Semantic Collision ขณะที่ Host Agent ต้องคาดเดาโครงสร้างเอง
วิธีแก้ของ Day 1: เราออกแบบ SKILL.md พร้อม YAML Frontmatter ที่นิยาม Semantic Contract ชัดเจน ทำหน้าที่เป็น Router Interface ให้ Host Agent ทำ Lazy Resolution — โหลดเนื้อหาเข้า Working Context เฉพาะเมื่อ Intent ของงานตรงกับ description เท่านั้น
Agent Skill Package Topology & Host Lifecycle agentskills Specification v1.0 
.github/skills/ OR .cursor/skills/ OR skills/
 └── <skill-name>/                             ◄── Skill Root Package Directory
      ├── SKILL.md                             ◄── [TODAY'S FOCUS: Spec Contract & Frontmatter]
      │    ├── --- (YAML Frontmatter)          ◄── 1. Scanned at Host Startup (Indexed ~100 tokens)
      │    │    ├── name: <identifier>         ◄── Unique Namespace (slug-case)
      │    │    ├── description: <routing doc> ◄── Semantic Router Embeddings Gatekeeper
      │    │    └── schema-version: "1.0"      ◄── Contract Compatibility Standard
      │    └── --- (Markdown Instruction Body) ◄── 2. Lazy Loaded ONLY upon Intent Match
      ├── scripts/                             ◄── Deterministic CLI Executables (Phase 2)
      │    ├── run-verifier.sh
      │    └── ast-parser.py
      └── references/                          ◄── Heavy DTOs, Schemas, Golden Context (Phase 3)
           └── enterprise-contract.json
STEP 01: DISCOVERY

Index Frontmatter Only

Host Agent อ่านเฉพาะ YAML block ด้านบนสุดเพื่อสร้าง Index และ Semantic Map ในหน่วยความจำ โดยไม่โหลดตัวไฟล์ markdown ทั้งหมด

STEP 02: ROUTING

Semantic Intent Match

เมื่อ User พิมพ์ Prompt หรือสั่งงาน Agent จะเปรียบเทียบ Intent กับ description หากคะแนน Similarity ถึงเกณฑ์ จึง Trigger ตัว Skill

STEP 03: HYDRATION

Context Injection

Host ทำการ Lazy Hydrate นำ Markdown Instructions, Rules, และ Tool Scripts เข้าสู่ Active Context Window เพื่อเริ่มปฏิบัติการ

⚙️ SECTION 2 / ARCHITECTURAL DEEP DIVE

AI Skills ในฐานะ Declarative Software Packages

ในระดับ Production Software Engineering เราไม่มอง Prompt เป็นเพียงข้อความสั่งการ (Text Snippet) แต่ออกแบบ AI Skill ให้มีคุณสมบัติเหมือนกับ Library หรือ Package Module ที่มี Contract, Versioning, Preconditions และ Deterministic Tooling

มิติสถาปัตยกรรม (Dimension) Ad-hoc Chat Prompt Rules File (.cursorrules) Agent Skills Standard (SKILL.md)
Context Budgeting สูญเสีย Context โดยเปล่าประโยชน์ ต้อง paste ซ้ำทุก session Static Injection: ฝังอยู่ในทุก request เปลือง token ตลอดเวลา Dynamic Lazy Resolution: เสียค่า Token (~100 tokens) ตอน discovery และ hydrate เมื่อ match เท่านั้น
Semantic Routing ไม่มี ต้องให้ User สั่ง explicit prompt เสมอ Regex Path / Glob Matching (จำกัดอยู่แค่ path ของไฟล์) Intent-based Natural Language Router ผ่าน metadata.description
Deterministic Tools ไม่มี ต้องพึ่งความจำของ LLM 100% ไม่มี execution sandbox ในตัว Decoupled CLI Sandbox: รัน Shell / Python verification scripts ได้
Host Portability ยึดติดกับ Chat box ของแต่ละ Provider Vendor-lock (.cursorrules, .clinerules) Open Standard: รองรับ Copilot, Cursor, Claude Code, Windsurf
YAML Frontmatter Schema Specification

YAML Frontmatter ถูกคั่นด้วยเครื่องหมาย --- ที่จุดเริ่มต้นของ SKILL.md ทำหน้าที่เป็น Manifest Header สำหรับ Host Agent:

  • name (string, required): Unique Slug Identifier ของ Skill ต้องใช้ตัวพิมพ์เล็กและขีดกลาง (kebab-case) ห้ามมีช่องว่าง
  • description (string, required): สัญญาณเรดาร์บอก Host Agent ว่า "Skill นี้ทำอะไรได้ และควรถูกเรียกใช้ภายใต้เงื่อนไขใด" นี่คือหัวใจของการป้องกัน Trigger Collision
  • metadata (map, optional): กำหนด Author, Version, Framework constraints (เช่น junit: 5.10.2, mockk: 1.13.10)
Token Degradation & Context Budgeting

เมื่อ Prompt หรือ System Instructions ยาวเกินไป โมเดล LLM จะเกิดอาการ "Attention Saturation" หรือ "Lost in the Middle":

  • Cost of Global Rules: หากคุณมี 30 กฎ กฎละ 500 tokens ทุก prompt invocation จะเสียทันที 15,000 tokens ทำให้เหลือ Context สำหรับ Code จริงน้อยลง
  • Selective Lazy Loading: การแยกคำสั่งเฉพาะทางลงใน Skill ทำให้ Active Prompt สะอาด คงความแม่นยำทางไวยากรณ์ (Syntax Precision) สูงสุดตลอดกระบวนการ Agentic Loop
🧩 SECTION 3 / END-TO-END CODE BLUEPRINT

Production Artifact: Spring Boot Unit Tester Skill

ตัวอย่างโครงสร้างไฟล์ระดับองค์กรที่ปฏิบัติตามข้อกำหนด agentskills/agentskills อย่างเคร่งครัด สำหรับสร้างและตรวจสอบ Unit Test ในสถาปัตยกรรม Kotlin / Spring Boot

Package Directory Structure 
.github/skills/spring-boot-unit-tester/
├── SKILL.md                          # Main Declarative Manifest & Instruction Contract
├── scripts/
│   └── verify-tests.sh               # Deterministic Test Execution & AST Validation Runner
└── references/
    └── test-patterns.md              # Mocking conventions and golden assertions
FILE: .github/skills/spring-boot-unit-tester/SKILL.md Markdown + YAML 
---
# [TODAY'S LESSON PLUGS IN HERE: YAML FRONTMATTER SPECIFICATION]
name: spring-boot-unit-tester
schema-version: "1.0.0"
description: >
  Generates and fixes deterministic Kotlin unit tests for Spring Boot 3.x services 
  using JUnit 5, MockK, and AssertJ. Trigger this skill whenever writing backend 
  unit tests, mocking enterprise services, or troubleshooting failed Maven/Gradle 
  test runs. Never use for frontend or end-to-end Selenium tests.
metadata:
  author: "Platform Engineering Core"
  target-framework: "Spring Boot 3.2+"
  runtime: "Java 21 / Kotlin 1.9+"
  testing-libraries:
    - "org.junit.jupiter:junit-jupiter:5.10.2"
    - "io.mockk:mockk:1.13.10"
    - "org.assertj:assertj-core:3.25.3"
---

# Spring Boot Unit Test Architect Specification

## 1. Non-Negotiable Architectural Contracts
You are the Lead Quality Systems Architect. Every generated unit test MUST adhere to these rules:
1. **MockK Exclusivity**: NEVER import or generate `org.mockito.*` code. Use `io.mockk.*` exclusively.
2. **AAA Structure**: Explicitly annotate and separate `// Arrange`, `// Act`, and `// Assert` phases.
3. **No Database Hydration**: Do NOT annotate unit test classes with `@SpringBootTest` or `@DataJpaTest`. Tests must run in pure isolated JVM memory via standard instantiation and `mockk()`.
4. **AssertJ Fluent Assertions**: Use `assertThat(result).isEqualTo(...)` rather than JUnit's raw `assertEquals`.

## 2. In-Context Verification Preflight
Before declaring a test complete, verify the following boundary conditions:
- Are all external HTTP/Repository dependencies mocked using `every { ... } returns ...`?
- Are edge-case exceptions asserted using `assertThatThrownBy { ... }.isInstanceOf(...)`?
- Did you verify that no hardcoded IDs or unisolated state leak between execution threads?

## 3. Deterministic Local Tooling Integration
When instructed to run verification, the Host Agent must trigger:
`bash .github/skills/spring-boot-unit-tester/scripts/verify-tests.sh`
and analyze stdout/stderr according to the contract in Day 6.
🛠️ SECTION 4 / HANDS-ON SCENARIO & LAB

Enterprise Production Incident: The Mockito Infiltration

สถานการณ์จริง: ทีม Backend กำลัง Migrate โค้ดจาก Java เป็น Kotlin ทั้งระบบ โดยมีนโยบายบริษัทกำหนดให้ใช้ MockK แทน Mockito เพื่อป้องกันปัญหา Kotlin Final Class และ Coroutine Mocking แต่ GitHub Copilot มักจะพลั้งเผลอ Import org.mockito.Mockito.* เข้ามา ทำให้ Pipeline Build พัง

⚠️ MISSION OBJECTIVES
  1. สร้างโครงสร้าง Directory ตามมาตรฐาน .github/skills/spring-boot-unit-tester/
  2. เขียน SKILL.md ที่มี YAML Frontmatter ถูกต้องตาม Schema เพื่อให้ Host Agent ดักจับ Intent เวลาผู้ใช้สั่ง "สร้าง Unit Test Service" ได้อย่างแม่นยำ
  3. สร้าง Bash Linter Script ตรวจสอบว่าไฟล์ SKILL.md มี Syntax YAML ที่สมบูรณ์และไม่มีการหลุดคำว่า org.mockito เข้ามาในคู่มือ
VERIFICATION SCRIPT: scripts/verify-skill-compliance.sh POSIX Bash 
#!/usr/bin/env bash
# ==============================================================================
# verify-skill-compliance.sh
# Verifies that SKILL.md adheres to agentskills standards and Frontmatter schema
# ==============================================================================
set -euo pipefail

SKILL_FILE=".github/skills/spring-boot-unit-tester/SKILL.md"

echo "🔍 [1/3] Checking SKILL.md existence..."
if [[ ! -f "$SKILL_FILE" ]]; then
  echo "❌ Error: $SKILL_FILE does not exist!" >&2
  exit 1
fi

echo "🔍 [2/3] Validating YAML Frontmatter Delimiters (---)..."
# Frontmatter must start on line 1 with '---'
FIRST_LINE=$(head -n 1 "$SKILL_FILE")
if [[ "$FIRST_LINE" != "---" ]]; then
  echo "❌ Error: SKILL.md must start with '---' on line 1." >&2
  exit 1
fi

# Frontmatter must have closing '---'
DELIMITER_COUNT=$(grep -c "^---$" "$SKILL_FILE" || true)
if [[ "$DELIMITER_COUNT" -lt 2 ]]; then
  echo "❌ Error: SKILL.md is missing the closing '---' Frontmatter boundary!" >&2
  exit 1
fi

echo "🔍 [3/3] Scanning for negative anti-pattern rules (Negative Constraints)..."
if grep -q "org.mockito" "$SKILL_FILE"; then
  echo "✅ Found explicit Mockito constraints inside SKILL.md body."
else
  echo "⚠️ Warning: SKILL.md should explicitly state negative constraints against Mockito."
fi

echo "🎉 PASS: Agent Skill Frontmatter & File Contract is valid!"
exit 0
🎯 SECTION 5 / INTERACTIVE ARCHITECTURE & VERIFICATION QUIZ

ทดสอบสถาปัตยกรรม Agent Skills (Day 1)

Current Score
0 / 12

ตอบคำถามเชิงสถาปัตยกรรมทั้ง 12 ข้อด้านล่าง ระบบจะตรวจคำตอบและให้ Feedback ทันทีเมื่อคลิกเลือกช้อยส์ พร้อมแสดงคำอธิบายเชิงลึก