CommunityEscrita e Ediçãogithub.com

MichaelYochpaz/agent-skills

Habilidades de agente cuidadosamente elaboradas e eficientes em tokens para fluxos de trabalho confiáveis de agentes.

O que é agent-skills?

Este skill, MichaelYochpaz/agent-skills, fornece um conjunto de habilidades de agente otimizadas para tokens, projetadas para fluxos de trabalho confiáveis e eficientes em ferramentas de IA como Claude Code ou Cursor. O foco principal é a integração com o GitHub CLI (`gh`), oferecendo comandos para gerenciar repositórios, releases, issues, PRs, discussões, pesquisa e Actions. Ele prioriza saídas de texto padrão para economizar tokens, recomenda clonagem para exploração de código desconhecido e fornece diretrizes de segurança para operações destrutivas, como exclusões e merges. As habilidades são verificadas com `gh` 2.95.0 e incluem fallbacks para versões mais antigas, garantindo ampla compatibilidade.

Funciona com~Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add MichaelYochpaz/agent-skills

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.

Documentação

GitHub CLI (gh)

Interaja com o GitHub a partir da linha de comando: repositórios, releases, issues, PRs, discussões, pesquisa, revisão de código e Actions.

Verificado com gh 2.95.0.

Diretrizes do Agente

  • Para arquivos ou diretórios remotos conhecidos, use gh repo read-file / gh repo read-dir (pré-visualização no gh 2.95). Para versões mais antigas do gh ou necessidades somente de API, use o fallback da API de conteúdos em Padrões de API.
  • Quando uma tarefa exigir pesquisa em vários arquivos ou explorar código desconhecido onde os caminhos não são conhecidos antecipadamente, clone para um diretório temporário (gh repo clone owner/repo <temp-dir> -- --depth 1) e use ferramentas locais de leitura de arquivos e pesquisa.
  • Prefira a saída de texto padrão em vez de --json para leitura/visualização — é mais eficiente em tokens. Use --json com --jq somente ao extrair campos específicos programaticamente. Para descobrir campos suportados, execute o comando com --json e sem lista de campos, e então solicite apenas os campos necessários.
  • Ao visualizar logs ou diffs, escopo a saída primeiro (ex.: --name-only, --log-failed) antes de buscar o conteúdo completo.
  • A flag --repo é desnecessária ao executar dentro de um repositório clonado — o repositório do diretório atual é usado por padrão. Para gh api, use o caminho explícito (repos/OWNER/REPO/...) ou defina a variável de ambiente GH_REPO.
  • Use este skill para fluxos de trabalho cobertos. Quando uma flag ou campo necessário estiver faltando aqui, um comando falhar com uma flag desconhecida/alterada, ou o comando estiver marcado como pré-visualização, verifique a ajuda desse comando específico (ex.: gh pr diff --help).

Segurança

  • Operações de escrita (create, edit, comment, review, close, merge, delete, rerun, run cancel, workflow run/enable/disable, mutações de discussão) modificam o estado do GitHub. Confirme com o usuário antes de executar, especialmente em repositórios que você não possui.
  • gh api com --method POST/PUT/PATCH/DELETE envia solicitações de escrita. Verifique novamente o endpoint e o payload. O método padrão é GET (seguro); adicionar parâmetros -f/-F muda o padrão para POST.
  • Operações destrutivas (delete, close, merge --admin) podem ser irreversíveis. Exigem confirmação explícita do usuário.

Pré-requisitos

Verifique se o gh está instalado e autenticado antes de executar comandos:

gh --version
gh auth status

Se não estiver autenticado, guie o usuário através de gh auth login.

Flags Comuns

