Skills profundas — o SkillStore e a disclosure progressiva

Memória e skills são as duas metades do loop que aprende. A memória é o que o agente sabe (declarativa, ampla); a skill é o que o agente sabe fazer (procedural, estreita). Esta lição é sobre a metade durável.

Uma skill não é um registro num banco: é um diretório no disco. Um arquivo obrigatório (SKILL.md) e quatro pastas de suporte opcionais, e nada mais.

O charset do nome também vem verbatim da fonte (VALID_NAME_RE): /^[a-z0-9][a-z0-9._-]*$/ — letras minúsculas, dígitos, ponto, hífen e sublinhado, começando por letra ou dígito. Tudo validado por Zod e elevado a Result, nunca lançado.

// packages/hermes/src/skills/types.ts:69-80 — o nome filesystem-safe
const SKILL_NAME_RE = /^[a-z0-9][a-z0-9._-]*$/;

export const skillNameSchema = z
  .string()
  .min(1, 'Skill name is required.')
  .max(MAX_NAME_LENGTH, `Skill name exceeds ${MAX_NAME_LENGTH} characters.`)
  .regex(SKILL_NAME_RE, 'Invalid skill name. Use lowercase letters …');

Os subdirs de suporte (SKILL_SUPPORT_DIRS) também são verbatim: references, templates, scripts, assets — espelhando ALLOWED_SUBDIRS da fonte.

Esta é a peça que define o subsistema. Listar tudo é barato; abrir um corpo custa só quando você abre; abrir uma referência custa só quando você precisa. Três níveis, três custos.

Disclosure progressiva: o custo de contexto sobe degrau a degrau — você só paga pelo que abre.

// packages/hermes/src/skills/skill-store.ts:80-96 — list (nível 1)
async list(): Promise<Result<readonly SkillMetadata[], Error>> {
  // … ensureDir + readDir(baseDir) …
  for (const entry of entries.value) {
    if (!entry.isDirectory) continue;
    const meta = await this.readMetadata(entry.name);   // só o frontmatter
    if (meta.ok) found.push(meta.value);              // pula dirs não-skill em silêncio
  }
  found.sort((a, b) => a.name.localeCompare(b.name));
  return ok(found);
}

Um diretório sem um SKILL.md legível e de frontmatter válido é simplesmente pulado (a tolerância _find_all_skills da fonte). A lista volta ordenada por nome.

A fonte parseia frontmatter com YAML completo (CSafeLoader), caindo num chave: valor ingênuo só quando o YAML dá erro. Para ficar sem dependências — adicionar um pacote yaml é uma stop-condition desta run — o clone reproduz exatamente esse fallback e nada mais: só pares escalares de topo.

// packages/hermes/src/skills/frontmatter.ts:60-70 — parseScalarBlock
for (const line of block.split('\n')) {
  const colon = line.indexOf(':');
  if (colon === -1) continue;               // sem ':' ⇒ pula a linha
  const key = line.slice(0, colon).trim();
  if (key.length === 0) continue;
  out[key] = line.slice(colon + 1).trim();      // split no 1º ':'; chave depois vence
}

Um documento sem fence de abertura devolve ({}, content) — a coisa toda é o corpo. Mapeamentos aninhados, listas e aspas-com-dois-pontos estão deliberadamente fora de escopo.

Arquivos de suporte são confinados. Um caminho relativo não pode conter segmento .. nem ., não pode ser absoluto, deve usar barras normais, e seu primeiro segmento deve ser um dos quatro subdirs de suporte.

validateSupportPath: quatro travas em sequência transformam "escreva um arquivo" numa operação limitada e auditável.

// packages/hermes/src/skills/skill-store.ts:404-437 — validateSupportPath (condensado)
if (relPath.includes('\\'))   return err(…'use forward slashes');
if (relPath.startsWith('/')) return err(…'must be relative');
const segments = relPath.split('/').filter((s) => s.length > 0);
if (segments.length < 2)     return err(…"must be under references/templates/scripts/assets");
for (const segment of segments)
  if (segment === '..' || segment === '.') return err(…'path traversal is not allowed');
if (!isSupportDir(segments[0]))    return err(…'first segment must be one of …');

O patch faz um find-and-replace alvo por substring único — e reusa de propósito o mesmo motor fail-closed que o memory store usa (match exato; zero ou múltiplas ocorrências → err), não o matcher fuzzy normalizador-de-espaços da fonte. A escolha é fidelidade à convenção já entregue do Alembic, em vez do helper Python.

// packages/hermes/src/skills/skill-store.ts:449-461 — replaceUnique
const first = content.indexOf(find);
if (first === -1) return err(new Error(`No match for '${find}' in SKILL.md.`));
const second = content.indexOf(find, first + find.length);
if (second !== -1) return err(new Error(`Multiple matches for '${find}' …`));
return ok(content.slice(0, first) + replace + content.slice(first + find.length));

O FsPort não expõe um unlink (nem remoção recursiva). Então delete e removeFile limpam o arquivo para vazio — o que o torna invisível ao list()/view(), porque frontmatter vazio falha a validação. É o marcador "deletado" portável mais próximo possível.

Note ainda: edit é uma reescrita completa do corpo que preserva o frontmatter parseado; ele recusa corpo vazio. E todo write é atômico (writeFileAtomic) — uma falha de IO vira err, nunca uma exceção solta.

Simples ↔ Técnico: a mesma ideia, duas alturas

Cartões de memória