Referência · som-skill-library

Skills

O SOM carrega contexto; as Skills carregam conhecimento. Uma skill é uma regra escrita uma vez, pela redação, e legível por todas as ferramentas. Ela declara o que é verdade — quem age é só a ferramenta dona do executor.

Declarar, não agir Anatomia A biblioteca Combinando holds Validação O que está em aberto

O modelo

Skills declaram. Executores agem.

A skill declara

Um arquivo de skill enuncia uma condição e o que é verdade quando ela se cumpre — uma flag está de pé, um hold se aplica, um enriquecimento se justifica. Ele nunca executa nada, nunca escreve estado da história e nunca altera conteúdo.

O executor aciona (recall)

Os executores vivem dentro das ferramentas dos fornecedores. Cada um compara as mensagens que chegam com os adverts das skills — o bloco recall, lido por máquina — e publica o que a skill declara como skill.warning.raised.

A ferramenta age

O MAM impede o commit de um asset retido, o playout recusa o take, o CMS segura um caminho. Cada um a seu modo, e cada um decidindo por si. Ninguém recebe comando nenhum.

Formato aberto, política da casa. As skills seguem o formato aberto agentskills.io ↗: um arquivo markdown com frontmatter YAML. A biblioteca compartilhada é genérica; cada redação carrega nela os próprios valores. Sua política continua sendo sua, e uma redação pode implementar o SOM 1.0 por completo sem usar a biblioteca.

Anatomia

Um arquivo: frontmatter para as máquinas, prosa para as pessoas

---
skill_id: smart-stories/hold-while-flagged
skill_version: 0.2.2
som_schema_version: ["1.0.0"]
skill_type: REFERENCE
category: compliance
lifecycle: draft

recall:                      # the advert
  target_system_type: [mam, playout, rundown,
                       cms, compliance_hub]
  conditions:
    - kind: field
      path: editorial_gates[].gate_type
      op: equals
      value: "{{ config.gate_type }}"
    - kind: field
      path: editorial_gates[].status
      op: equals
      value: PENDING
  recall_on: ["story.context", …]
  state_path: editorial_gates[].status

output_messages: ["skill.warning.raised"]
severity_range: [hold]
auto_change_content: false
fail_closed: true
migration_policy: GATED
disclosure_level: L2
depends: []
---
# hold-while-flagged
…what it is, config surface, runtime loop,
 output contract, worked configurations,
 eval set, open items, vendor build notes

Identidade

skill_id no formato publisher/name, uma skill_version semver, as versões de schema do SOM contra as quais ela resolve, uma category e um lifecycle.

O advert

recall diz quais tipos de ferramenta podem pegar a skill, as condições sobre caminhos da história (field e field_change) e quais mensagens provocam uma verificação. Os caminhos são literais e conferidos contra o schema publicado; os valores podem vir de templates preenchidos pela configuração da casa.

Instância configurada

Um arquivo genérico com os valores de uma casa carregados, vigiando uma condição. Uma casa roda várias a partir do mesmo arquivo — uma restrição judicial com escopo story, um número não confirmado com escopo link — e registra uma linha de advert por instância configurada.

Severidade

hold / flag / inform, em minúsculas para sempre. Uma skill declara em severity_range quais delas pode produzir.

Garantia	Valor	O que significa
`auto_change_content`	`false`	O único valor permitido. O que se retém é uma ação, nunca o conteúdo — um executor que edita para liberar quebrou o modelo.
`fail_closed`	`true`	Um valor ilegível é tratado como se a condição valesse, na severidade mais alta que a skill tem. Silêncio diante de uma restrição ilegível nunca é permitido.
`output_messages`	`["skill.warning.raised"]`	Uma skill tem uma única maneira de dizer qualquer coisa. Ela nunca escreve estado da história.
`depends`	`[]`	O encadeamento acontece pela pipeline, não por dependências declaradas. Um hold se anuncia (advert) a partir do estado da flag, não importa quem a levantou.

som-skill-library 0.2.2

Dez skills de referência, uma proposta

Todas lifecycle: draft, origin: reference, resolvendo contra o SOM 1.0. Encontre o tipo da sua ferramenta na tabela de consulta, leia as skills daquela linha e configure-as para a sua casa.