Estas flags estão disponíveis em muitos grupos de comandos, mas o suporte varia por comando:

  • --repo OWNER/REPO — Segmentar um repositório diferente (padrão: repositório do diretório atual). Também aceita URLs completas.
  • --json FIELDS — Saída como JSON com campos especificados. Passe sem valor para listar campos disponíveis.
  • --jq EXPRESSION — Filtrar saída JSON usando sintaxe jq. Requer --json.
  • --template STRING — Formatar saída JSON usando um template Go (alternativa ao --jq).
  • --web — Abrir o recurso no navegador em vez de exibir no terminal.
  • --limit N — Número máximo de resultados para comandos de lista (o padrão é geralmente 30).

Repositórios

Visualizar

Exibir a descrição, README, estrelas, detalhamento de linguagem e outros metadados de um repositório.

gh repo view owner/repo
gh repo view owner/repo --json name,description,defaultBranchRef,languages,stargazerCount

Clonar

Clonar um repositório localmente. Configura automaticamente o remote e, para forks, configura o remote upstream.

gh repo clone owner/repo [target-directory]

Ler conteúdo remoto de repositório

Para leituras rápidas de arquivos ou diretórios conhecidos, use os comandos de leitura de repositório (pré-visualização no gh 2.95):

# Arquivo conhecido
gh repo read-file src/main.py --repo owner/repo --ref main

# Diretório conhecido
gh repo read-dir src --repo owner/repo --ref main

# Fallback para versões mais antigas do gh
gh api "repos/OWNER/REPO/contents/src/main.py?ref=main" -H "Accept: application/vnd.github.raw+json"

Para formas de saída, limites de tamanho de arquivo e ressalvas de listagem de diretórios, veja Padrões de API. Para exploração de vários arquivos, clone em vez disso (veja Diretrizes do Agente).

Listar repositórios

Listar repositórios pertencentes a um usuário ou organização, com filtros opcionais de linguagem e visibilidade.

gh repo list owner --limit 30

Releases

Listar

Listar releases em um repositório, ordenados por data de criação (mais recentes primeiro). Padrão: exibir todos os releases, incluindo pré-lançamentos e rascunhos.

gh release list --repo owner/repo --limit 10

Flags:

  • --exclude-pre-releases — Excluir pré-lançamentos
  • --exclude-drafts — Excluir rascunhos

Campos JSON principais: tagName, name, publishedAt, isLatest, isDraft, isPrerelease, isImmutable

Visualizar (changelog, assets)

Exibir o corpo do changelog, tag, assets e metadados de um release. Omita a tag para visualizar o último release.

gh release view --repo owner/repo                         # Último release
gh release view v1.2.0 --repo owner/repo                  # Tag específica
gh release view v1.2.0 --json tagName,body,assets,publishedAt

Campos JSON principais: tagName, name, body, assets, author, publishedAt, isDraft, isPrerelease, isImmutable, url

Issues

Listar

Listar issues em um repositório, filtradas por estado, label, responsável ou consulta de pesquisa. Padrão: apenas issues abertas.

gh issue list --repo owner/repo
gh issue list --repo owner/repo --state all --label bug --assignee @me
gh issue list --repo owner/repo --search "error no:assignee sort:created-asc"

Flags:

  • --state VALUE — open (padrão), closed, all
  • --label NAME — Filtrar por label (repita para múltiplas)
  • --assignee LOGIN — Filtrar por responsável (@me para si)
  • --search QUERY — Sintaxe de pesquisa do GitHub

Campos JSON principais: number, title, state, stateReason, author, labels, assignees, createdAt, updatedAt, url

Visualizar

Exibir o título, corpo, labels, responsáveis e status de uma issue. Use --comments para incluir o tópico completo de comentários.

gh issue view 123
gh issue view 123 --comments
gh issue view 123 --json title,body,labels,comments,state

Criar

Criar uma nova issue com título, corpo, labels e responsáveis.

gh issue create --title "Bug: descrição" --body "Detalhes..." --label bug --assignee user1

Editar

Atualizar o título, corpo, labels, responsáveis ou milestone de uma issue. Todas as flags podem ser combinadas em uma única chamada.

