SkillStore — disclosure progressiva

Skills são "memória procedural estreita e acionável" — a metade durável do ciclo de auto-aperfeiçoamento, complementando a memória declarativa ampla do MemoryStore. Uma skill é um diretório: um SKILL.md (frontmatter + corpo) mais arquivos opcionais sob references/templates/scripts/assets. A ideia definidora é a disclosure progressiva: list() lê só metadados baratos; view() carrega o corpo completo sob demanda. Um CLONE do skills_tool.py (1.638 LOC) + skill_manager_tool.py (1.233 LOC) do Hermes.

01 · O que é, de fato, uma "skill"

Antes do mecanismo, o objeto. Uma skill não é uma linha num banco — é um diretório no disco. No fundo dele há um arquivo obrigatório, SKILL.md, com duas partes: um cabeçalho --- … --- (o frontmatter, que guarda name e description) e o corpo de instruções abaixo. Em volta, quatro pastas opcionais carregam material de apoio.

Um SkillStore é apoiado por um FsPort injetado (a fronteira de IO do @alembic/etl) sobre um único diretório-base — o análogo do ~/.hermes/skills/ da fonte. Isso é a invariante de injeção da Lição 05: o store nunca toca fs direto, então é testável com um FsPort em memória.

Procedural vs declarativa: skill não é memória

Por que um subsistema separado, e não só guardar isso no MemoryStore? Porque os dois guardam coisas diferentes, com formas diferentes. A memória é ampla e declarativa ("o que eu sei"); a skill é estreita e procedural ("como eu faço"). Veja lado a lado:

02 · Disclosure progressiva: três níveis de custo

Aqui está a ideia central. Carregar o corpo de toda skill toda vez que você quer só saber que elas existem seria caro — desperdício de contexto e de tokens. A disclosure progressiva resolve isso pagando o custo em três níveis: você lista de graça, e só paga pelo conteúdo no momento exato em que abre.

O list() percorre o diretório-base, lê apenas o frontmatter de cada SKILL.md via readMetadata, ignora pastas sem skill válida, e devolve a lista ordenada por nome. Note o que ele não faz: nunca toca no corpo.

// packages/hermes/src/skills/skill-store.ts:80-96 — list (nível 1)
async list(): Promise<Result<readonly SkillMetadata[], Error>> {
  // … readDir(baseDir) …
  for (const entry of entries.value) {
    if (!entry.isDirectory) continue;
    const meta = await this.readMetadata(entry.name);   // só 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);
}

03 · list vs view — o comparativo que define o subsistema

Os dois lados da disclosure são list() e view(). Eles parecem irmãos, mas fazem leituras opostas do disco. Ver os dois lado a lado é entender o subsistema inteiro:

O view() também junta os linkedFiles: percorre as quatro pastas de apoio e lista os arquivos não vazios (size > 0) — detalhe que volta na seção 09 quando virmos como o delete funciona. O nível 3 é carregar um desses arquivos por caminho relativo, num view(name, relPath) posterior.

04 · O parser de frontmatter sem dependências

Como o frontmatter vira name e description? A fonte parseia YAML completo (CSafeLoader), com um fallback ingênuo de key: value quando o YAML dá erro. Para ficar sem dependências — adicionar uma dep yaml é uma condição de parada desta run — o clone reproduz exatamente esse fallback, e nada mais: só pares escalares de nível superior.

// 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 dois-pontos ⇒ pula a linha
  const key = line.slice(0, colon).trim();
  if (key.length === 0) continue;          // chave vazia ⇒ pula
  out[key] = line.slice(colon + 1).trim();      // 1º dois-pontos; chaves posteriores vencem
}

A detecção de fronteira do bloco espelha a fonte: o documento deve começar com ---, e o bloco fecha na primeira linha que é --- (casada como /\n---[ \t]*\n/ a partir do offset 3, frontmatter.ts:22). Um documento sem fence de abertura retorna ({}, content) — tudo vira corpo (frontmatter.ts:40–52).

05 · Faça o parse na mão (passo a passo → agora você)

Você viu a regra. Agora rode-a na mão, devagar, sobre um frontmatter de verdade — depois um caso é seu. Recuperar o procedimento (não só ler a regra) é o que fixa.

06 · Segurança de caminho: sem traversal, sob um subdir permitido

Uma skill pode guardar scripts e assets que o agente autorou. Escrever um arquivo dentro de uma skill é, no fundo, "escrever um arquivo no disco" — e isso é perigoso se o caminho puder escapar. O validateSupportPath é o portão: ele transforma "escrever um arquivo" numa operação delimitada e auditável, recusando qualquer caminho que tente sair da skill.

Diante de um caminho relativo, siga o fluxograma de cabeça — cada losango é uma checagem que ou barra o caminho ou o deixa passar. O caminho malicioso ../../secrets.txt está destacado: ele cai no losango de traversal.

