CommunityEscrita e Ediçãogithub.com

FrancescoBorzi/agent-toolkit

Habilidades e regras minimalistas e independentes de projeto para agentes de codificação de IA.

O que é agent-toolkit?

Esta skill, chamada 'Ticket Fetcher', permite que agentes de IA (como Claude Code, Cursor, etc.) busquem tickets de forma limpa e isolada de sistemas de rastreamento como Azure DevOps, Jira e GitHub Issues. Ela se concentra exclusivamente na extração e formatação de dados, sem realizar qualquer análise ou planejamento. O resultado é um arquivo `.TICKET.md` autocontido, que inclui metadados, descrição, critérios de aceitação, comentários, anexos baixados e referências de design. A skill prioriza a integridade dos dados, garantindo que anexos sejam baixados e verificados corretamente, e que links relacionados sejam listados. Ela também sugere claramente o próximo passo, gerando um comando de inicialização para uma nova sessão de refinamento do ticket. É útil para desenvolvedores que precisam de uma representação completa e portátil de um ticket para trabalho offline ou em diferentes ferramentas de IA.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add FrancescoBorzi/agent-toolkit

Installed? Explore more Escrita e Edição skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Prévia

Do README da skill

attachment-1
figma-<nodeId>

Documentação

Ticket Fetcher

Somente busca — sem análise, requisitos ou planejamento. A saída é um arquivo .TICKET.md autocontido.

Origem e acesso

Identifique o rastreador a partir da entrada (host da URL ou formato do ID) e busque através do servidor MCP correspondente — por exemplo, Azure DevOps MCP para itens de trabalho do ADO, Atlassian MCP para issues do Jira, GitHub MCP / gh para issues do GitHub. Use quaisquer ferramentas equivalentes que estejam conectadas; os prefixos dos nomes das ferramentas variam conforme a configuração. Resolva uma vez qualquer identificador que o MCP precise (por exemplo, cloudId do Atlassian, projeto do ADO) e reutilize-o. Se a entrada for ambígua, pergunte ao usuário — não adivinhe. Se nenhum MCP correspondente estiver conectado: um ticket público pode ser extraído de sua URL como fallback (você ainda pode sugerir a instalação do MCP correspondente quando ele faria um trabalho melhor); um ticket privado não pode — a URL retorna uma página de login, não o ticket — então pare e informe ao usuário para instalar e autenticar o servidor MCP correspondente e, em seguida, executar novamente.

Sua tarefa

  1. Resolva a entrada. Aceite uma URL completa de ticket ou um ID/chave simples; extraia o identificador. Se o rastreador usar um prefixo de chave (por exemplo, XX-1234), mantenha-o; caso contrário, use o número simples. Se a entrada for irreconhecível, pergunte.
  2. Busque o ticket. Obtenha o item de trabalho/issue com seu conjunto completo de campos, comentários inline e links/relações relacionados expandidos. Capture tudo que o ticket contém — não pré-filtre para um conjunto fixo de campos. Converta qualquer formato de rich text que você receber (HTML, ADF, …) para Markdown limpo.
  3. Escolha um slug. Slug curto em kebab-case, de 3 a 5 palavras, a partir do título/resumo — pesquisável, não complique.
  4. Decida o diretório de saída. Um subdiretório <id>-<slug>/ relativo ao projeto, dentro do diretório de planejamento do projeto (por exemplo, .claude/plans/) — siga a convenção do projeto/usuário para onde os planos devem ficar; se nenhum estiver definido, pergunte ao usuário. Nunca adivinhe. Se já existir, sugira <id>-<slug>-v2, -v3, etc. — nunca sobrescreva um diretório de plano existente; o histórico por nova busca é mantido intencionalmente.
  5. Escreva o arquivo do ticket em <output-dir>/<id>-<slug>.TICKET.md.
  6. Baixe os anexos para o diretório de saída; avise sobre qualquer um que falhar (veja Anexos).
  7. Imprima o resultado — caminhos relativos ao projeto e a linha do próximo passo (veja Próximo passo).

Estrutura do arquivo do ticket

Deve ser autocontido: uma versão completa e legível do ticket com metadados suficientes para que uma nova sessão identifique a origem sem precisar buscar novamente.

