This commit is contained in:
@@ -1,5 +1 @@
|
||||
"""Skills package."""
|
||||
|
||||
from .loader import LocalSkill, SkillLoader
|
||||
|
||||
__all__ = ["LocalSkill", "SkillLoader"]
|
||||
"""Agent Skills discovery and validation. The Skills themselves live in skills/ at the repository root."""
|
||||
|
||||
142
app/skills/agent_skills.py
Normal file
142
app/skills/agent_skills.py
Normal file
@@ -0,0 +1,142 @@
|
||||
"""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 split_frontmatter(text: str, source: Path) -> tuple[dict, str]:
|
||||
"""Split a markdown document into its YAML frontmatter mapping and body."""
|
||||
match = _FRONTMATTER_PATTERN.match(text)
|
||||
if not match:
|
||||
raise SkillFormatError(f"{source}: missing YAML frontmatter delimited by '---'")
|
||||
try:
|
||||
frontmatter = yaml.safe_load(match.group(1))
|
||||
except yaml.YAMLError as exc:
|
||||
raise SkillFormatError(
|
||||
f"{source}: frontmatter is not valid YAML: {exc}"
|
||||
) from exc
|
||||
if not isinstance(frontmatter, dict):
|
||||
raise SkillFormatError(f"{source}: frontmatter must be a mapping")
|
||||
return frontmatter, text[match.end() :]
|
||||
|
||||
|
||||
def read_skill(skill_dir: Path) -> SkillMeta:
|
||||
"""Parse and validate the SKILL.md in `skill_dir`."""
|
||||
skill_file = skill_dir / SKILL_FILE
|
||||
frontmatter, _ = split_frontmatter(
|
||||
skill_file.read_text(encoding="utf-8"), skill_file
|
||||
)
|
||||
|
||||
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
|
||||
@@ -1,22 +0,0 @@
|
||||
---
|
||||
name: architecture_design
|
||||
phase: design
|
||||
description: Guidance for GCP product selection, architecture design markdown, Mermaid diagrams, and Terraform IaC generation.
|
||||
---
|
||||
|
||||
# Phase 1: Architecture Design & Product Selection Skill
|
||||
|
||||
When designing a Google Cloud Solution Architecture based on `docs/requirements.md`:
|
||||
|
||||
1. **Resolve Deferred Product Choices**: Select Google Cloud managed services suited for regional high availability and scale:
|
||||
- Compute: Cloud Run / Cloud Functions / GKE.
|
||||
- Messaging & Ingestion: Pub/Sub, Eventarc, or Cloud Tasks.
|
||||
- State & Storage: Cloud Storage, Firestore, Cloud SQL, or Spanner.
|
||||
- Identity & Security: Cloud IAM, Secret Manager, KMS, Artifact Registry.
|
||||
2. **Architecture Documentation (`docs/architecture.md`)**:
|
||||
- Provide executive summary, component responsibilities, data flow, security model, and cost model.
|
||||
3. **Mermaid Diagram (`architecture.mmd`)**:
|
||||
- Render clean, valid Mermaid syntax (`graph TD` or `flowchart TD`) mapping client ingress, compute, messaging, and storage components.
|
||||
4. **Terraform Infrastructure as Code (`terraform/`)**:
|
||||
- Produce valid Terraform HCL files (`main.tf`, `variables.tf`, `outputs.tf`, `versions.tf`).
|
||||
- Ensure planability without credentials or resource provisioning during validation.
|
||||
@@ -1,105 +0,0 @@
|
||||
"""Dynamic Local Skill Loader."""
|
||||
|
||||
import logging
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
from typing import Dict, List, Optional
|
||||
import yaml
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
@dataclass
|
||||
class LocalSkill:
|
||||
"""Represents a local skill loaded from SKILL.md."""
|
||||
|
||||
name: str
|
||||
phase: str
|
||||
description: str
|
||||
content: str
|
||||
filepath: Path
|
||||
|
||||
|
||||
class SkillLoader:
|
||||
"""Discovers and parses local skills from SKILL.md files."""
|
||||
|
||||
def __init__(self, skills_dir: Path) -> None:
|
||||
self.skills_dir = skills_dir
|
||||
self._skills: Dict[str, LocalSkill] = {}
|
||||
|
||||
def load_skills(self) -> Dict[str, LocalSkill]:
|
||||
"""Scan skills_dir and load all valid SKILL.md files."""
|
||||
self._skills.clear()
|
||||
if not self.skills_dir.exists():
|
||||
logger.warning("Skills directory does not exist: %s", self.skills_dir)
|
||||
return self._skills
|
||||
|
||||
for skill_file in self.skills_dir.glob("**/SKILL.md"):
|
||||
try:
|
||||
skill = self._parse_skill_file(skill_file)
|
||||
if skill:
|
||||
self._skills[skill.name] = skill
|
||||
logger.info("Loaded skill '%s' (phase: %s)", skill.name, skill.phase)
|
||||
except Exception as exc:
|
||||
logger.error("Failed to parse skill file %s: %s", skill_file, exc)
|
||||
|
||||
return self._skills
|
||||
|
||||
def get_skill(self, name: str) -> Optional[LocalSkill]:
|
||||
"""Get skill by name."""
|
||||
if not self._skills:
|
||||
self.load_skills()
|
||||
return self._skills.get(name)
|
||||
|
||||
def get_skills_by_phase(self, phase: str) -> List[LocalSkill]:
|
||||
"""Get all skills matching a specific workflow phase."""
|
||||
if not self._skills:
|
||||
self.load_skills()
|
||||
return [skill for skill in self._skills.values() if skill.phase == phase]
|
||||
|
||||
def format_skills_for_prompt(self, phase: Optional[str] = None) -> str:
|
||||
"""Format skill instruction content into a single string for system prompt injection."""
|
||||
skills = self.get_skills_by_phase(phase) if phase else list(self._skills.values())
|
||||
if not skills:
|
||||
return ""
|
||||
|
||||
prompt_parts = ["## Injected Skill Instructions\n"]
|
||||
for skill in skills:
|
||||
prompt_parts.append(f"### Skill: {skill.name} (Phase: {skill.phase})\n{skill.content}\n")
|
||||
return "\n".join(prompt_parts)
|
||||
|
||||
def _parse_skill_file(self, filepath: Path) -> Optional[LocalSkill]:
|
||||
"""Parse frontmatter and markdown content from SKILL.md."""
|
||||
raw_text = filepath.read_text(encoding="utf-8")
|
||||
if not raw_text.startswith("---"):
|
||||
return LocalSkill(
|
||||
name=filepath.parent.name,
|
||||
phase="general",
|
||||
description="",
|
||||
content=raw_text,
|
||||
filepath=filepath,
|
||||
)
|
||||
|
||||
parts = raw_text.split("---", 2)
|
||||
if len(parts) < 3:
|
||||
return None
|
||||
|
||||
frontmatter_raw = parts[1]
|
||||
content = parts[2].strip()
|
||||
|
||||
try:
|
||||
metadata = yaml.safe_load(frontmatter_raw) or {}
|
||||
except Exception:
|
||||
metadata = {}
|
||||
|
||||
name = metadata.get("name", filepath.parent.name)
|
||||
phase = metadata.get("phase", "general")
|
||||
description = metadata.get("description", "")
|
||||
|
||||
return LocalSkill(
|
||||
name=name,
|
||||
phase=phase,
|
||||
description=description,
|
||||
content=content,
|
||||
filepath=filepath,
|
||||
)
|
||||
@@ -1,37 +0,0 @@
|
||||
---
|
||||
name: packaging_guide
|
||||
phase: package
|
||||
description: Guidance for assembling the comprehensive solution-architecture-guide.md following Google's official 8-section output template.
|
||||
---
|
||||
|
||||
# Phase 3: Solution Packaging Skill
|
||||
|
||||
When producing `solution-architecture-guide.md`, follow Google's official 8-section solution architecture output template:
|
||||
|
||||
1. **Executive summary and workload overview**
|
||||
- High-level business goals, workload description, and proposed solution architecture summary.
|
||||
2. **Requirements and current state**
|
||||
- **2.1. Functional requirements**: Business processes, key activities, and use cases.
|
||||
- **2.2. Non-functional requirements**: Security, reliability, cost, operations, performance, and sustainability requirements.
|
||||
- **2.3. Current state**: Existing As-Is architecture, pain points, and migration drivers.
|
||||
- **2.4. Dependencies**: Internal and external system dependencies.
|
||||
3. **Technical decomposition of the workload**
|
||||
- Layered breakdown of application tiers and logical components.
|
||||
4. **Proposed solution architecture**
|
||||
- **4.1. Google Cloud products and features mapping**: Selected products mapping table with justifications, doc citations, and alternatives considered.
|
||||
- **4.2. Architecture diagram**: Embedded Mermaid diagrams for As-Is (Before) and Target Google Cloud (After) architecture.
|
||||
- **4.3. Architecture description**: Data flow and task/control flow between components.
|
||||
5. **Design and configuration recommendations** (Architecture Framework Pillars)
|
||||
- 5.1 Security, privacy, and compliance (IAM, encryption, network security)
|
||||
- 5.2 Reliability (Redundancy, disaster recovery, RTO/RPO)
|
||||
- 5.3 Operational excellence (Monitoring, logging, IaC)
|
||||
- 5.4 Cost optimization (Sizing, autoscaling, pricing models)
|
||||
- 5.5 Performance efficiency (Caching, database & query optimization)
|
||||
- 5.6 Sustainability (Resource efficiency, serverless adoption)
|
||||
6. **Deployment guidance**
|
||||
- **6.1. Deployment prerequisites**: Required GCP APIs, SDK tools, and permissions.
|
||||
- **6.2. Step-by-step deployment instructions**: Complete Terraform IaC blueprint (`terraform/main.tf`) and CLI execution runbook.
|
||||
7. **Validation plan**
|
||||
- Pre-deployment validation results, dry-run checks, and Verification Checklist.
|
||||
8. **References**
|
||||
- Citations and documentation links grounded by Google Developer Knowledge MCP.
|
||||
@@ -1,19 +0,0 @@
|
||||
---
|
||||
name: requirements_discovery
|
||||
phase: discover
|
||||
description: Guidance for discovering, analyzing, and documenting GCP solution requirements.
|
||||
---
|
||||
|
||||
# Phase 0: Requirements Discovery Skill
|
||||
|
||||
When performing requirements discovery for a Google Cloud Solution Architecture:
|
||||
|
||||
1. **Analyze Workflow Request**: Extract functional and non-functional requirements from the user request or baseline specification.
|
||||
2. **Defer Product Selection**: During discovery, product selection must explicitly be marked as `deferred: true`. Do not commit to specific GCP products (e.g. Cloud Run vs GKE) until the design phase.
|
||||
3. **Capture Core Requirements**:
|
||||
- Authenticated HTTPS ingress, stateless processing, asynchronous domain events.
|
||||
- High availability within a selected GCP region.
|
||||
- At-least-once delivery with idempotent processing.
|
||||
- Least-privilege IAM service accounts and private networking where practical.
|
||||
4. **Document Assumptions and Open Questions**: Highlight unknowns regarding scale, traffic spikes, compliance, and specific region requirements.
|
||||
5. **Output Standard**: Produce a valid `docs/requirements.md` file matching the phase spec.
|
||||
@@ -1,22 +0,0 @@
|
||||
---
|
||||
name: source_discovery
|
||||
phase: source_discover
|
||||
description: Guidance for discovering, auditing, and documenting the existing pre-emptive source environment before target migration.
|
||||
---
|
||||
|
||||
# Phase 0a: Existing Source Environment Discovery Skill
|
||||
|
||||
When auditing and discovering an existing pre-emptive source environment:
|
||||
|
||||
1. **Assess As-Is Architecture**: Analyze existing workloads, on-premises applications, legacy infrastructure, or existing cloud provider setups.
|
||||
2. **Identify Existing Components**:
|
||||
- Monolithic / legacy application services & ingress endpoints.
|
||||
- Self-hosted database engines (e.g. MySQL, PostgreSQL, Oracle) or legacy file shares.
|
||||
- Traditional messaging queues (e.g. RabbitMQ, ActiveMQ).
|
||||
- Network topology, firewall rules, and authentication mechanisms.
|
||||
3. **Capture Source Metrics & Pain Points**:
|
||||
- Current scale, capacity constraints, downtime risks, and operational bottlenecks.
|
||||
- Security vulnerabilities, compliance gaps, and maintenance costs.
|
||||
4. **Document Source Architecture**:
|
||||
- Produce a clear `docs/source-architecture.md` baseline documenting the "Before" state.
|
||||
- Render a Mermaid diagram representing the existing source topology (`source-architecture.mmd`).
|
||||
@@ -1,19 +0,0 @@
|
||||
---
|
||||
name: validation_rules
|
||||
phase: validate
|
||||
description: Guidance for verifying Terraform syntax, Mermaid diagrams, and repository artifact completeness.
|
||||
---
|
||||
|
||||
# Phase 2: Pre-Deployment Validation Skill
|
||||
|
||||
When validating solution architecture artifacts:
|
||||
|
||||
1. **Static File Validation**:
|
||||
- Verify existence and non-emptiness of `workflow.yaml`, `requirements.yaml`, `docs/requirements.md`, `docs/architecture.md`, `architecture.mmd`, `terraform/main.tf`, `solution-architecture-guide.md`.
|
||||
2. **Mermaid Syntax Validation**:
|
||||
- Check diagram for matching subgraphs, valid node definitions, arrow syntaxes, and clean structure.
|
||||
3. **Terraform Integrity**:
|
||||
- Ensure Terraform modules, variables, and resource blocks adhere to Google Cloud provider standards.
|
||||
- Ensure static non-provisioning check passes (`deploy_resources: false`).
|
||||
4. **Output Report**:
|
||||
- Generate `validation-results.md` summarizing pass/fail status across all verification rules.
|
||||
Reference in New Issue
Block a user