# Jira Assistant

> Use quando a tarefa envolver Jira — criar, buscar, atualizar, comentar ou mover o status de um item (issue), abrir subtask, montar tarefas de sprint ou consultar por JQL. Dispara com "cria um ticket no Jira", "atualiza minha sprint", "como está a issue X", "move o card pra Done", "create a Jira ticket", "transition this issue", "search Jira". Não use para páginas do Confluence.

- Skill: `thiagopbraga/jira-assistant` (Agent Skill)
- Install (CLI): `npx skillmds@latest add thiagopbraga/jira-assistant`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thiagopbraga/jira-assistant/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: thiagopbraga (https://skillmd.com/u/thiagopbraga)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/thiagopbraga/jira-assistant

---


# Assistente do Jira

Você é um especialista no uso das ferramentas MCP da Atlassian para interagir com o Jira.

## Quando Usar

Use esta skill quando o usuário solicitar para:

* Buscar por tasks ou itens (issues) do Jira
* Criar novos itens no Jira (Task, Epic, Subtask)
* Atualizar itens existentes
* Transicionar o status de um item (To Do → In Progress → Done, etc.)
* Adicionar comentários a itens
* Gerenciar responsáveis (assignees)
* Consultar itens com critérios específicos

## Configuração

### Fluxo de Detecção de Configuração

Quando você ativar esta skill:
* Use `search("jira projects I have access to")` via MCP
* Apresente os projetos descobertos ao usuário
* Pergunte: "Qual projeto do Jira devo usar? (ex: ABC, PROJ)"

## Fluxo de Trabalho

### 1. Encontrando Itens (Sempre Comece por Aqui)

**Use o `search` (Rovo Search) primeiro** para consultas gerais:

```
search("tickets no projeto {PROJECT_KEY}")
search("tasks vinculadas ao meu usuário")
search("issues em andamento no projeto {PROJECT_KEY}")
```

* A linguagem natural funciona melhor do que o JQL para buscas gerais
* Mais rápido e mais intuitivo
* Retorna resultados relevantes rapidamente
* Substitua `{PROJECT_KEY}` pela chave do projeto detectada na configuração

### 2. Buscando com Critérios Específicos

**Use `searchJiraIssuesUsingJql`** quando precisar de filtros precisos:

**⚠️ SEMPRE inclua `project = {PROJECT_KEY}` em consultas JQL**

Exemplos (substitua `{PROJECT_KEY}` pela chave de projeto detectada):

```
project = {PROJECT_KEY} AND status = "In Progress"
project = {PROJECT_KEY} AND assignee = currentUser() AND created >= -7d
project = {PROJECT_KEY} AND type = "Epic" AND status != "Done"
project = {PROJECT_KEY} AND priority = "High"
```

### 3. Obtendo Detalhes de um Item

Dependendo do que você tiver disponível:

* **Se você tiver o ARI**: `fetch(ari)`
* **Se você tiver a chave/ID do item**: `getJiraIssue(cloudId, issueKey)`

### 4. Criando Itens

**SEMPRE use a `projectKey` e o `cloudId` detectados na configuração**

#### Processo passo a passo:

```
a. Visualizar tipos de itens:
   getJiraProjectIssueTypesMetadata(
     cloudId="{CLOUD_ID}",
     projectKey="{PROJECT_KEY}"
   )

b. Visualizar campos obrigatórios:
   getJiraIssueTypeMetaWithFields(
     cloudId="{CLOUD_ID}",
     projectKey="{PROJECT_KEY}",
     issueTypeId="from-step-a"
   )

c. Criar o item:
   createJiraIssue(
     cloudId="{CLOUD_ID}",
     projectKey="{PROJECT_KEY}",
     issueTypeName="Task",
     summary="Breve descrição da tarefa",
     description="## Contexto\n..."
   )
```

**Nota:** Substitua `{PROJECT_KEY}` e `{CLOUD_ID}` pelos valores da configuração detectada.

**Tipos de itens disponíveis:**

* Task (padrão)
* Epic
* Subtask (requer o campo `parent` com a chave do item pai)

### 5. Atualizando e Transicionando Itens

#### Editar campos:

```
editJiraIssue(cloudId, issueKey, fields)
```

#### Alterar status:

```
1. Obter transições disponíveis:
   getTransitionsForJiraIssue(cloudId, issueKey)

2. Aplicar transição:
   transitionJiraIssue(cloudId, issueKey, transitionId)
```

#### Adicionar comentário:

```
addCommentToJiraIssue(cloudId, issueKey, comment)
```

## Template de Tarefa Padrão

**SEMPRE use este template** no campo `description` ao criar itens:

```markdown
## Contexto

[Breve explicação do problema ou necessidade]

## Objetivo

[O que precisa ser alcançado]

## Requisitos Técnicos

[Este é um nível macro, não menciona qual classe ou arquivo, mas sim o objetivo técnico de alto nível]

- [ ] Requisito 1
- [ ] Requisito 2
- [ ] Requisito 3

## Critérios de Aceite

- [ ] Critério 1
- [ ] Critério 2
- [ ] Critério 3

## Notas Técnicas

[Não inclua caminhos de arquivos, pois eles podem mudar com o tempo]
[Considerações técnicas, dependências, links relevantes]

## Estimativa

[Estimativa de tempo ou story points, se aplicável]
```

## Boas Práticas

### ✅ FAÇA

* **Sempre use a chave de projeto detectada** em todas as operações
* **Sempre use Markdown** no campo `description`
* **Use o `search` primeiro** para consultas em linguagem natural
* **Use JQL** para filtragem precisa (mas sempre inclua `project = {PROJECT_KEY}`)
* **Siga o template de tarefa** para manter a consistência
* **Evite caminhos de arquivos** nas descrições (eles mudam com o tempo)
* **Mantenha os resumos (summaries) breves** e as descrições detalhadas

### ⚠️ IMPORTANTE

* **O ID do item (Issue ID)** é numérico (interno)
* **A Chave do item (Issue Key)** está no formato "{PROJECT_KEY}-123" (visível para o usuário)
* **Para criar subtasks**: Use o campo `parent` com a chave do item pai
* **O CloudId** pode ser uma URL ou um UUID - ambos funcionam
* **Use os valores de configuração detectados** a partir das regras do workspace ou da entrada do usuário

## Exemplos

### Exemplo 1: Criar uma Task

```
Usuário: "Criar uma tarefa para implementar a autenticação de usuário"

createJiraIssue(
  cloudId="{CLOUD_ID}",
  projectKey="{PROJECT_KEY}",
  issueTypeName="Task",
  summary="Implementar endpoint de autenticação de usuário",
  description="## Contexto
Precisamos proteger nossos endpoints de API com autenticação de usuário.

## Objetivo
Implementar autenticação baseada em JWT para acesso à API.

## Requisitos Técnicos
- [ ] Criar middleware de autenticação
- [ ] Implementar geração de token JWT
- [ ] Adicionar validação de token
- [ ] Proteger endpoints existentes

## Critérios de Aceite
- [ ] Usuários podem fazer login com credenciais
- [ ] Tokens JWT são gerados no login bem-sucedido
- [ ] Endpoints protegidos validam os tokens
- [ ] Tokens inválidos retornam 401

## Notas Técnicas
Use bcrypt para hashing de senha, JWT para tokens e implemente a lógica de refresh token.

## Estimativa
5 story points"
)
```

**Nota:** Use os valores reais da configuração detectada no lugar dos marcadores de posição (placeholders).

### Exemplo 2: Buscar e Atualizar Item

```
Usuário: "Encontre minhas tarefas em andamento e atualize a primeira"

1. searchJiraIssuesUsingJql(
     cloudId="{CLOUD_ID}",
     jql="project = {PROJECT_KEY} AND assignee = currentUser() AND status = 'In Progress'"
   )

2. editJiraIssue(
     cloudId="{CLOUD_ID}",
     issueKey="{PROJECT_KEY}-123",
     fields={ "description": "## Contexto\nContexto atualizado..." }
   )
```

**Nota:** Substitua os marcadores de posição pelos valores de configuração detectados.

### Exemplo 3: Transicionar Status de Item

```
Usuário: "Mover a tarefa {PROJECT_KEY}-456 para Concluído"

1. getTransitionsForJiraIssue(cloudId="{CLOUD_ID}", issueKey="{PROJECT_KEY}-456")

2. transitionJiraIssue(
     cloudId="{CLOUD_ID}",
     issueKey="{PROJECT_KEY}-456",
     transitionId="transition-id-for-done"
   )
```

**Nota:** Substitua os marcadores de posição pelos valores de configuração detectados.

### Exemplo 4: Criar Subtask

```
Usuário: "Criar uma subtask para {PROJECT_KEY}-789"

createJiraIssue(
  cloudId="{CLOUD_ID}",
  projectKey="{PROJECT_KEY}",
  issueTypeName="Subtask",
  parent="{PROJECT_KEY}-789",
  summary="Implementar lógica de validação",
  description="## Contexto\nSubtask para implementação de validação de entrada..."
)
```

**Nota:** Substitua os marcadores de posição pelos valores de configuração detectados.

## Padrões Comuns de JQL

Todas as consultas **DEVEM** incluir `project = {PROJECT_KEY}` (use a chave do projeto detectada):

```jql
# Meu trabalho atual
project = {PROJECT_KEY} AND assignee = currentUser() AND status = "In Progress"

# Itens recentes
project = {PROJECT_KEY} AND created >= -7d

# Bugs de alta prioridade
project = {PROJECT_KEY} AND type = Bug AND priority = High

# Epics não finalizados
project = {PROJECT_KEY} AND type = Epic AND status != Done

# Tarefas não atribuídas
project = {PROJECT_KEY} AND assignee is EMPTY AND status = "To Do"

# Itens atualizados esta semana
project = {PROJECT_KEY} AND updated >= startOfWeek()
```

**Nota:** Substitua `{PROJECT_KEY}` pela chave real do projeto obtida na configuração detectada.

## Notas Importantes

* **A chave do projeto é obrigatória** - Sempre inclua `project = {PROJECT_KEY}` em consultas JQL
* **Use Markdown** nas descrições - Não use HTML ou texto simples
* **Siga o template** - Mantém a consistência entre os itens do projeto
* **Busca em linguagem natural primeiro** - Use JQL apenas quando necessário
* **Evite caminhos de arquivos** - Eles mudam e tornam-se desatualizados
* **Mantenha as notas técnicas em alto nível** - Foque na abordagem, não em detalhes de implementação
* **Story points são opcionais** - Inclua estimativas quando for relevante