Versão 1.0.0-alpha.1mais recente
Capítulo 2.20
Competências
Como escrever, testar e publicar uma competência do Skills Engine, onde aparece assim que está ativa e como diferem as competências de manifesto num plugin. Inclui um exemplo prático de resumo de atribuição de cais para a Harrow Port Authority.
Esta página foi traduzida por IA a partir do original em inglês. Em caso de dúvida, a página em inglês serve de referência. Ler esta página em inglês

Tomás Reilly, o engenheiro de plataforma na Harrow Port Authority, perguntou-me no mês passado porque é que os seus planeadores de cais recebiam uma resposta diferente sempre que perguntavam ao assistente «quem está em que cais amanhã e o que mudou?». A resposta era que ninguém tinha dito ao assistente como deveria ser uma boa resposta. Uma competência do Skills Engine resolveu o problema numa tarde: os planeadores recebem agora sempre o mesmo resumo em três partes, com a tabela de cais em primeiro lugar, as alterações desde o último plano por baixo e os conflitos em último. Este capítulo percorre essa competência de ponta a ponta e, em seguida, aborda o outro tipo de competência, aquela que reside no manifesto de um plugin.
Dois tipos de competência
O Nexus utiliza a palavra «competência» (skill) para duas coisas diferentes, e estas são construídas de forma diferente.
| Competência do Skills Engine | Competência de manifesto | |
|---|---|---|
| O que é | Um pacote SKILL.md na biblioteca de competências |
Uma linha tipada na matriz skills[] de um plugin |
| Quem a escreve | Qualquer pessoa com permissão, no criador ou no seu próprio editor | Um programador, dentro de um plugin |
| O que contém | Instruções, as ferramentas que pode invocar, ficheiros e scripts opcionais | Um esquema de entrada e saída, um nível (tier) e os campos de que esse nível necessita |
| Como chega à plataforma | Validada, carregada e publicada no Skills Engine | Compilada a partir do manifesto e sincronizada com o registo de competências |
| O que a executa | O assistente, agentes, fluxos de trabalho, botões de IA (inteligência artificial), Claude Code | Despacho do UNO (o motor de fluxos de trabalho) |
| Utilização típica | «Resumir o plano de cais sempre da mesma forma» | «Executar o nosso propagador de órbita nesta passagem» |
O resto do capítulo mantém-nas separadas. Se um parágrafo disser apenas «competência», trata-se de uma competência do Skills Engine.
Parte 1: competências do Skills Engine
O que é uma competência
Uma competência é uma pasta. O seu SKILL.md indica para que serve a competência e como realizar a tarefa; ao seu lado encontram-se quaisquer ficheiros de que a tarefa necessite e quaisquer scripts que execute. O motor carrega uma competência em três camadas: o nome e a descrição sempre, as instruções quando uma tarefa requer a competência e os ficheiros apenas quando um passo necessita deles. É por isso que uma instalação pode conter duzentas competências e não ter quase nenhum custo por elas até que uma seja utilizada.
skills/<slug>/
├── SKILL.md # required: YAML frontmatter, then the instructions
├── skill.yaml # optional: engine metadata (triggers, aliases, tags, capabilities)
└── scripts/ # optional: bundled with the skill as components
O nome do diretório deve ser igual ao slug da competência. Uma divergência gera um aviso de validação, que vale a pena corrigir, porque o slug é a forma como a biblioteca faz corresponder um carregamento a uma competência existente.
Frontmatter do SKILL.md
O frontmatter é código YAML entre duas linhas --- no topo do ficheiro. O formato requer três campos. A validação em si bloqueia apenas em alguns casos: um nome ou descrição em falta e um slug ou tipo de tarefa que já esteja a ser utilizado. Tudo o resto é comunicado como um aviso.
| Campo | Tipo | Obrigatório | O que contém |
|---|---|---|---|
name |
string | sim | O identificador único, em kebab-case |
description |
string | sim | O que a competência faz, no máximo com 500 caracteres. A biblioteca e o mecanismo de correspondência leem-na, por isso escreva-a para um leitor que esteja a decidir se esta é a competência certa |
allowed-tools |
string ou lista | sim | As ferramentas que a competência pode invocar. Apenas pode restringir a lista de permissões de quem a executa |
triggers |
lista | não | Comandos de barra (slash commands) que invocam a competência diretamente |
capabilities |
lista | não | Capacidades estruturadas, cada uma com um name, um description e, opcionalmente, input_schema, output_schema e examples |
version |
string | não | Uma versão semântica; 1.0.0 quando omitida |
visibility |
string | não | private, team ou public |
status |
string | não | draft, testing ou published |
Mantenha as instruções abaixo de cerca de 5000 tokens. Seja específico e dê exemplos. Cada competência deve fazer bem uma única tarefa; se der por si a escrever «e também», provavelmente tem duas competências.
skill.yaml
O skill.yaml contém o que o motor necessita para a descoberta e para a biblioteca, para que o SKILL.md permaneça legível. Os campos que o motor lê incluem name, display_name, description, version, status, visibility, triggers, aliases, category, tags, allowed_tools e capabilities. Uma capacidade pode conter query_patterns, as formulações que o mecanismo de correspondência lhe deve enviar. Existem também indicações para a orçamentação do próprio motor: complexity, estimated_tokens e required_services.
scripts/
Qualquer elemento sob scripts/ é agrupado literalmente com a competência como um componente. Um script é executado, nunca lido para o contexto do modelo, e é executado numa sandbox. Utilize um quando um passo envolver aritmética ou análise sintática (parsing) que um modelo não deva fazer de cabeça.
Visibilidade e estado
A visibilidade indica quem pode encontrar a competência: private é o utilizador, team é a sua equipa e public são todas as pessoas na organização servida pela biblioteca. Na consola, a mesma escolha aparece como «Apenas eu», uma equipa como «Balcão aduaneiro» ou toda a organização, e uma competência também pode ser partilhada num pacote de domínio através da revisão própria desse pacote.
O estado indica em que fase do ciclo de vida se encontra a competência.
| Estado | Significado |
|---|---|
draft |
Trabalho em curso; não pesquisável |
testing |
Em validação, com acesso limitado |
published |
Disponível para utilização geral |
deprecated |
Substituída; em vias de descontinuação |
Uma vez publicada uma versão, esta nunca muda. Na consola, «live», «canary» e «shadow» são etiquetas aplicadas às versões, e voltar a uma versão anterior move uma etiqueta. As execuções em curso terminam na versão com que começaram.
SKILL.md, os ficheiros ao seu lado e quando cada um é carregado, bem como as ferramentas que a competência pode invocar. A uma competência de verificação não é oferecida nenhuma ferramenta de escrita, e uma competência apenas pode restringir a lista de permissões de quem a executa.De uma pasta para uma competência ativa
Cinco scripts npm no repositório do Skills Engine levam uma competência do seu editor para a biblioteca e comprovam que lá chegou.
| Comando | O que faz |
|---|---|
npm run skill:validate skills/<slug> |
Analisa (lints) o pacote. A publicação requer zero erros |
npm run skill:upload skills/<slug> |
Valida e publica num único passo; idempotente |
npm run skill:upload skills/<slug> --dry-run |
Valida e imprime o plano sem escrever nada |
npm run skill:publish -- --dry-run skills/<slug> |
A publicação de nível inferior subjacente ao carregamento, o mesmo pipeline |
npm run skill:reconcile |
Compara as competências no seu repositório com o que consta na biblioteca e no registo de competências |
npm run skill:live:verify |
Verifica uma competência publicada de ponta a ponta na instalação em execução |
A publicação escreve duas entradas, e ambas são importantes. Uma é a própria competência, com o seu corpo SKILL.md, capacidades, componentes e registo de qualidade; a biblioteca, a descoberta e a correspondência leem essa entrada. A outra é a entrada de registo contra a qual o motor de fluxos de trabalho resolve um despacho. Uma competência que apenas tenha chegado ao registo é executada, mas fica invisível na biblioteca até que a carregue.
A publicação é idempotente. Uma competência inalterada resulta numa não-operação (no-op), e uma competência existente é associada pelo seu slug e atualizada no local, nunca recriada. Se carregar os mesmos bytes de uma versão que já foi publicada, recebe essa versão de volta com CONTENT_HASH_ALREADY_PUBLISHED, e não um duplicado.
O skill:reconcile percorre as competências do seu repositório comparando-as com a biblioteca, o registo e o inventário do motor de fluxos de trabalho, e comunica tudo o que exista num local e não noutro. O skill:live:verify vai mais longe na instalação em execução: ambas as entradas existem e apontam uma para a outra com o mesmo hash de conteúdo, um despacho de simulação (dry-run) do tipo de tarefa da competência é aceite, a competência aparece na lista e nos detalhes da biblioteca, pode ser invocada e o registo de auditoria interliga a publicação, o despacho e a execução através do slug e do ID do pedido.
A partir de uma estação de trabalho, o carregamento chega ao serviço de conhecimento da instalação, nexus-graphrag, através de um encaminhamento de portas (port-forward), e necessita da chave de serviço do Skills Engine no ambiente. Carregue a chave sem a exibir no ecrã:
kubectl -n nexus port-forward svc/nexus-graphrag 8090:8090
read -rs GRAPHRAG_SKILLS_ENGINE_SERVICE_KEY
export GRAPHRAG_SKILLS_ENGINE_SERVICE_KEY
GRAPHRAG_URL=http://localhost:8090 npm run skill:upload skills/berth-allocation-summaryDentro do cluster, numa tarefa de pipeline, o endereço predefinido é resolvido por si só e GRAPHRAG_URL não é necessário. Obtenha a chave através do processo de segredos da sua própria organização. Esta nunca deve constar no repositório, no histórico da sua shell ou na saída de um comando.
Testes, aprovação e entrada em produção
Uma competência chega à biblioteca como rascunho, e o criador retém-na aí até que três etapas sejam concluídas com êxito.
| Verificação | O que faz |
|---|---|
| Casos de teste | Todos os casos têm de passar antes de a competência poder seguir para aprovação. Um caso só pode ser removido mediante uma justificação, que fica visível para os aprovadores. |
| Uma execução simulada em modo sombra (shadow) | A competência é executada sobre trabalho passado, onde ninguém vê as respostas, e os seus resultados são comparados com o que uma pessoa decidiu na altura. |
| Uma revisão cega por um modelo de outra família | Procura uma verificação falhada, uma fonte inventada e uma instrução infiltrada que a competência tenha seguido quando não o deveria ter feito. |
Depois, a aprovação. Uma competência que adicione uma ferramenta de escrita fica retida até que duas pessoas a aprovem com as suas chaves de acesso (passkeys), e a pessoa que a propôs não pode ser uma delas (PUBLISH_NEEDS_APPROVAL). Em seguida, entra em produção em modo sombra (shadow), depois em modo canário (canary) para uma unidade protegida por critérios de controlo (gates) designados e, por fim, para todos. Se um critério de controlo canário não for cumprido, o modo canário interrompe-se a si mesmo e todos permanecem na versão anterior; enviá-la para todos antecipadamente requer uma justificação e um segundo aprovador (CANARY_GATE_NOT_MET).
Na versão Community, o criador, a biblioteca, as versões e os testes estão todos presentes, e o proprietário publica sozinho assim que os testes passam. O modo canário, a aprovação por duas pessoas, a sincronização de plugins e a fusão de duplicados estão incluídos na versão Enterprise.
Onde aparecem as competências
A mesma competência publicada chega às pessoas em cinco locais.
- O assistente faz corresponder um pedido a uma competência através da sua descrição, acionadores e padrões de consulta, e segue as instruções da competência.
- Agentes e fluxos de trabalho invocam competências como passos. Um passo do fluxo de trabalho indica o nome da competência; a execução regista qual a versão utilizada.
- Botões de IA nos ecrãs executam, cada um, uma competência. Um administrador pode abrir «Acerca deste botão» para ver a competência que um botão executa, o que lê e quem a alterou pela última vez, e pode desativar o botão sem tocar na competência.
- O seu IDE (ambiente de desenvolvimento integrado) e o Claude Code acedem à biblioteca através do Workbench e de treze ferramentas MCP (Model Context Protocol):
list_skills,get_skill,match_prompt,discover_skills,invoke_skill,record_execution,create_skill,import_skill,get_generation_jobesync_skills_local, entre elas. Cada chamada é executada em nome da pessoa que a iniciou, dentro da sua lista de permissões. - A própria biblioteca de competências, onde as pessoas procuram, executam e sugerem alterações às competências, e os administradores veem o proprietário, os utilizadores, as execuções e os gastos de cada competência.
Independentemente do que executar uma competência, esta não pode alargar o que o executante tem permissão para fazer: invoca apenas ferramentas dentro da lista de permissões do executante e lê apenas o que essa pessoa tem permissão para abrir (SKILL_CANNOT_WIDEN_TOOLS). Uma execução sem uma rota de modelo é recusada em vez de ser adivinhada (SKILLS_ENGINE_BINDING_MISSING); o despachante escolhe a rota a partir da configuração de modelos da própria organização.
Exemplo prático: um resumo de atribuição de cais para a Harrow
Os planeadores da Harrow já tinham duas ferramentas só de leitura na sua lista de permissões a partir do próprio plugin de planeamento de cais da Harrow: berth-plan.read devolve o plano para uma data e vessel-call.read devolve uma escala de navio com a sua janela de chegada e comprimento. A competência não necessita de mais nada. Nunca escreve dados, pelo que nunca necessita de dois aprovadores.
---
name: berth-allocation-summary
description: Summarise tomorrow's berth plan at Harrow for the planning desk. Use when someone asks who is on which berth, what moved since the last plan, or where two calls clash.
allowed-tools: berth-plan.read, vessel-call.read
triggers:
- /berth-summary
capabilities:
- name: summarise_berth_plan
description: The berth table, the changes since the last plan and any clashes, for one date
version: 1.0.0
visibility: team
status: draft
---
# Berth allocation summary
## When to use
A planner asks about the berth plan for a date, or asks what changed.
## Steps
1. Read the plan for the date with berth-plan.read. If no date is given, use tomorrow.
2. For each call on the plan, read it with vessel-call.read.
3. Write the berth table first: berth, vessel, arrival window, length overall.
4. Then list what moved since the previous plan, one line per change, with the reason the plan records.
5. Then list clashes: two calls whose windows overlap on one berth, or a vessel longer than the berth.
6. Cite the plan's version for every line. Never guess a time the plan doesn't give.
## Output
Three headed sections, in this order: Berths, Changes, Clashes. Write "No clashes" when there are none.O skill.yaml ao seu lado fornece à biblioteca um nome de apresentação, uma categoria e as formulações que o mecanismo de correspondência deve encaminhar para aqui:
# skill.yaml, beside SKILL.md
name: berth-allocation-summary
display_name: "Berth allocation summary"
version: "1.0.0"
status: draft
visibility: team
category: operations
tags:
- berths
- planning
triggers:
- "/berth-summary"
allowed_tools:
- berth-plan.read
- vessel-call.read
capabilities:
- name: "summarise_berth_plan"
description: "Berth table, changes since the last plan and clashes, for one date"
query_patterns:
- "who is on which berth tomorrow"
- "what moved on the berth plan"
- "any berth clashes on *"Em seguida, os comandos, a partir da raiz do repositório:
npm run skill:validate skills/berth-allocation-summary
npm run skill:upload skills/berth-allocation-summary --dry-run
npm run skill:upload skills/berth-allocation-summaryO Tomás adicionou seis casos de teste no criador: um dia normal, um dia com uma chegada atrasada que moveu duas escalas, um dia com um conflito genuíno, uma data ainda sem plano, um navio demasiado comprido para o seu cais e um pedido que tentava fazer com que a competência propusesse um novo cais (não o deve fazer; não tem nenhuma ferramenta de escrita). A execução simulada reproduziu vinte planos passados em modo sombra. Assim que os casos passaram, um revisor no balcão de planeamento aprovou-a, e esta entrou em produção para a equipa de planeamento. O assistente responde agora à pergunta sempre com o mesmo formato, e o botão de IA dos planeadores na página do plano de cais executa a mesma competência.
Parte 2: competências de manifesto
Uma competência de manifesto é a unidade de computação que um plugin publica. É declarada em skills[] do manifesto, validada pelo SDK (kit de desenvolvimento de software) quando executa create-nexus-plugin validate, compilada no corpo do registo por compileRegistry e sincronizada com o registo de competências. Nunca escreve SQL de registo manualmente, pelo que a linha que a plataforma despacha e o descritor que declarou não podem divergir.
Cada competência de manifesto necessita de id, displayName, description, tier, classification, inputSchema e outputSchema. Declare também timeoutMs: é um número inteiro de 1,000 a 21,600,000 (um segundo a seis horas), e um valor fora desse intervalo é recusado com TIMEOUT_OUT_OF_BOUNDS. dataResidency é any, eu ou us, sendo any a predefinição.
O id está em formato lower_snake, e a chave de despacho do registo é o tipo de tarefa com espaço de nomes (namespaced) <plugin name>.<skill id>, pelo que dois plugins podem ter ambos uma competência summarise sem entrarem em conflito. Eis a única competência do modelo, resumida:
{
"id": "sentiment_score",
"displayName": "Sentiment score",
"description": "Deterministic lexicon-based sentiment score for a piece of text.",
"tier": "host_callback",
"classification": "tenant",
"dataResidency": "any",
"inputSchema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1 } }, "required": ["text"] },
"outputSchema": { "type": "object", "properties": { "score": { "type": "number" } }, "required": ["score"] },
"hostCallback": {
"service": "my-plugin",
"port": 8080,
"path": "/internal/skills/sentiment_score",
"maxRequestBytes": 262144,
"maxResponseBytes": 16384,
"tenantHeader": "X-Organization-ID"
},
"timeoutMs": 10000
}Os cinco níveis
O nível (tier) não é uma etiqueta. Cada nível tem os seus próprios campos, e um campo que pertença a outro nível é recusado com FIELD_NOT_FOR_TIER em vez de ser silenciosamente ignorado.
| Nível | Requer | Acede a um modelo | Quem a executa |
|---|---|---|---|
host_callback |
hostCallback: o seu Service, a respetiva porta, um caminho e ambos os limites de bytes |
Não | A plataforma envia (POST) os dados de entrada para o seu próprio Service, dentro do seu espaço de nomes |
plugin_queue |
queueName, escrito <plugin name>.<name> |
Não | O seu worker, extraindo da sua fila |
tool_using |
systemPrompt e tools[]; confiança core ou verified |
Sim | A plataforma, através do AI Provider Router; cada chamada de ferramenta é executada através de um executor na lista de permissões |
llm_only |
systemPrompt; confiança core ou verified |
Sim | A plataforma, uma chamada através do AI Provider Router |
map |
map.perItemJobType, indicando o nome de outra competência do mesmo manifesto que não seja um mapa |
Apenas através do seu destino | A plataforma executa o destino uma vez por item e reúne os resultados |
Nenhum dos níveis de modelo indica o nome de um fornecedor ou de um modelo. O router escolhe ambos a partir do conjunto de recursos (pool) da própria organização despachante. Uma ferramenta numa competência tool_using indica o nome de um de seis executores: standing_service_call (o seu próprio Service), graphrag, graphrag_query, graphrag_search, h3 ou web_search. Qualquer outro é recusado com EXECUTOR_NOT_PERMITTED. Os três executores de grafo de conhecimento aceitam apenas os nomes de ferramentas graphrag_query e graphrag_search, porque o executor executa qualquer operação correspondente ao nome da ferramenta.
Existem dois níveis no registo que um plugin não pode declarar: cadeias e competências que são executadas de forma autónoma são escritas apenas pela plataforma. Uma sincronização que indique o nome de uma delas é recusada na totalidade.
Que nível utilizar
host_callbackquando o trabalho é uma função dos dados de entrada que o seu próprio código calcula: uma pontuação, um cálculo, uma pesquisa no seu próprio esquema. É o mais simples de testar e a predefinição do modelo. Proteja a rota de callback: um caminho num manifesto não é um segredo, e a rota tem de verificar a chamada da plataforma e obter a organização a partir dela, nunca a partir do corpo. Declare-aauth: internale monterequireService(Fastify) ouserviceMiddleware(Express) na mesma. A proteção recusa um token emitido para qualquer outra entidade. Responda rapidamente e torne inofensiva uma segunda entrega da mesma tarefa.plugin_queuepara trabalhos mais demorados pelos quais uma pessoa aguarda, em que o seu worker detém o controlo do ciclo de vida. O worker tem de mover a execução pararunningquando inicia e para um estado terminal quando termina; um worker que apenas publique o seu resultado deixa a execução a mostrarqueuedindefinidamente.llm_onlyquando uma chamada de modelo com um prompt de sistema fixo realiza a tarefa, e o seu plugin écoreouverified.tool_usingquando o modelo necessita de invocar ferramentas num ciclo (loop), novamente apenas emcoreouverified.mapquando pretende que a plataforma distribua (fan out) uma das suas outras competências por uma lista.
A minha competência de propagação de órbita na Corrán Orbital é uma host_callback. O nosso plugin é community, pelo que os níveis de modelo nunca foram uma opção, e não sinto a falta deles: um propagador que desse uma resposta diferente na terça-feira seria pior do que inútil.
Aprovação antes de cada execução
Uma competência de manifesto que nunca deva ser executada apenas por decisão de uma máquina declara-o:
"approval": { "required": true, "reason": "Re-planning a pass needs the flight dynamics lead." }required é sempre true; uma competência que não necessite de aprovação omite o bloco. reason é o que o aprovador vê, de 1 a 500 caracteres após a remoção de espaços nas extremidades (trimming), e qualquer outro formato é recusado com APPROVAL_INVALID. Um despacho da competência fica então retido: o despacho responde 202 com status: "awaiting_approval" e um waitpointId, e apenas a aprovação de uma pessoa designada o liberta, uma única vez. Um despacho em lote (batch), mapa (map) ou cadeia (chain) de uma competência retida é recusado com SKILL_APPROVAL_NOT_HOLDABLE, porque uma distribuição (fan-out) não pode reter os seus itens. Apresente a resposta retida e deixe o aprovador decidir; não despache para depois pedir consentimento.
Sincronizar com o registo
Cada sincronização é declarativa e verificada na sua totalidade. Envie sempre o conjunto completo de competências: uma competência que omita é desativada, e o seu histórico de execuções permanece. Uma única competência incorreta recusa toda a sincronização com SYNC_CONTRACT_VIOLATION, listando todas as violações em conjunto e sem escrever nada, para que um plugin nunca fique apenas meio atualizado. O Capítulo 2.22, O tempo de execução do plugin, aborda a chamada de sincronização e a forma como a plataforma sabe qual é o plugin que está a fazer a chamada.
Escolher entre os dois tipos
Se a tarefa for «dizer isto sempre da mesma forma», trata-se de uma competência do Skills Engine. Se a tarefa for «executar o meu código e dar-me a sua resposta», trata-se de uma competência de manifesto. A maioria do trabalho real acaba por ser ambos: o resumo de cais da Harrow é uma competência do Skills Engine cujas ferramentas provêm de um plugin, e as ferramentas do plugin são, elas próprias, declaradas no seu manifesto. A competência do Skills Engine é a mais económica das duas para alterar, o que é uma boa razão para manter aí a redação e o discernimento, e a aritmética no plugin.
O custo é real de qualquer das formas. Uma competência do Skills Engine não está concluída quando o SKILL.md parece bem redigido; está concluída quando os seus casos passam, a sua execução simulada concorda com o que as pessoas decidiram e alguém que não seja o próprio autor a tiver aprovado. Reserve uma semana no orçamento para uma competência de escrita, sendo a maior parte desse tempo dedicada ao modo canário.



