MODULE_11 · УРОК 11.1

Система skills

Рано или поздно вам захочется научить агента вещам, которых нет в его обучении: как в вашей команде принято делать auth, что за зверь у вас вместо миграций, почему тесты запускаются вот этой странной командой. Первый порыв понятен - вывалить всё в системный промпт. На одном-двух наборах знаний это даже работает. На пяти вы получаете промпт тысяч на пятнадцать токенов, платите за него при каждом вызове, а модель бродит по этой энциклопедии в поисках одной нужной строки.

Skills решают ту же задачу с другого конца, и приём старый как библиотечный каталог: в промпте лежат только названия и одна строка описания, а полный текст живёт в markdown на диске и приезжает ровно тогда, когда агент сам за ним потянулся. Каталог стоит копейки, книгу с полки берут по необходимости.

ЧТО ПОЛУЧИТСЯ Файл skills.py находит все skills/*/SKILL.md, в промпте появляется секция # Skills с коротким каталогом, а tool load_skill по имени отдаёт полный текст, но не больше заданного потолка длины.

Слова, которые встретятся

  • Skill - папка с файлом SKILL.md внутри: сверху описание для каталога, ниже сам текст со всеми подробностями и грязными деталями.
  • Постепенное раскрытие (progressive disclosure) - подход, при котором модель сначала видит только оглавление, а подробности запрашивает сама. Та же экономия, что с обрезкой вывода инструментов, только на слое знаний.
  • Frontmatter - блок метаданных между строками --- в начале markdown-файла. Нам хватит одного поля description:, но именно оно и решает, позовут skill или нет.

Быстрый путь

  1. Положить 1-2 skill в skills/<имя>/SKILL.md.
  2. Написать discover_skills + create_load_skill_tool.
  3. Секция Skills в prompts.py.
  4. Подключить в main.py.

Какие файлы трогаем

Файл Что делать
skills.py Создать. discover + фабрика load_skill.
skills/auth-patterns/SKILL.md Создать. Пример skill для проверки.
prompts.py Править. Поле skills + секция # Skills.
main.py Править. discover, tool, tool_names.

Шаг 1. Пример skill

Начнём с подопытного. Настоящей авторизации в учебном harness нет, и это даже удобно: skill проверяет механику загрузки, а не наши познания в OAuth.

skills/auth-patterns/SKILL.md

---
description: Паттерны и грабли при добавлении auth в этот проект
---
# Auth Patterns

В этом учебном harness auth пока нет - skill нужен как демо загрузки.

Если бы добавляли вход:
- не храните секреты в коде - только env;
- сначала спросите через ask_user: сессии vs JWT;
- правки держите в одном модуле (например auth.py), не размазывайте.

Ключевые файлы курса для ориентира: approval.py, prompts.py, main.py.

Шаг 2. skills.py

skills.py (целиком)

from __future__ import annotations

from pathlib import Path
from typing import TypedDict


class Skill(TypedDict):
    name: str
    description: str
    path: str


MAX_SKILL_CHARS = 4000


def _parse_frontmatter(md: str) -> dict[str, str]:
    if not md.startswith("---"):
        return {}
    end = md.find("\n---", 3)
    if end < 0:
        return {}
    block = md[3:end]
    out: dict[str, str] = {}
    for line in block.splitlines():
        if ":" not in line:
            continue
        key, _, val = line.partition(":")
        out[key.strip()] = val.strip().strip("'\"")
    return out


def discover_skills(dirs: list[Path]) -> list[Skill]:
    """Сканировать skills/*/SKILL.md. Первый каталог побеждает при коллизии имён."""
    skills: list[Skill] = []
    seen: set[str] = set()

    for root in dirs:
        if not root.is_dir():
            continue
        for entry in sorted(root.iterdir()):
            if not entry.is_dir() or entry.name in seen:
                continue
            path = entry / "SKILL.md"
            if not path.is_file():
                continue
            seen.add(entry.name)
            text = path.read_text(encoding="utf-8")
            meta = _parse_frontmatter(text)
            skills.append({
                "name": entry.name,
                "description": meta.get("description") or "(нет описания)",
                "path": str(path),
            })
    return skills


def create_load_skill_tool(skills: list[Skill]):
    by_name = {s["name"]: s for s in skills}

    async def load_skill(name: str) -> str:
        """Загрузить полный текст skill.

        WHEN TO USE: задача попадает в домен из секции # Skills
          (auth, db, тесты, деплой…).
        WHEN NOT TO USE: задача не связана ни с одним skill.
        DO NOT USE FOR: имя, которого нет в списке Skills.
        """
        skill = by_name.get(name)
        if skill is None:
            return f"Unknown skill: {name}"
        content = Path(skill["path"]).read_text(encoding="utf-8")
        if len(content) > MAX_SKILL_CHARS:
            return (
                content[:MAX_SKILL_CHARS]
                + f"\n... (truncated at {MAX_SKILL_CHARS} chars)"
            )
        return content

    return load_skill

Каталогов сознательно несколько: сначала смотрим в проектный cwd/skills, потом в общий ~/.harness/skills. Кто первый - тот и победил, поэтому локальный skill с тем же именем спокойно перекрывает глобальный. Логика знакомая по конфигам: личные настройки дома, проектные рядом с кодом, и проектные главнее.

Шаг 3. Секция в prompts.py

Сначала новое поле в PromptContext - туда приедет каталог:

    skills: NotRequired[list[dict[str, str]]]  # name + description

А теперь сама секция. Место ей после Guardrails, но точная позиция не принципиальна:

    if skill_list := ctx.get("skills"):
        lines = "\n".join(
            f"- {s['name']}: {s['description']}" for s in skill_list
        )
        parts.append(f"""
