feat: vendor upstream Skills and add the GCP provider bundle
Increment 2 of .scratch/solution-architect-agent/spec.md. - Vendor google-cloud-solution-architecture and the six google-cloud-waf-* Skills from google/skills@81a31a6, unmodified, with LICENSE, SHA256SUMS and VENDOR.md; add scripts/sync-vendored-skills.sh to re-sync at a pinned sha. - app/agent_skills.py: discover Skills and validate SKILL.md frontmatter against the Agent Skills specification. - app/providers.py + providers/gcp.yaml: load and validate a Cloud provider bundle (Skills, output template, per-role models, tool tiers, remote MCP servers). MCP allowlists stay empty until the read-only review in increment 6. - Settings CLOUD_PROVIDER and MCP_ENABLE_PREVIEW. - 35 new tests; full suite 65 passed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
137
app/agent_skills.py
Normal file
137
app/agent_skills.py
Normal file
@@ -0,0 +1,137 @@
|
||||
"""Agent Skills discovery and frontmatter validation.
|
||||
|
||||
A Skill is a directory holding a SKILL.md whose YAML frontmatter follows the
|
||||
Agent Skills specification (https://agentskills.io/specification).
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from collections.abc import Iterable
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
|
||||
import yaml
|
||||
|
||||
SKILL_FILE = "SKILL.md"
|
||||
|
||||
_NAME_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
|
||||
_FRONTMATTER_PATTERN = re.compile(
|
||||
r"\A---[ \t]*\r?\n(.*?)\r?\n---[ \t]*(?:\r?\n|\Z)", re.DOTALL
|
||||
)
|
||||
_ALLOWED_FIELDS = {
|
||||
"name",
|
||||
"description",
|
||||
"license",
|
||||
"compatibility",
|
||||
"metadata",
|
||||
"allowed-tools",
|
||||
}
|
||||
|
||||
|
||||
class SkillFormatError(ValueError):
|
||||
"""A SKILL.md does not conform to the Agent Skills specification."""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class SkillMeta:
|
||||
"""The level-1 metadata of a Skill, plus where it lives."""
|
||||
|
||||
name: str
|
||||
description: str
|
||||
path: Path
|
||||
|
||||
|
||||
def read_skill(skill_dir: Path) -> SkillMeta:
|
||||
"""Parse and validate the SKILL.md in `skill_dir`."""
|
||||
skill_file = skill_dir / SKILL_FILE
|
||||
match = _FRONTMATTER_PATTERN.match(skill_file.read_text(encoding="utf-8"))
|
||||
if not match:
|
||||
raise SkillFormatError(
|
||||
f"{skill_file}: missing YAML frontmatter delimited by '---'"
|
||||
)
|
||||
|
||||
try:
|
||||
frontmatter = yaml.safe_load(match.group(1))
|
||||
except yaml.YAMLError as exc:
|
||||
raise SkillFormatError(
|
||||
f"{skill_file}: frontmatter is not valid YAML: {exc}"
|
||||
) from exc
|
||||
if not isinstance(frontmatter, dict):
|
||||
raise SkillFormatError(f"{skill_file}: frontmatter must be a mapping")
|
||||
|
||||
unknown = set(frontmatter) - _ALLOWED_FIELDS
|
||||
if unknown:
|
||||
raise SkillFormatError(
|
||||
f"{skill_file}: unsupported frontmatter fields: {', '.join(sorted(unknown))}"
|
||||
)
|
||||
|
||||
name = frontmatter.get("name")
|
||||
if not isinstance(name, str) or not name:
|
||||
raise SkillFormatError(f"{skill_file}: 'name' is required")
|
||||
if len(name) > 64:
|
||||
raise SkillFormatError(f"{skill_file}: 'name' must be at most 64 characters")
|
||||
if not _NAME_PATTERN.match(name):
|
||||
raise SkillFormatError(
|
||||
f"{skill_file}: 'name' must use lowercase letters, digits and single hyphens, "
|
||||
"without leading or trailing hyphens"
|
||||
)
|
||||
if name != skill_dir.name:
|
||||
raise SkillFormatError(
|
||||
f"{skill_file}: 'name' {name!r} must match its directory {skill_dir.name!r}"
|
||||
)
|
||||
|
||||
description = frontmatter.get("description")
|
||||
if not isinstance(description, str) or not description.strip():
|
||||
raise SkillFormatError(
|
||||
f"{skill_file}: 'description' is required and must be non-empty"
|
||||
)
|
||||
if len(description) > 1024:
|
||||
raise SkillFormatError(
|
||||
f"{skill_file}: 'description' must be at most 1024 characters"
|
||||
)
|
||||
|
||||
compatibility = frontmatter.get("compatibility")
|
||||
if compatibility is not None and (
|
||||
not isinstance(compatibility, str) or not 1 <= len(compatibility) <= 500
|
||||
):
|
||||
raise SkillFormatError(
|
||||
f"{skill_file}: 'compatibility' must be 1-500 characters"
|
||||
)
|
||||
|
||||
metadata = frontmatter.get("metadata")
|
||||
if metadata is not None and (
|
||||
not isinstance(metadata, dict)
|
||||
or not all(
|
||||
isinstance(key, str) and isinstance(value, str)
|
||||
for key, value in metadata.items()
|
||||
)
|
||||
):
|
||||
raise SkillFormatError(
|
||||
f"{skill_file}: 'metadata' must map string keys to string values"
|
||||
)
|
||||
|
||||
for field in ("license", "allowed-tools"):
|
||||
if field in frontmatter and not isinstance(frontmatter[field], str):
|
||||
raise SkillFormatError(f"{skill_file}: '{field}' must be a string")
|
||||
|
||||
return SkillMeta(name=name, description=description, path=skill_dir)
|
||||
|
||||
|
||||
def discover_skills(directories: Iterable[Path]) -> dict[str, SkillMeta]:
|
||||
"""Index every Skill that is an immediate child of one of `directories`.
|
||||
|
||||
Raises SkillFormatError on an invalid Skill or a name defined twice.
|
||||
"""
|
||||
skills: dict[str, SkillMeta] = {}
|
||||
for directory in directories:
|
||||
for child in sorted(directory.iterdir()):
|
||||
if not (child / SKILL_FILE).is_file():
|
||||
continue
|
||||
skill = read_skill(child)
|
||||
if skill.name in skills:
|
||||
raise SkillFormatError(
|
||||
f"Skill {skill.name!r} is defined in both {skills[skill.name].path} and {skill.path}"
|
||||
)
|
||||
skills[skill.name] = skill
|
||||
return skills
|
||||
@@ -49,6 +49,10 @@ class Settings(BaseSettings):
|
||||
ADK_MAX_LOOP_ITERATIONS: int = 5
|
||||
ADK_ENABLE_ARTIFACT_STORE: bool = True
|
||||
|
||||
# Cloud Provider Bundle (providers/<name>.yaml) & Remote MCP Servers
|
||||
CLOUD_PROVIDER: str = "gcp"
|
||||
MCP_ENABLE_PREVIEW: bool = True
|
||||
|
||||
# Google Developer Knowledge MCP Server Settings
|
||||
DEVELOPER_KNOWLEDGE_MCP_URL: str = "https://developerknowledge.googleapis.com/mcp"
|
||||
DEVELOPER_KNOWLEDGE_MCP_ENABLED: bool = True
|
||||
|
||||
159
app/providers.py
Normal file
159
app/providers.py
Normal file
@@ -0,0 +1,159 @@
|
||||
"""Cloud provider bundles.
|
||||
|
||||
A Cloud provider is configuration, not code (ADR-0002): providers/<name>.yaml lists
|
||||
the Skills, local tools, remote MCP servers and default models that one Cloud
|
||||
provider brings. Nothing outside this module names a provider.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Mapping
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
import yaml
|
||||
|
||||
from app.agent_skills import SkillFormatError, SkillMeta, discover_skills
|
||||
|
||||
TIERS = ("general", "cloud_read")
|
||||
_REPO_ROOT = Path(__file__).resolve().parent.parent
|
||||
|
||||
|
||||
class ProviderConfigError(ValueError):
|
||||
"""A provider bundle is missing or invalid."""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class McpServerSpec:
|
||||
"""A remote MCP server hosted by the Cloud provider.
|
||||
|
||||
Only tools named in `allow` are ever exposed; an empty `allow` exposes nothing.
|
||||
"""
|
||||
|
||||
id: str
|
||||
url: str
|
||||
tier: str
|
||||
allow: tuple[str, ...]
|
||||
preview: bool = False
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ModelConfig:
|
||||
default: str
|
||||
roles: Mapping[str, str] = field(default_factory=dict)
|
||||
|
||||
def for_role(self, role: str) -> str:
|
||||
return self.roles.get(role, self.default)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ProviderBundle:
|
||||
name: str
|
||||
skills_dirs: tuple[Path, ...]
|
||||
skills: Mapping[str, SkillMeta]
|
||||
output_template: Path
|
||||
models: ModelConfig
|
||||
tools: Mapping[str, tuple[str, ...]]
|
||||
mcp_auth: Mapping[str, Any]
|
||||
mcp_servers: Mapping[str, McpServerSpec]
|
||||
role_mcp_servers: Mapping[str, tuple[str, ...]]
|
||||
|
||||
def mcp_servers_for_role(
|
||||
self, role: str, include_preview: bool = True
|
||||
) -> tuple[McpServerSpec, ...]:
|
||||
servers = (
|
||||
self.mcp_servers[server_id]
|
||||
for server_id in self.role_mcp_servers.get(role, ())
|
||||
)
|
||||
return tuple(
|
||||
server for server in servers if include_preview or not server.preview
|
||||
)
|
||||
|
||||
|
||||
def load_provider(name: str, root: Path | None = None) -> ProviderBundle:
|
||||
"""Load and validate providers/<name>.yaml; relative paths resolve against `root`."""
|
||||
root = root or _REPO_ROOT
|
||||
config_path = root / "providers" / f"{name}.yaml"
|
||||
if not config_path.is_file():
|
||||
raise ProviderConfigError(f"No provider bundle for {name!r} at {config_path}")
|
||||
|
||||
config = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
|
||||
if not isinstance(config, dict):
|
||||
raise ProviderConfigError(f"{config_path}: must be a mapping")
|
||||
|
||||
def fail(message: str) -> ProviderConfigError:
|
||||
return ProviderConfigError(f"{config_path}: {message}")
|
||||
|
||||
if config.get("name") != name:
|
||||
raise fail(f"'name' must be {name!r}")
|
||||
|
||||
skills_dirs = tuple(root / entry for entry in config.get("skills_dirs") or ())
|
||||
if not skills_dirs:
|
||||
raise fail("'skills_dirs' must list at least one directory")
|
||||
for directory in skills_dirs:
|
||||
if not directory.is_dir():
|
||||
raise fail(f"'skills_dirs' entry {directory} is not a directory")
|
||||
try:
|
||||
skills = discover_skills(skills_dirs)
|
||||
except SkillFormatError as exc:
|
||||
raise fail(str(exc)) from exc
|
||||
|
||||
output_template = root / str(config.get("output_template", ""))
|
||||
if not config.get("output_template") or not output_template.is_file():
|
||||
raise fail(f"'output_template' {output_template} does not exist")
|
||||
|
||||
models = config.get("models") or {}
|
||||
if not isinstance(models.get("default"), str) or not models["default"]:
|
||||
raise fail("'models.default' is required")
|
||||
model_config = ModelConfig(
|
||||
default=models["default"], roles=dict(models.get("roles") or {})
|
||||
)
|
||||
|
||||
tools = {}
|
||||
for tier, tool_names in (config.get("tools") or {}).items():
|
||||
if tier not in TIERS:
|
||||
raise fail(f"'tools' tier {tier!r} must be one of {TIERS}")
|
||||
tools[tier] = tuple(tool_names or ())
|
||||
|
||||
mcp_servers = {}
|
||||
for server_id, spec in (config.get("mcp_servers") or {}).items():
|
||||
url = spec.get("url", "")
|
||||
if not url.startswith("https://"):
|
||||
raise fail(f"MCP server {server_id!r} url must use https")
|
||||
if spec.get("tier") not in TIERS:
|
||||
raise fail(f"MCP server {server_id!r} tier must be one of {TIERS}")
|
||||
if not isinstance(spec.get("allow"), list):
|
||||
raise fail(
|
||||
f"MCP server {server_id!r} needs an 'allow' list (empty exposes no tools)"
|
||||
)
|
||||
mcp_servers[server_id] = McpServerSpec(
|
||||
id=server_id,
|
||||
url=url,
|
||||
tier=spec["tier"],
|
||||
allow=tuple(spec["allow"]),
|
||||
preview=bool(spec.get("preview", False)),
|
||||
)
|
||||
|
||||
role_mcp_servers = {}
|
||||
for role, server_ids in (config.get("role_mcp_servers") or {}).items():
|
||||
unknown = [
|
||||
server_id for server_id in server_ids or () if server_id not in mcp_servers
|
||||
]
|
||||
if unknown:
|
||||
raise fail(
|
||||
f"role {role!r} references unknown MCP servers: {', '.join(unknown)}"
|
||||
)
|
||||
role_mcp_servers[role] = tuple(server_ids or ())
|
||||
|
||||
return ProviderBundle(
|
||||
name=name,
|
||||
skills_dirs=skills_dirs,
|
||||
skills=skills,
|
||||
output_template=output_template,
|
||||
models=model_config,
|
||||
tools=tools,
|
||||
mcp_auth=dict(config.get("mcp_auth") or {}),
|
||||
mcp_servers=mcp_servers,
|
||||
role_mcp_servers=role_mcp_servers,
|
||||
)
|
||||
Reference in New Issue
Block a user