// 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 …');

07 · CRUD: as cinco operações de mutação

Além de list/view (leitura), o store tem cinco operações que mudam o disco — todas devolvendo Result<T, Error>, nunca lançando exceção na fronteira pública. Cada uma tem regras de colisão/ausência próprias:

Vistas como um todo, as operações desenham o ciclo de vida de uma skill: ela nasce com create, é descoberta e aberta por list/view, evolui por edit/patch, e some por delete. Siga as transições:

08 · patch: um matcher, reusado — substring única

O patch faz um find-and-replace direcionado por substring ÚNICA — e deliberadamente reusa 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 entregue do Alembic em vez do helper Python.

Por que isso importa? Compare as duas filosofias de matcher lado a lado:

// 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));

09 · O guard de re-parse: um patch não pode corromper os metadados

Aqui está a sutileza que protege a skill de si mesma. Um patch opera sobre o texto bruto do SKILL.md — inclusive sobre o frontmatter. E se a substituição quebrar a estrutura do frontmatter em metadados inválidos? A resposta: depois de substituir, o patch re-parseia o resultado e re-valida; se quebrou, a escrita é recusada e a edição nunca cai.

10 · delete sem unlink: limpar para vazio

Última peça, e um desvio honesto. O FsPort do Alembic não expõe um unlink (nem remoção recursiva de diretório). Então como o delete "apaga"? Ele escreve uma string vazia por cima do SKILL.md. Um arquivo vazio tem frontmatter vazio → falha a validação → fica invisível a list() e view(). O marcador portável mais próximo de "deletado".

Confusões comuns

11 · Como isso se encaixa

O SkillStore não é uma peça solta — é a metade durável do ciclo de auto-aperfeiçoamento do Alembic. Pense nele como a memória de longo prazo procedural: enquanto o MemoryStore (Lição 07) guarda o que o agente sabe, o SkillStore guarda como ele faz. Os dois alimentam o mesmo loop fechado (Lição 08), e a disclosure progressiva é o que torna esse acervo barato de carregar quando o agente decide agir. Veja o trajeto, da origem ao consumo:

12 · Na prática

Sendo honesto: não existe um comando alembic skills que exponha o SkillStore na CLI — ele é uma biblioteca interna do @alembic/hermes, consumida pelo runtime, não um subcomando. [uncertain] nenhum comando da CLI canônica exercita diretamente este subsistema hoje. O caminho real para vê-lo rodar é o pacote de testes — que exercita as três níveis de disclosure e os cinco CRUD contra um FsPort em memória, sem tocar disco real:

# exercita o SkillStore — os 35 casos de skill-store.test.ts rodam aqui
pnpm --filter @alembic/hermes test
# …
# ✓ src/skills/skill-store.test.ts  (FsPort em memória → zero IO real)
#   ✓ list returns metadata only — name + description, never the body
#   ✓ view loads the full body + linkedFiles
#   ✓ rejects path traversal '..' in writeFile
#   ✓ refuses a patch that would corrupt the frontmatter
#   ✓ delete makes the skill invisible to list and view
# Test Files  1 passed   (entre os do pacote)
# Tests       35 passed  ← todos com um FsPort FALSO, nada toca seu disco

Os nomes dos casos acima são os reais de skill-store.test.ts (rodapé). A contagem de 35 é a do repo na escrita desta lição — o que importa é a invariante que cada caso prova, não o número exato.

E como o SkillStore é usado como API? Você o constrói com um FsPort e um diretório-base, e chama os mesmos métodos da disclosure progressiva. Este é o uso real — a mesma forma do teste (new SkillStore(fs, BASE)):

// uso da API — list (nível 1, barato) → view (nível 2, só ao abrir)
import { SkillStore } from '@alembic/hermes';

const store = new SkillStore(fs, '/skills');   // fs: um FsPort injetado

const all = await store.list();              // só frontmatter de cada skill
if (!all.ok) return all;                     // fail-closed: trate o err antes
for (const meta of all.value)
  console.error(meta.name, '—', meta.description);

const one = await store.view('pesquisar-web'); // AGORA paga o corpo
if (one.ok) console.error(one.value.body, one.value.linkedFiles);

// segurança: um caminho que tenta escapar é recusado ANTES de qualquer IO
await store.writeFile('pesquisar-web', '../../secrets.txt', 'x');
// ⇒ err('path traversal is not allowed') — nada é escrito (Result, nunca throw)

Repare em console.error, não console.log — saída de diagnóstico fora do canal padrão é a convenção do projeto. E todo método devolve Result<T, Error>: o if (!r.ok) return r é obrigatório antes de ler r.value — o typecheck recusa o contrário.

Fixe os conceitos (flashcards)

Clique pra virar. Tente lembrar a resposta antes de virar — recuperação ativa fixa mais que reler.