rundesk-ai/rundesk-cli

Criando habilidades

Reutilize o repositório existente

Inspecione os catálogos de habilidades existentes antes de criar um pacote. Para trabalhos em repositórios, pesquise no catálogo de destino e em todos os catálogos de origem relevantes no workspace autorizado. Para trabalhos autorizados em bibliotecas ativas, use o catálogo e a listagem de habilidades do Rundesk; não abra a biblioteca ativa para contornar o limite de acesso da tarefa. Leia as descrições de correspondências plausíveis, depois seus corpos e referências relevantes antes de decidir.

Estenda o repositório existente quando a funcionalidade solicitada compartilhar sua intenção de usuário, fluxo de trabalho e autoridade. Adicione um script de suporte, referência ou teste lá, em vez de criar uma segunda superfície de roteamento. Crie uma nova habilidade somente quando a funcionalidade precisar de roteamento, julgamento, autoridade ou prova distintos; registre essa distinção para que um nome próximo não seja tratado como justificativa por si só.

Escolha o artefato

• Uma habilidade é o limite de instrução: quando agir, qual julgamento aplicar, qual procedimento seguir e como provar o resultado.
• Um script de fluxo de trabalho é o mecanismo determinístico para transformação, validação ou orquestração local repetida.
• Uma integração adiciona um limite de serviço externo: credenciais, contas, falhas de rede, permissões ou efeitos remotos.

Mantenha a automação única em seu projeto e o comando repetido privado de um agente na área de scripts desse agente. Empacote um script em uma habilidade apenas quando futuras interações precisarem de roteamento ou julgamento para usá-lo. Não substitua código determinístico por prosa que um agente precise reinterpretar.

Leia Scripts de fluxo de trabalho reutilizáveis antes de enviar qualquer script reutilizável. Leia também Integrações de serviço externo quando usar credenciais, perfis, OAuth, uma rede ou efeitos remotos.

Posicione com segurança

Crie uma habilidade privada em local somente quando a criação ou instalação ao vivo for autorizada. Para um rascunho, revisão, alteração de repositório ou teste isolado, fique no workspace nomeado ou diretório temporário; não inspecione ou altere a biblioteca ativa para descobrir onde o resultado poderá ir depois.

Para uma habilidade privada autorizada, peça ao Rundesk a biblioteca em vez de derivá-la de RUNDESK_HOME ou incorporar um caminho absoluto. Substitua o nome de exemplo:

skill_name=release-notes
skill_library=$("$RUNDESK_COMMAND" skills | sed -n '1s/^skills in //p')
test -n "$skill_library" || exit 1
mkdir -p "$skill_library/local/$skill_name"

Escreva <biblioteca>/local/<nome>/SKILL.md, então conceda-o ao agente nomeado:

"$RUNDESK_COMMAND" skills grant "$RUNDESK_AGENT" local/release-notes

A concessão se torna detectável na próxima interação do agente, não na atual. Leia Publicando um catálogo de habilidades antes de criar uma habilidade para outras instalações; habilidades publicadas pertencem a um repositório de catálogo, não a local.

Use apenas a estrutura necessária

<nome>/
├── SKILL.md          obrigatório: roteamento e procedimento principal
├── rundesk.json      opcional: valores de ambiente necessários
├── scripts/          opcional: comandos reutilizáveis
├── tests/            opcional: contratos de script quando nenhuma área de teste do catálogo os possui
├── references/       opcional: detalhes carregados condicionalmente
└── assets/           opcional: material copiado ou de saída

Crie caminhos opcionais apenas com conteúdo. Omita README, changelog, guia de instalação e histórico de criação.

Escreva o roteamento primeiro

O frontmatter tem apenas name e description.

• Corresponda name ao diretório. Use no máximo 64 letras minúsculas, dígitos e hífens simples.
• Roteie pela intenção do usuário, incluindo solicitações indiretas que podem não nomear a habilidade. Comece com Use quando, Aplique quando ou linguagem de aplicabilidade equivalente; frases de prompt não são gatilhos.
• Busque duas frases curtas: aplicabilidade, depois o fluxo de trabalho especializado ou conhecimento fornecido. Adicione Não use apenas para um erro provável. Inclua apenas conceitos necessários para rotear antes do corpo carregar. Omita etapas, testes, alegações de benefício e detalhes de implementação; nomeie um tipo de arquivo, ferramenta ou formato apenas quando ele determinar se a habilidade deve ser acionada.
• Use a descrição mais curta que ainda roteie corretamente; 1.024 caracteres é um teto, não um alvo. Coloque cada gatilho lá porque cada detentor paga por ele a cada interação e o corpo fica indisponível até que o roteamento seja bem-sucedido.