Cabeçalho

Cabeçalho Markdown simples com metadados de origem; omita qualquer linha cujo valor esteja ausente. Inclua o que o rastreador fornecer. Exemplo:

# <título / resumo>

> **Origem** [<id>](<url>)
> **Tipo** {tipo}
> **Status** {status}
> **Responsável** {nome de exibição ou "—"}
> **Reportado por / Criado por** {nome de exibição}
> **Rótulos / Tags** {unidos ou "—"}
> **Obtido em** {hoje AAAA-MM-DD}

Seções do corpo

Emita nesta ordem, somente se presentes e não vazias:

  1. ## Descrição
  2. ## Critérios de aceitação — se o rastreador tiver um campo dedicado de AC populado
  3. ## <Outros campos> — uma seção para cada outro campo populado com conteúdo real (notas técnicas, campos personalizados, …), com o nome de exibição do campo como cabeçalho. Capture tudo que o ticket contém.
  4. ## Comentários — mais antigos primeiro, cada um com ### <autor> — <data> e o corpo. Melhor esforço: se os comentários não forem retornados, anote brevemente ou omita a seção.
  5. ## Tickets relacionados — veja abaixo
  6. ## Anexos — veja abaixo
  7. ## Referências de design — veja abaixo

Preserve a hierarquia de cabeçalhos, estrutura de marcadores, ênfase e blocos de código; mapeie subtítulos dentro de campos para ####. Omita seções vazias. Coloque strings voltadas ao usuário, identificadores de código, caminhos de arquivo, chaves de i18n e URLs exatamente como estão — nunca os altere ou traduza.

Tickets relacionados

A partir dos links/relações da resposta (e de qualquer ferramenta de link remoto), para cada ticket vinculado único (excluindo este) busque apenas título + status + tipo por meio de uma chamada barata — não o corpo completo. O objetivo principal é que haja um rastro de todos os tickets relacionados, para que possam ser buscados posteriormente, se necessário. Um marcador para cada, com o relacionamento, se disponível:

- [<id>](<url>) — (<tipo>, <status>) <título>

Para links remotos que não são tickets (por exemplo, uma página wiki/Confluence), emita o título e a URL como um marcador simples. Se uma busca falhar, liste o link com (não foi possível buscar) em vez de falhar toda a execução.

Anexos

Identifique cada anexo e cada imagem inline referenciada na descrição/campos, numerados como attachment-<N>.<ext> na ordem da primeira aparição, mantendo a extensão original. <N> é sequencial para ambos combinados.

Sempre tente buscar — em todos os MCPs conectados. Além dos anexos hospedados no rastreador, o ticket pode conter links para ativos externos (por exemplo, um recurso Confluence/ADO — para links de ferramentas de design como Figma ou Zeplin, veja Referências de design abaixo) acessíveis por meio de seu próprio MCP, incluindo arquivos de especificação/documentação em um repositório git vinculado (busque seu conteúdo via git ou o MCP do repositório, salve no diretório de saída com seu próprio nome de arquivo). Use o MCP que se adequar à origem para fazer o download; não declare um link como não buscável antecipadamente. Se um MCP apropriado estiver conectado, mas não autenticado, não o ignore silenciosamente — execute proativamente seu fluxo de autenticação (exiba a URL de login, complete o handshake) sem esperar ser solicitado, e então faça a busca. Quando não estiver claro se um ativo pode ou deve ser baixado, pergunte ao usuário.

Baixe cada um diretamente para o disco — curl -fSL <url> -o attachment-<N>.<ext>, ou a variante de salvar para caminho da ferramenta de anexo do MCP. Nunca roteie um anexo como base64 inline através do modelo e o re-emita: os limites de saída (~100k caracteres) o truncam silenciosamente — cabeçalho válido, rodapé ausente, não será aberto. Algumas ferramentas de anexo MCP retornam apenas base64 sem opção de salvar para caminho (por exemplo, ADO wit_get_work_item_attachment) — não as use para binários; busque da API REST do rastreador diretamente para o disco com um token de portador (ADO: az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv, depois curl -H "Authorization: Bearer <token>" "<attachmentUrl>" -o attachment-<N>.<ext>). (URLs de conteúdo frequentemente compartilham a autenticação do MCP; em caso de 401, tente novamente com o token de portador do rastreador, se obtível.)