Skill	Declara	Categoria	Severidade	Acionada por
`raise-flag-on-match`	Uma flag nomeada numa história quando um campo configurado casa com um valor configurado — já na criação, antes mesmo de existir qualquer mídia.	compliance · X=1	flaginform	`planning` `rundown` `mam` `graphics` `discovery`
`hold-while-flagged`	Uma ação nomeada retida enquanto houver uma flag de um tipo configurado, liberada apenas por uma liberação de autoridade igual ou superior no mesmo escopo.	compliance · X=1	hold	`mam` `playout` `rundown` `cms` `compliance_hub`
`gate-by-scope`	Se o gate de um caminho de destino permite um telling agora mesmo. Sempre com escopo de link.	compliance · X=1	holdinform	`cms` `playout` `rundown` `mam` `distribution`
`record-provenance-on-ingest`	Que a proveniência de uma fonte fica registrada quando ela entra numa história — inclusive uma cadeia C2PA ausente, registrada como ausente.	compliance · X=1	inform	`mam` `ingest` `verification` `discovery` `archive`
`flag-on-mismatch`	Uma divergência quando um asset vinculado ou um item do espelho carrega um valor que a história já não tem — nomeando os dois valores.	editorial · X=2	flaginform	`rundown` `graphics` `cms` `playout`
`apply-clearance`	Qual membro de um conjunto de versões preparadas uma liberação torna vigente, e quais membros ela substitui.	workflow · X=3	inform	`playout` `rundown` `mam` `cms` `graphics`
`enrich-on-condition`	Que um enriquecimento nomeado se justifica para um asset enquanto uma condição configurada se mantiver. Nunca executa o enriquecimento.	workflow · X=3	inform	`mam` `verification` `multimodal` `transcription` `ingest`
`match-and-propose`	Uma história candidata para um clipe solto, com confiança igual ou acima da definida pela casa. A confirmação é um ato humano, registrado em outro lugar.	workflow · X=3	inform	`multimodal` `mam` `discovery` `ingest` `rundown`
`select-provider-by-context`	Qual fornecedor a política da casa indica para uma capacidade, dado o contexto da história. Nunca atribui nem aciona.	workflow · X=3	inform	`transcription` `verification`
`surface-on-context-match`	Um item de uma fonte monitorada que corresponde à história em andamento, com a sua proveniência. Aditivo, fora do caminho crítico.	workflow · X=3	inform	`transcription` `verification` `discovery` `markets_data` `mam` `planning`
`declare-context-on-commit` proposta	O contexto da história que se aplica a um link quando um asset é vinculado a um destino.	workflow · X=3	inform	`playout` `mam` `graphics`

Tabela de consulta ↗ · Convenções ↗ · Todos os arquivos de skill ↗

Quando as skills se encontram

Holds se combinam por conjunção

Basta um hold para reter

Quando vários gates se aplicam ao mesmo fato no mesmo telling, ele só é servido quando todos permitem. “O mais restritivo vence” e “o dono da história tem precedência” foram formalmente retirados em 29 de julho de 2026.

A precedência entre duas skills que entram em conflito sobre a mesma ação é outra questão, ordenada por X (categoria: compliance 1, editorial 2, workflow 3), Y (origem — toda skill da biblioteca é 5) e Z, que só a casa publicadora define.

Encadeamento pela pipeline

Uma skill que ao mesmo tempo declarasse um estado e retivesse algo ocuparia duas posições de uma vez. Por isso “flag e hold” são duas skills: flag-on-mismatch declara a flag, e hold-while-flagged se anuncia (advert) a partir do estado da flag — não importa quem a levantou, uma skill ou um advogado.

É por isso que depends está vazio em toda parte: declarar uma dependência a inverteria e criaria um ciclo na primeira mudança de versão.

Fail-closed. Um valor ilegível na configuração ou na história é tratado como se a condição valesse, na severidade mais alta que a skill tem, e detail diz o que não pôde ser lido. Se uma regra não pode ser avaliada, a saída que ela protege continua retida e uma pessoa decide.

O que não libera um hold: a passagem do tempo, a flag simplesmente sumir de um snapshot posterior, uma liberação em outro escopo, uma autoridade inferior, o reinício do executor ou a liberação de outra flag. Liberar um hold nunca é uma instrução para liberar o asset.

Validação

A biblioteca verifica a si mesma

Cinco scripts vêm com a biblioteca, e cada um faz uma pergunta diferente — inclusive se os documentos concordam com os arquivos que descrevem.

cd som/skills
python3 scripts/validate_som_skill.py skills/<name>.md   # one skill file is legal
python3 scripts/check_library.py skills/                  # the library holds together
python3 scripts/check_paths.py skills/                    # every path resolves against
                                                          #   ../schema/story-context.schema.json
python3 scripts/build_lookup_table.py . --check           # the table matches the adverts
python3 scripts/check_cover_claims.py .                   # the docs match the files

Uma lacuna é declarada em vez de escondida: check_paths.py resolve apenas caminhos literais. Um valor {{ config.* }} é desconhecido até que a casa o configure, então pegar um caminho configurado errado é trabalho da casa no momento do registro.

Em aberto, com franqueza

O que a biblioteca não pretende resolver

Como a autoridade é comparada. “Liberado por autoridade igual ou superior no mesmo escopo” é a posição de trabalho da biblioteca, com a ordem fornecida por cada casa como authority_scale. Nenhum grupo a ratificou.
Quem transforma um aviso levantado em estado de gate. Uma skill de levantamento só publica um aviso; uma skill de hold lê editorial_gates[]. O que materializa um no outro ainda não está definido.
Correspondência de tags qualificada por esquema. Hoje as skills comparam tags[].value independentemente do esquema; se devem casar com newsroom:sport em vez de sport está em aberto.
Configuração da demo. As instâncias configuradas usadas no passo a passo da IBC nomeiam fornecedores específicos e não estão publicadas na 1.0, até que cada fornecedor dê o aval.

A seguir: valide e publique sua primeira mensagem →