Criação de Skills

Usado para criar ou manter os skills oficiais do AgentDock. O skill em si é um documento de instruções legível pelo modelo; as ferramentas são responsáveis pela verificação real, edição, execução de comandos, empacotamento, instalação e validação.

Um skill alvo deve ser composto por duas partes:

Contrato portável principal
+
Instruções opcionais de adaptação ao host

Após remover as instruções de adaptação específicas do AgentDock, o fluxo de trabalho do skill, as referências dentro do pacote, o contrato de variáveis de ambiente e os scripts auxiliares devem permanecer totalmente funcionais.

Quando usar

Use este skill para lidar com:

Criação de novos skills oficiais;
Modificação, refatoração ou atualização de skills existentes;
Ajuste de descrições de gatilho, fluxo do corpo, materiais de referência ou scripts auxiliares;
Adição de testes, exemplos, restrições de segurança e verificações de portabilidade;
Incremento de versão e conclusão da verificação entre o lado do código-fonte e a versão atualmente ativada.

Não use este skill para revisões formais de segurança de skills de terceiros, configuração de credenciais reais ou reversão de versões instaladas. Isso é de responsabilidade do skill-installation.

Princípios fundamentais

Defina primeiro quando o modelo deve selecionar este skill, depois escreva o corpo.
O skill descreve apenas métodos, limites e escolhas de ferramentas; não assume a responsabilidade de execução uniforme.
O contrato principal do skill deve ser independente do host; use caminhos relativos para arquivos dentro do pacote; o ambiente é injetado pelo host de execução.
Skills simples devem ter apenas um arquivo SKILL.md; adicione referências, scripts ou testes somente quando realmente necessário.
Após modificar o corpo, referências, scripts ou comportamento, a versão semântica deve ser incrementada.
Conteúdo com o mesmo nome e versão deve permanecer imutável.
Valores de ambiente, estado do dispositivo e dados de execução não devem entrar no pacote do skill.
Todas as validações devem recair sobre a versão atualmente instalada e ativada, não apenas no diretório de código-fonte.
Skills oficiais devem passar pelo lint deste skill, não apenas pela validação de instalação do pacote.

Especificação completa no arquivo references/skill-package-spec.md dentro do pacote.

Fluxo padrão

1. Entender os requisitos e condições de gatilho

Primeiro, esclareça:

O problema real que o usuário precisa resolver;
Em quais solicitações o modelo deve selecionar este skill;
Quais tarefas adjacentes não pertencem a este skill;
Quais ferramentas reais precisam ser chamadas;
Se são necessários scripts auxiliares, materiais de referência ou testes;
Se envolve rede, gravação, exclusão, credenciais ou ações de alto risco.

Não use descrições vagas como "gerenciar todo o ciclo de vida de uma capacidade". A description deve permitir que o modelo julgue de forma estável quando selecioná-lo.

2. Determinar o escopo de responsabilidades

O corpo deve pelo menos explicar:

Cenários aplicáveis e não aplicáveis;
Objetos lidos ou modificados;
Comportamento padrão somente leitura;
Regras de confirmação para operações de gravação e destrutivas;
Evidências a serem retornadas em caso de falha.

Um skill deve ser organizado em torno de um limite de capacidade estável. Quando os requisitos já cruzam responsabilidades independentes, devem ser divididos em vários skills.

3. Criar o diretório de código-fonte

Skills oficiais e da comunidade geralmente são colocados em um repositório agentdock-skills separado:

skills/<skill-name>/

Apenas os skills principais que são autoinicializados com o pacote de instalação do AgentDock e fortemente vinculados à versão do runtime são colocados no repositório principal do AgentDock:

core-skills/<skill-name>/

Escolha a estrutura conforme necessário:

skills/<skill-name>/
└── SKILL.md

skills/<skill-name>/
├── SKILL.md
├── references/
├── scripts/
└── tests/

skills/<skill-name>/
├── SKILL.md
├── run.py
└── tests/

Não crie diretórios vazios por formalidade, nem coloque integrações comuns de volta no repositório principal do AgentDock.

4. Escrever o Frontmatter

Atualmente, o AgentDock analisa formalmente:

---
name: example-skill
description: Explica claramente quando usar e qual problema resolver
version: 1.0.0
---

Requisitos:

name use um nome estável, curto, em minúsculas e com hífen;
description cubra tanto o cenário de gatilho quanto os limites de capacidade;
version use versionamento semântico;
Após o frontmatter, deve haver um corpo Markdown não vazio;
Não adicione campos de variáveis de ambiente ou execução não suportados pelo analisador atual.

5. Escrever o núcleo portável

O corpo e os scripts do skill alvo, por padrão, assumem apenas:

O diretório de trabalho atual é a raiz do pacote do skill;
Os recursos dentro do pacote podem ser acessados por caminhos relativos;
As variáveis de ambiente vêm do processo atual;
O host de execução é responsável por escolher ferramentas, mudar de diretório e injetar ambiente;
Não depende do diretório de instalação, diretório de estado ou variáveis exclusivas do AgentDock.

Quando houver scripts na raiz, um exemplo de execução genérica deve ser escrito como:

printf '%s' '{"skill_action":"status"}' | python3 run.py

Não devem ser usados como pré-requisitos de execução principal:

~/.agentdock/skill-store/installed/...;
Número de versão de instalação fixa;
AGENTDOCK_DIR, AGENTDOCK_HOME ou AGENTDOCK_SKILL_DIR para localizar scripts ou dados privados dentro do pacote;
skill_env, exec_command ou skill://;
Caminhos absolutos fixos do usuário;
Leitura ativa ou source de arquivos de ambiente privados do AgentDock.

Chamadas de ferramentas do AgentDock podem aparecer em uma seção separada "Adaptação/Validação AgentDock", mas após remover essa seção, o skill ainda deve estar utilizável.

6. Declarar variáveis de ambiente

Cada skill alvo que precisa de configuração deve declarar explicitamente as variáveis no corpo:

## Variáveis de ambiente

| Variável | Tipo | Obrigatório | Descrição |
|---|---:|---|
| EXAMPLE_BASE_URL | config | Sim | Endereço do serviço |
| EXAMPLE_API_KEY | secret | Sim | Chave da API |

O tipo deve distinguir pelo menos config e secret, e explicar quais capacidades ficam indisponíveis quando a variável está faltando.

O skill alvo declara apenas o nome e a finalidade da variável, não o caminho de armazenamento privado do AgentDock, e não armazena valores reais. Scripts auxiliares leem variáveis apenas do ambiente do processo atual.

Na validação local do AgentDock, os valores de ambiente são gerenciados por skill_package env_set/env_unset/env_list e injetados no subprocesso pelo contexto skill do exec_command. O ambiente não é escrito no processo principal do AgentDock ou no ambiente do sistema.

7. Escrever materiais de referência

Conteúdo adequado para references/ inclui:

Descrições de protocolos estáveis;
Listas de verificação mais longas;
Tabelas de campos de API ou códigos de erro;
Materiais de fundo que não precisam ser carregados completamente a cada vez.

O SKILL.md alvo usa caminhos relativos dentro do pacote, por exemplo:

references/api.md

Não use skill://<name>/... como contrato de referência principal, nem dependa do diretório de instalação de outro skill. O AgentDock pode ler recursos através de read_file skill://<name>/... ao validar o pacote atualmente ativado.

8. Escrever scripts auxiliares

Scripts auxiliares são apenas recursos opcionais, não o skill em si. Quando for necessário um script:

A entrada usa um objeto JSON no stdin;
O campo de ação de nível superior usa uniformemente skill_action;
As chaves são lidas apenas do ambiente do processo atual;
Não passe segredos como argumentos de linha de comando;
A saída deve ser JSON estruturado;
Erros retornam um code estável e um message legível;
Verificações de estado priorizam somente leitura;
Operações de gravação seguem as regras de confirmação do usuário;
Logs e erros não devem exibir segredos;
Arquivos dentro do pacote usam caminhos relativos ou são localizados com base no diretório do próprio script.

Entrada recomendada:

{
  "skill_action": "status"
}

Execução genérica na raiz do pacote do skill:

python3 run.py

Na validação do AgentDock, use exec_command com skill: "<skill-name>" para vincular o diretório atualmente ativado com o ambiente independente, sem analisar manualmente o diretório de versão.

9. Executar lint de portabilidade

O run.py deste skill fornece:

status: relata a versão do lint e o número de regras;
lint: verifica problemas de portabilidade principal e vinculação ao host no skill alvo.

Exemplo de entrada:

{
  "skill_action": "lint",
  "source": "/path/to/agentdock-skills/skills/example-skill"
}

O resultado inclui:

portable;
error_count;
warning_count;
Para cada problema: code, severity, arquivo, número da linha, descrição e sugestão de correção.

Caminhos de diretório de versão instalada codificados, dependência de variáveis de diretório exclusivas do AgentDock, leitura ativa de arquivos de ambiente do AgentDock e caminhos absolutos fixos do usuário são erros. Ferramentas ou URIs exclusivos do AgentDock aparecendo no SKILL.md alvo são avisos, e é necessário confirmar que eles existem apenas em instruções de adaptação opcionais.

Ao executar o lint em um diretório instalado, o arquivo .agentdock-install.json gerado pelo instalador do AgentDock na raiz do pacote é ignorado. Este arquivo é um comprovante de instalação do host, não conteúdo do pacote do skill; arquivos com o mesmo nome em outros diretórios dentro do pacote ainda serão escaneados normalmente.