Verifique a integridade, não apenas a transferência — não vazio; corresponde a Content-Length se enviado; rodapé do tipo presente (PNG IEND, JPEG FFD9, PDF %%EOF). Um tamanho que seja um múltiplo exato de 3 próximo a um limite de caracteres redondo sinaliza truncamento base64. Em caso de falha, baixe novamente para o disco; se ainda estiver ruim, trate como não baixado e avise — nunca faça referência a um arquivo corrompido. Então, por arquivo:

  • Baixado → faça referência ao arquivo local.
  • Não baixado (nenhum MCP/ferramenta de anexo adequada, autenticação que não pôde ser concluída, etc.) → ainda faça referência ao arquivo local e à URL de origem, e adicione-o à lista de avisos. Não bloqueie — o ticket é utilizável de qualquer forma.

Imagem → incorpore; não imagem (PDF, .docx, …) → link:

### Anexo 1

![attachment-1](attachment-1.png)
_Nome original do arquivo: image.png_

### Anexo 2

[attachment-2.pdf](attachment-2.pdf) — _Nome original do arquivo: design-spec.pdf_

Para um arquivo que não pôde ser baixado, acrescente sua origem para que o usuário possa buscá-lo manualmente: — não baixado; obtenha-o de <url> e salve aqui como attachment-<N>.<ext>.

Referências de design

Para links de ferramentas de design (Figma, Zeplin, Sketch, Adobe XD, …) na descrição/comentários, não os numere como attachment-<N> — são referências vivas, não arquivos anexados. Capture cada frame/tela referenciada por meio do MCP dessa ferramenta (por exemplo, Figma MCP get_screenshot), baixando a URL de curta duração retornada diretamente para o disco como <tool>-<id>-<slug>.png (autentique seu MCP primeiro, se necessário — veja Anexos). Se nenhum MCP para essa ferramenta estiver conectado, ainda registre a entrada com seu nome e URL de origem e adicione-a à lista de avisos — da mesma forma que um anexo não baixado. Registre uma entrada por link, com a visualização local e os identificadores necessários para reabri-lo na ferramenta:

### <nome do design>

![figma-<nodeId>](figma-<nodeId>-<slug>.png)
_Figma · arquivo `<fileKey>` · nó `<nodeId>` · [origem](<url>)_

Limites

  • Não analise, planeje ou explore a base de código para contexto — isso não isenta arquivos que o ticket vincula explicitamente, que você ainda busca (veja Anexos).
  • Não modifique o ticket em seu rastreador — a busca é somente leitura (sem comentários, transições, edições, logs de trabalho).
  • Os únicos arquivos que você cria: o .TICKET.md, seus anexos e quaisquer documentos vinculados que você buscou.

Próximo passo

Quando terminar, declare claramente, usando caminhos relativos ao projeto (nunca absolutos): o diretório de saída, o arquivo do ticket e quaisquer anexos. Se algum anexo não pôde ser baixado, primeiro emita um aviso claro listando cada attachment-<N>.<ext> ausente e sua URL de origem, instruindo o usuário a baixá-lo e salvá-lo com esse nome exato para que as incorporações sejam resolvidas. Em seguida, passe a próxima fase como um único comando de inicialização copiável e colável — nome da sessão e prompt combinados, para que uma única colagem inicie a sessão. Use a sintaxe de inicialização da ferramenta agente em uso (independente de fornecedor — claude abaixo é apenas o exemplo), nomeando a sessão como refine-<slug>:

claude --name refine-<slug> "/refine-ticket <output-dir>/<id>-<slug>.TICKET.md"

Em seguida, ofereça a alternativa — limpar a sessão atual em vez disso (independente de fornecedor — /clear abaixo é apenas o exemplo; use o comando de limpeza da ferramenta agente em uso):

OU /clear e execute:

/refine-ticket <output-dir>/<id>-<slug>.TICKET.md

Habilidades Relacionadas