# Ruim: incorpora implementação e verificação que não ajudam no roteamento.
description: Use ao criar notas de versão. Ele lê o histórico do Git, escreve Markdown, agrupa commits, verifica links, executa validação e produz versões internas e públicas concisas com formatação precisa.

# Bom: declara intenção, julgamento fornecido e o limite mais próximo apenas.
description: Use ao preparar notas de versão a partir de alterações enviadas ao repositório. Ele fornece um fluxo de trabalho focado no público e fundamentado em histórico verificado. Não use para planos não lançados.

Mantenha apenas orientação comportamental

Use etapas imperativas em ordem de execução. Presuma que o leitor pode raciocinar, editar e usar ferramentas comuns. Mantenha uma frase apenas quando ela mudar a execução, prevenir uma falha provável ou rotear detalhes necessários.

• Mantenha o procedimento principal, um padrão forte e pegadinhas não óbvias em SKILL.md.
• Use comandos exatos para operações frágeis; use julgamento conciso onde várias abordagens funcionam.
• Explique a falha que uma restrição previne, em vez de adicionar ênfase inexplicada.
• Apresente cada referência com quando lê-la. Mantenha uma única fonte de verdade; vincule em vez de reafirmar.
• Remova histórico, alegações datadas e regras já carregadas em outro lugar.
• Diferencie contratos observados de padrões recomendados. Fundamente restrições técnicas e ensine armadilhas reais como sintoma, causa, substituição e prova observável.

Mantenha SKILL.md abaixo de 500 linhas; mova detalhes condicionais um nível para referências vinculadas.

Orçamento de contexto

Parte	Custo de token	Mantenha lá
description	toda interação	gatilho completo mais curto
SKILL.md	após o roteamento	procedimento principal, padrões, pegadinhas
references/	quando lido	detalhes condicionais e exemplos maiores
scripts/	a saída entra no contexto	trabalho determinístico com saída limitada
tests/	apenas validação	contratos executáveis e casos de borda
assets/	quando usado	modelos e material de saída

Prefira exemplos curtos. Limite a saída do script ao que a próxima decisão precisa.

Prove a habilidade completa

1. Valide o nome do diretório, nome do frontmatter, sintaxe da descrição e limites.

2. Quando uma concessão for necessária, aplique-a e verifique a próxima interação:

   "$RUNDESK_COMMAND" skills list "$RUNDESK_AGENT"
   "$RUNDESK_COMMAND" skills doctor "$RUNDESK_AGENT"
   

3. Execute cada matriz de borda de propriedade da referência e ponto de entrada executável direto do script.

4. Em diferentes interações novas, tente uma solicitação direta, uma solicitação indireta e um erro próximo. Confirme que o corpo e as referências necessárias carregam antes do trabalho; corrija o roteamento por categoria, não por frases de prompt copiadas.

5. Para uma habilidade substancial, compare a mesma tarefa com uma linha de base nova sem a habilidade. Depois, peça a um agente de teste separado para usá-la sem a implementação esperada. Revise artefatos e comandos diretamente; o resumo do agente não é prova. Remova orientação que não gere melhoria material.

6. Revise a escrita gerada separadamente da correção executável: precisão do roteamento, ordem de execução, julgamento útil, concisão, duplicação e disciplina de referência. Testes de script verdes não provam qualidade da escrita. Fundamente promessas factuais ou observe-as; teste declarações executáveis e estreite verdades parciais. Desafie declarações semânticas com um contraexemplo adversário que preserve agregados convenientes enquanto muda a relação ou resultado real—verificações de mutação não podem reparar um oráculo de teste errado. Revise toda a interface, incluindo sucesso vazio, evidência duplicada e toda seção de saída dependente de dados.