Flags:

  • --title TEXT / --body TEXT — Atualizar título ou corpo
  • --add-label NAME / --remove-label NAME — Modificar labels
  • --add-assignee LOGIN / --remove-assignee LOGIN — Modificar responsáveis
  • --milestone NAME / --remove-milestone — Definir ou remover milestone

Comentar

Adicionar um comentário a uma issue existente.

gh issue comment 123 --body "Texto do comentário"

Fechar / Reabrir

Fechar ou reabrir uma issue. Opcionalmente, especifique um motivo de fechamento e deixe um comentário.

gh issue close 123 --comment "Corrigido no PR #456" --reason "not planned"
gh issue close 123 --duplicate-of 456
gh issue reopen 123

Motivos de fechamento: completed (padrão), not planned, duplicate.

Status

Mostrar um resumo das issues relevantes para você: atribuídas a você, mencionando você e abertas por você.

gh issue status

Para tipos de issue, sub-issues, relacionamentos pai, dependências de bloqueio e seus campos JSON (requer hosts GitHub suportados), veja Referência de Issues.

Pull Requests

Use estes comandos para visualizar e inspecionar PRs. Para criar, mesclar, revisar e gerenciar PRs, veja Referência de Pull Requests.

Listar

Listar pull requests em um repositório, filtrados por estado, autor, label ou consulta de pesquisa. Padrão: apenas PRs abertos.

gh pr list --repo owner/repo
gh pr list --repo owner/repo --state all --author @me --label "needs-review"
gh pr list --repo owner/repo --search "status:success review:required"
gh pr list --repo owner/repo --app dependabot

Flags:

  • --state VALUE — open (padrão), closed, merged, all
  • --draft — Filtrar por estado de rascunho
  • --author LOGIN / --assignee LOGIN — Filtrar por autor ou responsável
  • --label NAME — Filtrar por label
  • --search QUERY — Sintaxe de pesquisa do GitHub
  • --app NAME — Filtrar por autor do GitHub App (ex.: dependabot)

Campos JSON principais: number, title, state, author, headRefName, baseRefName, labels, reviewDecision, isDraft, statusCheckRollup, files, commits, reviews, url

Visualizar

Exibir o título, corpo, status de revisão, verificações e outros metadados de um PR. Sem argumento, mostra o PR para o branch atual. Use --comments para incluir o tópico de comentários.

gh pr view 123
gh pr view 123 --comments
gh pr view 123 --json title,body,files,commits,reviews,reviewDecision

Status

Mostrar um resumo dos PRs relevantes para você: o PR do branch atual, PRs que você criou e PRs onde sua revisão é solicitada.

gh pr status

Discussões

Use gh discussion para Discussões de repositório (pré-visualização no gh 2.94). Comece com comandos de leitura e verifique flags com --help porque o conjunto de comandos está em pré-visualização:

gh discussion list --repo owner/repo --limit 10
gh discussion view 123 --repo owner/repo --comments

Para criar, editar, comentar, tópicos de resposta, formas de saída JSON e padrões de fallback GraphQL, veja Referência de Discussões.

Pesquisa

Pesquisar no GitHub por issues, PRs, código, commits e repositórios. Use gh issue list / gh pr list para um repositório; use gh search ... para consultas entre repositórios ou em toda a organização.

Para a sintaxe completa de consulta de pesquisa, veja a documentação de pesquisa do GitHub. Para flags específicas de cada subcomando, execute gh search <subcommand> --help.

Limites de taxa: As APIs de pesquisa têm limites de taxa mais rigorosos do que a API principal. A pesquisa de código é a mais restritiva (~10/min autenticado; requer autenticação). Outros comandos de pesquisa permitem ~30/min autenticado ou ~10/min não autenticado. Verifique a cota atual com gh api rate_limit --jq '.resources | {search, code_search}'.

Quando clonar em vez disso: Veja Diretrizes do Agente para quando clonar vs. usar a API.

