Lesson 04 — Skill generation

"""Skill registry — discover, validate, expose."""

from __future__ import annotations

import re
from pathlib import Path

import yaml
from pydantic import ValidationError
from rich import print as rprint

from src.schemas import SkillManifest

_FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)


def _parse_frontmatter(md: str) -> dict[str, object] | None:
    m = _FRONTMATTER_RE.match(md)
    if not m:
        return None
    parsed = yaml.safe_load(m.group(1))
    return parsed if isinstance(parsed, dict) else None


def discover_skills(skills_dir: Path) -> list[SkillManifest]:
    manifests: list[SkillManifest] = []
    for skill_md in sorted(skills_dir.glob("*/SKILL.md")):
        raw = skill_md.read_text(encoding="utf-8")
        fm = _parse_frontmatter(raw)
        if fm is None:
            rprint(f"[yellow]⚠ skipping {skill_md}: no frontmatter[/yellow]")
            continue
        try:
            manifests.append(SkillManifest.model_validate(fm))
        except ValidationError as e:
            rprint(f"[yellow]⚠ skipping {skill_md}: {e.error_count()} errors[/yellow]")
    return manifests


def as_tool_descriptions(manifests: list[SkillManifest]) -> str:
    if not manifests:
        return "(no skills available yet)"
    return "\n".join(
        f"- `{m.name}` — {m.description} (use when: {m.when_to_use})"
        for m in manifests
    )

# … imports previos …
from pathlib import Path

from deepagents.backends import FilesystemBackend  # tu ruta puede variar según versión
from src.skill_registry import as_tool_descriptions, discover_skills

SKILLS_DIR = Path(".skills")

SKILL_AUTHOR_INSTRUCTIONS = """You are a skill author for the CTL Academy workshop.

Given a description of a capability gap, write a new SKILL.md file that follows
the spec in .skills/README.md exactly. Use the `write_file` tool (inherited from
FilesystemMiddleware) to place it at `.skills/<snake_case_name>/SKILL.md`.

## Repo context — do NOT invent paths or data shapes

- Data source: `data/acme/*.md` are plain markdown files with tables of invoices,
  customers, and quarterly totals in COP. NOT CSV. NOT SQL. NOT a database.
- Memory backend by end of Lesson 05: `cognee` async Python library backed by
  Neo4j. Query API: `await cognee.search(query_text=..., query_type=SearchType.INSIGHTS)`.
- Realistic tools to declare in the SKILL.md: ["cognee_search"], optionally
  ["cognee_search", "cognee_add"]. Do NOT invent `execute_sql`, `read_csv`,
  `pandas_query`, `duckdb_query`.
- Do NOT invent env vars like `ACME_BILLING_PATH`. The dataset is fixed at
  `data/acme/*.md` — reference it explicitly in the Preconditions section.

## Rules for the SKILL.md you write

- Frontmatter MUST include: name, description, when_to_use, tools, allowed_actions.
- name must match snake_case regex ^[a-z][a-z0-9]*(_[a-z0-9]+)*$.
- description must be ≥ 20 characters.
- tools is a list of function name strings — do NOT implement them here.
- allowed_actions ⊂ {read, write, network}. Prefer ["read"] unless the skill ingests.
- Body sections: Preconditions, Procedure (numbered), Failure modes.
- Preconditions MUST cite `data/acme/*.md` and (for L05+) an initialized Cognee graph.
- Do NOT create tool.py. Only the SKILL.md.
- Return the path you wrote.
"""


def build_agent(llm: BaseChatModel | None = None) -> Any:
    skills = discover_skills(SKILLS_DIR)
    instructions = INSTRUCTIONS + "\n\n## Available skills\n" + as_tool_descriptions(skills)
    return create_deep_agent(
        tools=[],
        instructions=instructions,
        model=llm or build_llm(),
        subagents=[
            {
                "name": "skill_author",
                "description": "Writes new SKILL.md files following .skills/README.md spec",
                "prompt": SKILL_AUTHOR_INSTRUCTIONS,
                # NO pasar `tools` acá: el schema de DeepAgents no acepta strings.
                # El sub-agent hereda `write_file` desde FilesystemMiddleware.
            }
        ],
        # Backend REQUERIDO: sin esto el SKILL.md queda en StateBackend in-memory
        # y no aparece en `git status`. virtual_mode=True sandboxea al root_dir
        # (sin él el agente puede pedir /home y explota en macOS).
        backend=FilesystemBackend(root_dir=".", virtual_mode=True),
    )

If you cannot answer because a required skill is missing, do the following BEFORE
responding "no_capability":
1. Delegate to the `skill_author` sub-agent with a clear gap description that
   INCLUDES the data source shape ("markdown files in data/acme/") and the
   memory backend ("Cognee graph, available from Lesson 05").
2. After it writes the skill, note "skill_created: <name>" in your response.
3. Do NOT claim the skill is "ready to use" — it is not. Only the manifest
   exists; the implementation comes in Lesson 05.
4. Then respond "no_capability" — the human will re-run and this time the
   skill exists in the registry.