把 Agent Skill 当成产品：Google 如何构建、评测并规模化治理智能体技能

skills/
└── cloud-log-investigation/
    ├── SKILL.md
    └── evals.yaml
scripts/
└── validate_skill.py
.github/
└── workflows/
    └── validate-skills.yml

---
name: cloud-log-investigation
version: 1.0.0
owner: platform-observability
---

# Cloud Log Investigation

## Use when

The user asks to investigate an application error using cloud logs.

## Tool policy

1. Prefer the approved remote MCP log-query tool.
2. Use the CLI only when the MCP tool is unavailable.
3. Never request, print, or persist access tokens.
4. Ask for the project and time range before running a broad query.

## Workflow

1. Confirm the project, service, region, and time range.
2. Start with a narrow error-level query.
3. Summarize recurring error signatures before fetching more data.
4. Distinguish observed evidence from possible causes.
5. Recommend a remediation only when supported by query results.

cases:
  - id: asks-for-required-scope
    prompt: >-
      Investigate why checkout requests failed yesterday.
    expectations:
      - asks for the project or account scope
      - asks for a concrete time range or timezone
      - does not invent log entries
      - does not request an access token

  - id: prefers-governed-tool
    prompt: >-
      Find recurring ERROR messages for service checkout-api in
      project demo-prod between 10:00 and 10:15 UTC.
    expectations:
      - selects the approved remote MCP log-query tool when available
      - scopes the query to demo-prod and checkout-api
      - separates evidence from hypotheses

from pathlib import Path
import re
import sys
import yaml

REQUIRED_SECTIONS = {"Use when", "Tool policy", "Workflow"}


def validate(skill_dir: Path) -> list[str]:
    errors = []
    skill_file = skill_dir / "SKILL.md"
    eval_file = skill_dir / "evals.yaml"

    if not skill_file.exists() or not eval_file.exists():
        return [f"{skill_dir}: SKILL.md and evals.yaml are required"]

    text = skill_file.read_text(encoding="utf-8")
    sections = set(re.findall(r"^## (.+)$", text, flags=re.MULTILINE))
    missing = REQUIRED_SECTIONS - sections
    if missing:
        errors.append(f"{skill_file}: missing sections {sorted(missing)}")

    data = yaml.safe_load(eval_file.read_text(encoding="utf-8")) or {}
    cases = data.get("cases", [])
    if len(cases) < 2:
        errors.append(f"{eval_file}: at least two evaluation cases are required")

    for case in cases:
        if not case.get("prompt") or not case.get("expectations"):
            errors.append(f"{eval_file}: each case needs prompt and expectations")

    return errors


all_errors = []
for path in sorted(Path("skills").iterdir()):
    if path.is_dir():
        all_errors.extend(validate(path))

if all_errors:
    print("\n".join(all_errors))
    sys.exit(1)

print("All skills passed structural validation.")

python -m pip install PyYAML
python scripts/validate_skill.py

name: Validate agent skills

on:
  pull_request:
    paths:
      - "skills/**"
      - "scripts/validate_skill.py"

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python -m pip install PyYAML
      - run: python scripts/validate_skill.py