Bots e apps: Para autores de GitHub App como Dependabot, use --app dependabot; --author dependabot filtra contas de usuário, não autores de app.

Reconhecimento: Ao pesquisar um repositório desconhecido, verifique primeiro sua linguagem primária para selecionar os valores corretos de --extension e --language:

gh repo view owner/repo --json primaryLanguage --jq '.primaryLanguage.name'

Issues

Pesquisar issues entre repositórios usando palavras-chave, labels, estado ou sintaxe de pesquisa do GitHub.

gh search issues "error handling" --repo owner/repo
gh search issues --label bug --state open --assignee @me
gh search issues --app dependabot --repo owner/repo
gh search issues --involves username --comments ">10" --repo owner/repo

Flags principais: --repo, --owner, --state, --label, --assignee, --author, --app, --involves, --comments, --match, --sort, --include-prs.

PRs

Pesquisar pull requests entre repositórios. Suporta filtragem por autor, status de revisão, estado de merge e status de rascunho.

gh search prs "refactor" --repo owner/repo
gh search prs --review-requested @me --state open
gh search prs --app dependabot --repo owner/repo
gh search prs --author username --merged --repo owner/repo

Flags principais: --repo, --owner, --state, --merged, --draft, --author, --assignee, --app, --label, --review, --review-requested, --base, --head, --checks, --sort.

Código

Pesquisar dentro do conteúdo de arquivos em repositórios GitHub. Retorna apenas linhas correspondentes (sem números de linha, sem contexto circundante). Útil para localizar arquivos contendo um padrão, mas acompanhe com leituras de arquivo ou clone o repositório para entender a lógica do código.

Limitações: Usa um mecanismo de pesquisa legado (os resultados podem não corresponder ao github.com). Pesquisa apenas o branch padrão. Apenas arquivos com menos de 384 KB são indexados. Toda consulta deve incluir pelo menos um termo de pesquisa (pesquisas apenas com qualificadores como --extension ts sozinhas falharão). Não suporta --sort ou --order — os resultados são sempre classificados por relevância.

gh search code "functionName" --repo owner/repo
gh search code "createServer" --repo owner/repo --extension ts
gh search code "lint" --repo owner/repo --filename package.json

Flags principais: --repo, --owner, --extension, --filename, --language, --match, --size.

Campos JSON principais: path, repository, sha, textMatches, url.

O campo textMatches fornece contexto de fragmento com posições de correspondência em nível de caractere — use --json path,textMatches quando precisar de mais contexto do que a saída de texto padrão fornece.

Commits

Pesquisar commits por texto de mensagem, autor, data do committer ou hash.

gh search commits "fix bug" --repo owner/repo
gh search commits --author username --committer-date ">2024-01-01"
gh search commits --hash abc1234

Flags principais: --repo, --owner, --author, --committer, --author-date, --committer-date, --author-name, --author-email, --hash, --merge, --sort.

Repositórios

Pesquisar por repositórios por palavra-chave, linguagem, tópico, estrelas, licença ou proprietário. Nota: --repo não está disponível neste subcomando — use --owner para filtrar por proprietário.

gh search repos "keyword" --language python --sort stars --order desc
gh search repos --topic cli --stars ">1000" --language go

Flags principais: --owner, --language, --topic, --stars, --forks, --license, --created, --updated, --match, --sort, --include-forks, --visibility.

Excluindo qualificadores (prefixo de hífen)

Consultas de pesquisa com exclusões como -label:bug precisam de sintaxe especial para evitar interpretação de flag do shell. Todas as flags (ex.: --limit) devem aparecer antes de --; qualquer coisa após -- é interpretada como texto de consulta de pesquisa:

# Shells tipo Unix
gh search issues -- "my query -label:bug"

# PowerShell
gh --% search issues -- "my query -label:bug"

…

[truncado para tradução]

Habilidades Relacionadas