# Skills
Доступны skills ниже. Полный текст - через tool load_skill(name=...).
{lines}
""")

Одна строка на skill, и ни символом больше. Как только вы начнёте «на всякий случай» дописывать в каталог второе предложение, вся экономия пойдёт прахом, а мы вернёмся к промпту-энциклопедии, с которого урок начинался.

Шаг 4. Подключение в main.py

from pathlib import Path
import os

from skills import discover_skills, create_load_skill_tool

skill_dirs = [
    cwd / "skills",
    Path(os.path.expanduser("~/.harness/skills")),
]
skills = discover_skills(skill_dirs)
load_skill_fn = create_load_skill_tool(skills)

tool_names = [..., "load_skill"]  # ваши имена + load_skill

instructions = build_system_prompt({
    ...,
    "skills": [
        {"name": s["name"], "description": s["description"]} for s in skills
    ],
})

# Tool(load_skill_fn, takes_ctx=False) в список tools
ПОЧЕМУ ИМЕНА В ПРОМПТЕ, ТЕКСТ СНАРУЖИ Арифметика решает за нас. Пять skills по тысяче слов - это около пяти тысяч токенов, которые вы оплачиваете на каждом вызове, даже когда речь идёт о переименовании переменной. Пять однострочников - примерно сотня токенов. Модель при этом знает, что знания существуют, и сама решает, за каким лезть. Та же дисциплина, что в модуле 5 с обрезкой вывода инструментов, только применённая к знаниям.
МОДЕЛЬ ДОЛЖНА ПОПРОСИТЬ Никакой автозагрузки по угадыванию тут нет и не будет: skill приезжает только если load_skill действительно позвали. Отсюда типичная засада - знание лежит идеальное, а его никто не берёт. Лечится не кодом, а описанием: вставьте в description те слова, которыми задачу формулирует живой человек («OAuth», «JWT», «логин», «вход по паролю»). Описание тут работает крючком, а не аннотацией.

Проверьте

uv run python main.py . "Добавь OAuth-логин. Сначала загляни в skill auth-patterns через load_skill."

Если стрим из 10.2 включён, в stderr должен мелькнуть вызов load_skill с именем auth-patterns, и только после этого агент начнёт рассуждать про вход. Первый раз прямая просьба в промпте помогает убедиться, что механика жива; дальше уже интересно, догадается ли модель сама.

uv run python main.py . "Какой синтаксис у list comprehension в Python? Коротко."

А здесь load_skill не должен вызываться вообще: синтаксис языка модель знает и без наших заметок. Skill, который лезет в каждый разговор, ничем не лучше раздутого промпта.

Готово, если:

  • discover_skills читает frontmatter и пути
  • В промпте есть # Skills с именами и описаниями
  • load_skill отдаёт текст с потолком длины
  • Локальный skill перекрывает глобальный при том же имени
  • Задача со skill зовёт load_skill; посторонняя - нет
ДАЛЬШЕ Знания теперь подгружаются по требованию, а вот инструменты по-прежнему собираются руками в main.py. В следующем уроке заведём реестр: регистрируем новое, оборачиваем старое и не форкаем harness ради одного своего tool.