No AgentDock, após instalar uma nova versão do skill-authoring, pode ser executado assim:

exec_command
  skill: skill-authoring
  cmd: python3 run.py
  stdin: {"skill_action":"lint","source":"/path/to/source"}

Ao criar ou modificar um skill oficial, portable deve ser true; os avisos devem ser corrigidos um a um ou explicados por que pertencem à adaptação opcional do host.

10. Escrever testes

Os testes cobrem riscos reais e, no mínimo, consideram:

Frontmatter e corpo são analisáveis;
Falha clara quando a entrada não é um objeto JSON;
Falha clara para skill_action desconhecido;
Quando faltam variáveis de ambiente, apenas o nome da variável é relatado, sem vazar o valor;
Verificações de estado somente leitura não produzem gravação;
Ações destrutivas sem confirmação são rejeitadas;
Logs e erros não contêm segredos;
Quando plataforma ou dependência está faltando, retorna informação diagnosticável;
O pacote é executado a partir da raiz usando comandos relativos;
O script não depende de diretórios privados do AgentDock.

11. Verificações de segurança e qualidade

Antes de enviar, verifique:

Nenhuma senha, token, cookie, cache de autenticação ou arquivo de sessão real dentro do pacote;
Nenhum .env, cache, banco de dados, captura de tela, arquivo baixado ou resultado de execução;
Nenhum __pycache__, *.pyc, node_modules ou artefatos de compilação;
Nenhum caminho absoluto fixo do usuário, link simbólico ou path escape;
Nenhum exemplo de protocolo de execução unificado antigo, exemplo de ferramenta de ambiente antiga ou lista antiga;
Destinos de rede, gravação de arquivos, exclusão, upload e alterações de permissão são explicitamente explicados;
A instalação de dependências não será executada ocultamente.

Proibido gerar ou restaurar:

agentdock.yaml;
skill_run;
skill_env_manage;
AGENTDOCK_OPERATION;
Protocolo antigo PLUGIN_*;
Listas antigas operation ou entrypoint;
Executor de skill unificado ou Skill Runtime antigo.

Estado privado do dispositivo e valores de ambiente do AgentDock pertencem apenas ao host, não entram no pacote.

12. Incrementar versão

Apenas corrigir erros de digitação no texto que não afetam o julgamento de comportamento: pode incrementar a versão de patch;
Adicionar capacidades compatíveis, variáveis, ações ou referências: incrementa a versão menor;
Mudar o escopo de responsabilidade, remover capacidades existentes ou introduzir fluxo incompatível: incrementa a versão principal.

Antes de instalar, compare a versão atualmente instalada com o novo código-fonte. Não substitua conteúdo diferente com a mesma versão.

13. Validação e instalação local

Pelo menos conclua:

Verificar diretório e Frontmatter;
Verificar se a versão foi incrementada corretamente;
Verificar arquivos proibidos, links simbólicos e secrets reais;
Executar verificação de sintaxe e testes próprios nos scripts auxiliares;
Executar skill-authoring lint, confirmar portable=true e revisar avisos;
Usar skill_package validate para validar a legalidade do pacote;
Usar skill_package install para instalar e ativar;
Através de agentdock_context, verificar se nome e descrição entram no índice leve;
Através de read_file skill://<name>/SKILL.md, verificar o corpo atualmente ativado;
Se houver referências, ler pelo menos uma referência;
Se houver scripts auxiliares, executar status somente leitura com exec_command skill=<name> na versão atualmente ativada;
Executar uma ação representativa de baixo risco; se não for possível, registrar o motivo real.

skill_package validate é responsável por determinar se o pacote pode ser legalmente instalado; o lint deste skill é responsável pela qualidade de criação oficial e portabilidade; eles não podem substituir um ao outro.

Variáveis de ambiente

Este skill em si não requer variáveis de ambiente. Ele exige que o skill alvo a ser escrito declare variáveis de negócio, e que o host de execução as injete no subprocesso atual.

Critérios de conclusão

A tarefa é considerada concluída apenas quando todas as seguintes condições são atendidas:

A descrição pode ser acionada de forma estável e os limites são claros;
O núcleo portável não depende de diretórios privados do AgentDock ou parâmetros de ferramenta;
Scripts dentro do pacote podem ser executados a partir da raiz do skill usando caminhos relativos;
skill-authoring lint retorna portable=true, e os avisos foram tratados um a um;
Verificações de segurança, testes e skill_package validate passam;
A nova versão foi instalada e ativada;
agentdock_context e skill:// leem a nova versão;
A verificação real de somente leitura da versão atualmente ativada passa;
Nenhum segredo, estado privado do dispositivo ou arquitetura antiga retornou.

uvwt/agentdock

O que é agentdock?

Perguntar na sua IA favorita

Documentação