Escreva e mantenha habilidades de gestão de produtos que ensinem bom discernimento

## Mantenha as razões e os exemplos que ensinam bom discernimento ao usuário ### Atenda aos dois públicos Uma habilidade de gestão de produtos deve ajudar um profissional a concluir um trabalho útil e a aprimorar sua prática. Crie cada habilidade tanto para a pessoa que desenvolve discernimento quanto para o agente que executa o fluxo de trabalho. Não otimize para um público em detrimento do outro. Deixe o raciocínio por trás do fluxo de trabalho visível o suficiente para que as recomendações sejam confiáveis, explicáveis e transferíveis. O usuário deve entender por que uma abordagem funciona, não apenas receber um artefato concluído. ### Proteja a estrutura de aprendizagem - Não encurte explicações quando isso eliminar o raciocínio necessário para tomar decisões acertadas. - Preserve antipadrões explícitos, pois eles ensinam aos usuários o que reconhecer e evitar em situações reais. - Use exemplos que mostrem o processo de raciocínio, não apenas o resultado final. - Defina termos especializados quando aparecerem pela primeira vez e explicite as compensações envolvidas. - Mantenha o fluxo de trabalho prático e pronto para agentes sem retirar a camada de coaching. Ao melhorar a eficiência, elimine repetições, conteúdo supérfluo e informações contextuais secundárias antes de remover lições, exemplos ou modos de falha. Se não estiver claro se uma passagem é uma estrutura de apoio ou conteúdo desnecessário, mantenha-a até que sua função seja compreendida. ### Demonstre qualidade em diferentes contextos Inclua pelo menos um exemplo concreto que mostre como as evidências levam a uma decisão. Para uma habilidade plenamente desenvolvida, acrescente um modelo reutilizável e exemplos completos de dois contextos de negócios significativamente diferentes, como um serviço de software e uma empresa física ou operacional. Use organizações e dados fictícios. ## Dê a cada habilidade sua própria pasta e não edite à mão as listas geradas ### Separe fontes canônicas de resultados derivados Mantenha cada habilidade em sua própria pasta, com nome consistente, contendo um documento canônico da habilidade e todos os recursos ou scripts de apoio específicos dela. Armazene comandos reutilizáveis de orquestração separadamente das habilidades individuais. Mantenha pesquisas, documentação do usuário, aplicativos de visualização prévia e artefatos de lançamento em áreas distintas com responsabilidades claramente definidas. Trate catálogos gerados, índices, cópias de pacotes e pacotes de distribuição como artefatos derivados. Gere-os novamente a partir das fontes canônicas em vez de editá-los diretamente. Use kebab-case em letras minúsculas nos nomes das pastas de habilidades e mantenha o nome da pasta sincronizado com o nome declarado da habilidade. Preserve caminhos estáveis sempre que possível; renomeie uma habilidade somente quando necessário e, em seguida, atualize todas as referências. ### Respeite os limites de responsabilidade Antes de editar o conteúdo, confirme qual repositório ou espaço de trabalho é responsável por ele. Uma biblioteca compartilhada, um manual específico de produto e um repositório de distribuição podem fazer referência uns aos outros e, ainda assim, ter fontes oficiais diferentes. Trabalhe no local responsável e trate os demais locais como referências somente para leitura, a menos que a tarefa altere explicitamente esse limite. Não deduza a estrutura apenas a partir de um nome de diretório conhecido. Antes de tomar decisões estruturais, use as definições, as regras de contribuição, os scripts e os exemplos existentes do próprio repositório. ### Encontre a capacidade mais específica Antes de improvisar orientações sobre gestão de produtos, examine as habilidades disponíveis e escolha a correspondência mais específica. As áreas comuns incluem descoberta, Jobs to Be Done, personas, estratégia de produto, priorização, roteiros, documentos de requisitos, histórias de usuário, critérios de aceitação, trabalho com produtos de inteligência artificial, fluxos de trabalho de agentes e alinhamento de partes interessadas. Trate essas áreas como fluxos de trabalho de coaching e geração de artefatos, não como tarefas genéricas de engenharia de software. ## Inclua exemplos e erros comuns em cada habilidade e faça uma pergunta por vez ### Use um contrato de documento consistente Dê a cada habilidade uma sequência clara, como Propósito, Entrada, Conceitos Principais, Aplicação, Exemplos, Armadilhas Comuns e Referências. Inclua no frontmatter os campos name, description e type. Quando as plataformas de destino impuserem esses limites, mantenha name dentro de 64 caracteres e description dentro de 200 caracteres. Use títulos Markdown claros e parágrafos curtos. Adicione identificadores de linguagem aos blocos de código delimitados. Mantenha o texto conciso e com uma posição definida, mas não sacrifique o raciocínio, as condições ou os exemplos necessários. ### Transforme a entrada em um convite, não em uma barreira A seção Entrada deve explicar em linguagem simples o que o usuário pode fornecer e incluir um exemplo de chamada. Trate as informações fornecidas na solicitação como respostas já dadas. Permita uma entrada inicial parcial ou inexistente. Explique como o fluxo guiado coletará as informações que faltam em vez de impedir o usuário de prosseguir. Evite espaços reservados específicos do ambiente de execução ou sintaxes de modelo que aparecerão literalmente em ambientes incompatíveis. ### Crie fluxos interativos de forma deliberada Para uma habilidade interativa: - Faça uma pergunta por vez ou use pequenos grupos coerentes. - Permita que cada resposta determine a próxima pergunta. - Ofereça recomendações numeradas e adequadas ao contexto para os próximos passos. - Permita a seleção por número e também uma entrada personalizada. - Adapte o fluxo de trabalho quando as escolhas do usuário alterarem o caminho relevante. Torne a habilidade autossuficiente e utilizável por um agente sem pressupostos ocultos. Inclua pelo menos um antipadrão explícito e explique por que ele falha. ## Revise as habilidades e seus links com as ferramentas da biblioteca antes de compartilhar ### Use o caminho de validação da própria biblioteca Prefira as ferramentas documentadas do repositório para descoberta, validação, empacotamento e testes completos da biblioteca em vez de verificações improvisadas. Use a descoberta de arquivos e pesquisas direcionadas de referências para verificar os locais das habilidades e as referências cruzadas antes de enviar alterações. Valide se os caminhos canônicos das habilidades são resolvidos, se os metadados são válidos, se as seções obrigatórias estão presentes, se os exemplos e as referências estão corretos e se os links permanecem consistentes. Quando não houver testes automatizados disponíveis, realize essas verificações manualmente em vez de alegar um sucesso não verificado. Execute o criador de pacotes e o gerador de catálogos por meio de seus pontos de entrada mantidos. Se um aplicativo de visualização prévia tiver sido alterado, use o caminho de visualização local relevante e verifique sua documentação. ### Preserve a compatibilidade e a automação segura Respeite os requisitos de empacotamento específicos da plataforma, incluindo o uso exato de letras maiúsculas e minúsculas nos nomes de arquivo quando exigido. Mantenha os scripts de apoio determinísticos, documentados e sem acesso à rede, a menos que o fluxo de trabalho exija e controle isso explicitamente. Revise a segurança dos scripts e do conteúdo empacotado antes de compartilhá-los ou executá-los. Não remova arquivos gerenciados de marketplace, plugin ou compatibilidade apenas porque pareçam não relacionados. Não edite artefatos de lançamento gerados como substituto para a correção de sua fonte canônica. ### Verifique a verdadeira fonte oficial Antes de alterar uma categoria, um tipo de habilidade ou uma estrutura de pacote, fundamente a decisão nos critérios locais e na habilidade canônica relevante. Prefira evidências de validadores mantidos e ferramentas do repositório em vez de convenções pessoais. Se o trabalho solicitado pertencer a outro repositório, interrompa a escrita no limite atual e direcione a alteração à fonte responsável. O material de referência pode orientar o trabalho sem se tornar o alvo da edição. ## Faça mudanças pequenas e siga uma lista de verificação antes de publicar ### Prepare contribuições fáceis de revisar Mantenha as alterações pequenas, fáceis de manter e limitadas ao objetivo declarado. Use assuntos de commit claros e no imperativo. Uma solicitação de revisão deve resumir a alteração, incluir links para issues relevantes, identificar o tipo de habilidade e destacar mudanças significativas de compatibilidade ou comportamento. Ao adicionar ou renomear uma habilidade, atualize as entradas do catálogo, as contagens, as tabelas, os caminhos e os links cruzados. Antes do lançamento, verifique se todas as referências são resolvidas. ### Aplique uma lista de verificação completa para o lançamento - Valide as pastas canônicas de habilidades e os metadados. - Recrie os pacotes para download e os catálogos gerados a partir da fonte. - Confirme se os exemplos, as referências e os links de navegação continuam corretos. - Verifique a sintaxe do frontmatter e todas as cópias de pacotes específicas da plataforma. - Atualize a documentação da interface e as notas de lançamento quando um aplicativo de visualização prévia for alterado. - Verifique se nenhum artefato gerado, arquivo não relacionado ou substituição ampla involuntária entrou na alteração. ### Use os resultados educacionais como critério final Uma habilidade pronta para lançamento é pedagógica, pronta para uso por agentes, autossuficiente e prática. Ela inclui raciocínio, pelo menos um exemplo completo, um antipadrão explícito, termos especializados definidos e compensações visíveis. Uma habilidade plenamente desenvolvida também inclui um modelo reutilizável e exemplos de áreas contrastantes. Não remova explicações, antipadrões ou exemplos apenas para reduzir o tamanho. Aprove o lançamento somente quando a habilidade produzir um resultado útil, fortalecer o discernimento do usuário e continuar fácil de manter em todos os ambientes compatíveis.