Система skills
Рано или поздно вам захочется научить агента вещам, которых нет в его обучении: как в вашей команде принято делать auth, что за зверь у вас вместо миграций, почему тесты запускаются вот этой странной командой. Первый порыв понятен - вывалить всё в системный промпт. На одном-двух наборах знаний это даже работает. На пяти вы получаете промпт тысяч на пятнадцать токенов, платите за него при каждом вызове, а модель бродит по этой энциклопедии в поисках одной нужной строки.
Skills решают ту же задачу с другого конца, и приём старый как библиотечный каталог: в промпте лежат только названия и одна строка описания, а полный текст живёт в markdown на диске и приезжает ровно тогда, когда агент сам за ним потянулся. Каталог стоит копейки, книгу с полки берут по необходимости.
skills.py находит все
skills/*/SKILL.md, в промпте появляется секция
# Skills с коротким каталогом, а tool
load_skill по имени отдаёт полный текст, но не больше
заданного потолка длины.
Слова, которые встретятся
-
Skill - папка с файлом
SKILL.mdвнутри: сверху описание для каталога, ниже сам текст со всеми подробностями и грязными деталями. - Постепенное раскрытие (progressive disclosure) - подход, при котором модель сначала видит только оглавление, а подробности запрашивает сама. Та же экономия, что с обрезкой вывода инструментов, только на слое знаний.
-
Frontmatter - блок метаданных между строками
---в начале markdown-файла. Нам хватит одного поляdescription:, но именно оно и решает, позовут skill или нет.
Быстрый путь
- Положить 1-2 skill в
skills/<имя>/SKILL.md. - Написать
discover_skills+create_load_skill_tool. - Секция Skills в
prompts.py. - Подключить в
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
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.