@_brenosiqueira/claude-skills 1.0.0

package/skills/project-docs/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: project-docs
+description: >
+  Generates and maintains standardized documentation for software projects.
+  Use this skill whenever the user wants to create, update or improve project
+  documentation — including project vision, architecture decisions, sprint plans,
+  API contracts, README, or onboarding guides. Triggers on phrases like "create
+  documentation", "write the README", "document the architecture", "create a
+  project doc", "document this project", "what docs are missing", "generate
+  onboarding guide", or any request to produce structured written documentation
+  for a software project. Always use this skill when the conversation has enough
+  project context to produce a meaningful document — even if the user doesn't
+  say "documentation" explicitly.
+---
+
+# Project Docs Skill
+
+Generates standardized, consistent documentation for software projects.
+Asks for format (Markdown or Word), produces the first document, then
+proactively suggests what to create next based on what's missing.
+
+---
+
+## Document catalog
+
+| ID | File | Purpose |
+|---|---|---|
+| `project` | `PROJETO.md` | Product vision, roadmap, business model |
+| `architecture` | `ARQUITETURA.md` | Stack, ADRs, system diagrams, repos |
+| `sprints` | `SPRINTS.md` | Sprint history and planning |
+| `readme` | `README.md` | Overview, how to run, how to contribute |
+| `api` | `API.md` | Endpoint contracts, request/response examples |
+| `onboarding` | `ONBOARDING.md` | Guide for new developers joining the project |
+
+---
+
+## Workflow
+
+### Step 1 — Understand context
+
+Extract from the conversation what is already known about the project:
+- Project name, type, purpose
+- Stack and architecture decisions
+- Team size and stage (MVP, growth, etc.)
+- What has already been built or decided
+
+Do NOT ask for information that can be inferred from the conversation.
+If key information is missing for the requested document, ask one focused
+question — not a list.
+
+### Step 2 — Ask for format
+
+Ask the user which format they want:
+
+> "Prefere **Markdown** (`.md`, ideal para manter no repositório junto com o código)
+> ou **Word** (`.docx`, ideal para compartilhar com stakeholders não-técnicos)?"
+
+- If Markdown: generate `.md` file, save to `/mnt/user-data/outputs/`
+- If Word: read the `docx` skill at `/mnt/skills/public/docx/SKILL.md` before generating
+
+### Step 3 — Generate the document
+
+Read the reference template for the requested document type:
+- `references/project.md` → for PROJETO.md
+- `references/architecture.md` → for ARQUITETURA.md
+- `references/sprints.md` → for SPRINTS.md
+- `references/readme.md` → for README.md
+- `references/api.md` → for API.md
+- `references/onboarding.md` → for ONBOARDING.md
+
+Follow the template structure exactly. Populate with real project information
+from the conversation. Never leave placeholder text like "[INSERT HERE]" in
+the output — if information is missing, write a sensible default or omit the
+section with a comment explaining what should go there.
+
+### Step 4 — Present and suggest next
+
+After presenting the file, show the user what docs exist and what's missing:
+
+```
+✅ PROJETO.md — gerado agora
+✅ ARQUITETURA.md — gerado anteriormente (se aplicável)
+⬜ README.md — visão geral e como rodar o projeto
+⬜ API.md — contratos dos endpoints
+⬜ ONBOARDING.md — guia para novos devs
+⬜ SPRINTS.md — histórico de sprints
+
+Quer que eu gere o README.md agora?
+```
+
+Only suggest documents that make sense for the project stage. A solo MVP
+project in week 1 doesn't need ONBOARDING.md yet — suggest it later.
+
+---
+
+## Quality rules (apply to every document)
+
+- **No placeholder text.** Every section has real content or is omitted.
+- **No filler.** Every sentence earns its place. Cut generic advice.
+- **Consistent tone.** Technical but direct. No corporate language.
+- **ADRs always have:** decision, alternatives considered, reason for choice.
+- **API contracts always have:** method, path, headers, body, all response codes.
+- **Onboarding always ends with:** "first task" — something concrete the new dev can do.
+- **README always has:** one-command setup that actually works.
+
+---
+
+## Updating existing documents
+
+When the user asks to update a doc (e.g. "update the architecture doc with
+this new decision"):
+
+1. Ask for the existing file if not already in context
+2. Identify what changed
+3. Make targeted updates — do not rewrite sections that haven't changed
+4. Add a changelog entry at the top of the file if the change is significant:
+
+```markdown
+> **Atualizado em [data]:** [o que mudou em uma linha]
+```

package/skills/project-docs/references/architecture.md

@@ -0,0 +1,119 @@
+# Template — ARQUITETURA.md
+
+## Structure
+
+```markdown
+# Arquitetura Técnica — [Nome do Projeto]
+
+> Documento de alto nível com decisões de arquitetura, estrutura de
+> repositórios e contratos entre sistemas.
+> Para detalhes de implementação, consultar o README de cada serviço/app.
+
+---
+
+## Sumário
+[numbered list with anchor links]
+
+---
+
+## 1. Visão Geral do Sistema
+[ASCII diagram showing all components and their connections]
+[Brief explanation of each component]
+
+### Fluxo principal
+[Step-by-step of the most important user journey through the system]
+
+---
+
+## 2. Repositórios / Estrutura de Código
+[repo structure with explanation of each folder/app]
+[monorepo OR multi-repo decision explained]
+
+### Convenções comuns
+[language, lint, env vars, commit format, branch strategy]
+
+---
+
+## 3. [Shared Package / Core Library]
+[if applicable: what goes here, what doesn't, import path]
+[code example of key shared types]
+
+---
+
+## 4. [Service/App 1]
+[path, runtime, framework, key libraries]
+[folder structure]
+[main endpoint groups or responsibilities]
+[key algorithms or business logic]
+
+---
+
+## 5. [Service/App 2]
+[same structure]
+
+---
+
+[repeat for each app/service]
+
+---
+
+## [N-2]. Comunicação em Tempo Real
+[technology choice and why]
+[rooms/channels structure]
+[event catalog: event name | direction | payload]
+[fallback strategy]
+
+---
+
+## [N-1]. Integrações Externas
+[table: service | purpose | SDK/lib | notes]
+[auth strategy for each]
+[webhook security approach]
+
+---
+
+## [N]. Banco de Dados
+[SGBD, ORM/query strategy]
+[schema of main tables]
+[key indexes]
+[any special extensions (PostGIS, etc.)]
+
+---
+
+## [N+1]. Infraestrutura e Deploy
+[environments: local, staging, production]
+[production stack with justification]
+[environment variables list]
+[CI/CD approach]
+
+---
+
+## [N+2]. Decisões de Arquitetura (ADRs)
+
+### ADR-001: [Title]
+**Decisão:** [what was decided]
+**Motivo:** [why — specific to this project, not generic]
+**Alternativas consideradas:** [what else was evaluated and why rejected]
+
+[repeat for each ADR]
+
+---
+
+## [N+3]. Estratégia de Crescimento do Time
+[how the architecture evolves as team grows]
+[what stays the same, what changes at each stage]
+
+---
+*[footer]*
+```
+
+## Rules specific to ARQUITETURA.md
+
+- Every ADR must have: decision, reason, AND alternatives considered
+- Alternatives must explain WHY they were rejected — not just listed
+- ASCII diagrams must be accurate — don't draw connections that don't exist
+- Environment variables section must be complete — the list should be enough
+  to write a real `.env` file
+- No ADR without a "why" that is specific to this project's context
+- When a decision was reversed or updated, add a note to the original ADR
+  rather than deleting it — the history of thinking is valuable

package/skills/project-docs/references/other-docs.md

@@ -0,0 +1,295 @@
+# Template — README.md
+
+## Structure
+
+```markdown
+# [Project Name]
+
+> [One sentence: what this is and what problem it solves]
+
+---
+
+## O que é
+[2-3 sentences expanding on the tagline. What it does, who it's for.]
+
+## Stack
+[list of main technologies — keep it short, link to ARQUITETURA.md for details]
+
+## Pré-requisitos
+[exact versions required: Node 20+, Docker, etc.]
+
+## Como rodar localmente
+
+\`\`\`bash
+# 1. Clone
+git clone [url]
+cd [project]
+
+# 2. Instalar dependências
+[exact command]
+
+# 3. Configurar variáveis de ambiente
+cp .env.example .env
+# Editar .env com suas credenciais
+
+# 4. Subir serviços (banco, redis, etc.)
+[exact command]
+
+# 5. Rodar migrations
+[exact command]
+
+# 6. Iniciar
+[exact command]
+\`\`\`
+
+> Abrir [URL] no browser / ou rodar o app com `npx expo start`
+
+## Estrutura do repositório
+[tree of top-level folders with one-line description each]
+
+## Documentação
+| Documento | Descrição |
+|---|---|
+| [PROJETO.md](./PROJETO.md) | Visão de produto e roadmap |
+| [ARQUITETURA.md](./ARQUITETURA.md) | Decisões técnicas e stack |
+| [API.md](./API.md) | Contratos dos endpoints |
+| [ONBOARDING.md](./ONBOARDING.md) | Guia para novos devs |
+
+## Como contribuir
+[branch naming, PR process, commit format]
+
+## Licença
+[license type]
+```
+
+## Rules specific to README.md
+
+- "Como rodar localmente" must work — test every command mentally
+- No step can be "configure X" without saying exactly how
+- Keep it short — link to other docs for detail
+- First heading after title must be visible without scrolling
+
+---
+
+# Template — API.md
+
+## Structure
+
+```markdown
+# API Reference — [Project Name]
+
+> Base URL: `https://api.[domain].com.br`
+> Auth: Bearer JWT em todas as rotas (exceto `/auth/*`)
+
+---
+
+## Autenticação
+
+[explain JWT flow briefly, link to auth endpoints]
+
+---
+
+## [Module 1 — e.g. Auth]
+
+### POST /auth/send-otp
+[description: one sentence]
+
+**Request**
+\`\`\`json
+{
+  "phone": "+5511999999999"
+}
+\`\`\`
+
+**Responses**
+
+| Status | Descrição | Body |
+|---|---|---|
+| 200 | Código enviado | `{ "message": "Código enviado" }` |
+| 400 | Telefone inválido | `{ "error": "Formato inválido" }` |
+| 429 | Rate limit | `{ "error": "Muitas tentativas" }` |
+
+---
+
+[repeat for each endpoint, grouped by module]
+
+---
+
+## Erros comuns
+
+| Código | Significado | O que fazer |
+|---|---|---|
+| 401 | Token inválido ou expirado | Renovar via /auth/refresh |
+| 403 | Sem permissão | Verificar role do usuário |
+| 422 | Dados inválidos | Ver campo `error` na resposta |
+| 429 | Rate limit atingido | Aguardar e tentar novamente |
+```
+
+## Rules specific to API.md
+
+- Every endpoint must show ALL possible response status codes
+- Request body must show exact field names and types
+- Authentication requirement must be explicit for each endpoint
+- Group endpoints by domain/module, not alphabetically
+- Include at least one curl example per module
+
+---
+
+# Template — ONBOARDING.md
+
+## Structure
+
+```markdown
+# Onboarding — [Project Name]
+
+> Guia para novos desenvolvedores. Tempo estimado para estar rodando: **[X horas]**.
+
+---
+
+## O que é esse projeto
+[2-3 sentences — assume zero context]
+
+## Arquitetura em 5 minutos
+[high-level overview: what are the apps, how do they connect]
+[link to ARQUITETURA.md for depth]
+
+## Setup do ambiente
+[link to README.md — don't duplicate the setup steps]
+
+## Estrutura do código
+
+### Como o código está organizado
+[explain the main patterns: modules, services, stores, etc.]
+
+### Onde encontrar o quê
+| O que você precisa | Onde está |
+|---|---|
+| Lógica de corridas | `apps/api/src/modules/rides/` |
+| Telas do passageiro | `apps/passenger/app/` |
+| Tipos compartilhados | `packages/shared/` |
+
+---
+
+## Fluxo principal (passo a passo no código)
+[walk through the most important feature end-to-end, with file paths]
+[e.g.: "Uma corrida começa em RideController.ts linha 42, passa por..."]
+
+---
+
+## Padrões do projeto
+
+### Git
+[branch naming, commit format, PR process]
+
+### TypeScript
+[key conventions used in this codebase]
+
+### Testes
+[how to run, where they live, what's expected to be tested]
+
+---
+
+## Decisões que podem surpreender
+[list of non-obvious decisions with brief explanation]
+[e.g.: "Usamos $queryRaw para queries de localização porque PostGIS..."]
+
+---
+
+## Primeira tarefa
+[a concrete, small, self-contained task the new dev can do on day 1]
+[e.g.: "Adicione o campo `photoUrl` ao endpoint GET /users/me"]
+[link to a real GitHub issue if possible]
+
+---
+
+## Dúvidas frequentes
+[Q&A format for questions that come up repeatedly]
+```
+
+## Rules specific to ONBOARDING.md
+
+- "Primeira tarefa" is mandatory — onboarding without a concrete task is incomplete
+- "Decisões que podem surpreender" prevents the same questions every time
+- Setup steps must link to README, never duplicate them
+- Time estimate at the top must be honest — don't say 30 min if it takes 3 hours
+- Fluxo principal must include actual file paths, not just module names
+
+---
+
+# Template — SPRINTS.md
+
+## Structure
+
+```markdown
+# Planejamento de Sprints — [Project Name]
+
+> Histórico e planejamento de sprints. Issues detalhadas no GitHub Milestones.
+
+---
+
+## Status atual
+**Sprint em andamento:** Sprint [N] — [Nome]
+**Período:** [data início] → [data fim]
+**Progresso:** [X/Y issues concluídas]
+
+---
+
+## Sprint [N] — [Nome] (atual)
+
+**Objetivo:** [one sentence — what "done" looks like for this sprint]
+**Período:** [datas]
+
+### Por app
+| App | Issues | Concluídas |
+|---|---|---|
+| api | [N] | [N] |
+| passenger | [N] | [N] |
+| driver | [N] | [N] |
+| admin | [N] | [N] |
+
+### Destaques
+[bullet list of most important deliverables]
+
+### Impedimentos
+[anything blocking progress — honest assessment]
+
+---
+
+## Sprint [N-1] — [Nome] (concluído)
+
+**Objetivo:** [what was planned]
+**Resultado:** [what actually shipped — be honest about gaps]
+**Retrospectiva:**
+- O que funcionou bem: [...]
+- O que melhorar: [...]
+
+---
+
+[repeat for previous sprints, newest first]
+
+---
+
+## Backlog (próximos sprints)
+
+### Sprint [N+1] — [Nome previsto]
+[bullet list of planned items — not detailed yet]
+
+---
+
+## Definição de "Pronto"
+[checklist that every issue must pass before being marked done]
+- [ ] Código revisado (se time > 1 dev)
+- [ ] Testes passando
+- [ ] Sem erros de TypeScript
+- [ ] Testado em staging
+- [ ] Documentação atualizada se necessário
+```
+
+## Rules specific to SPRINTS.md
+
+- Retrospectiva section is mandatory for completed sprints — no sprint is
+  "completed" without honest reflection
+- "Resultado" must distinguish what was planned vs what shipped
+- Impedimentos must be honest — this is a working document, not a report
+- Definition of Done must match the actual team process
+- Link to GitHub Milestone for each sprint

package/skills/project-docs/references/project.md

@@ -0,0 +1,102 @@
+# Template — PROJETO.md
+
+## Structure
+
+```markdown
+# Plano de Projeto — [Nome do Projeto]
+
+> **Status:** [fase atual]
+> **Versão:** [número]
+> **Modelo:** [tipo de negócio, ex: Marketplace B2C]
+> **Contexto:** [uma frase descrevendo o contexto único do projeto]
+
+---
+
+## Sumário
+[numbered list of all sections with anchor links]
+
+---
+
+## 1. Sumário Executivo
+[2-3 paragraphs: what the product is, who it's for, what problem it solves]
+
+[info table with: tipo de produto, modelo de receita, fase atual, perfil do time,
+mercado-alvo, prazo estimado para MVP]
+
+---
+
+## 2. Problema & Oportunidade
+
+### 2.1 Problema a resolver
+[bulleted list of real pains — not generic market observations]
+
+### 2.2 Validação necessária
+[alert box: what needs to be validated before building]
+
+---
+
+## 3. Proposta de Valor
+
+### 3.1 Para [primary user]
+[bulleted list of concrete benefits]
+
+### 3.2 Para [secondary user, if marketplace]
+[bulleted list of concrete benefits]
+
+### Diferencial
+[what makes this product different — specific, not generic]
+
+---
+
+## 4. Visão Geral do Produto
+
+### 4.1 Componentes do sistema
+[table: component | description]
+
+### 4.2 Funcionalidades do MVP
+[grouped by user type — only what's needed for first working version]
+
+---
+
+## 5. Roadmap — [N] Fases
+[one section per phase with: name, duration, goals, key deliverables]
+[highlight which phase is current]
+
+---
+
+## 6. Modelo de Negócio
+
+### Fontes de receita
+[table: fonte | descrição | timing]
+
+### Estrutura de custos
+[bulleted list of main cost drivers]
+
+---
+
+## 7. Regulamentação & Compliance
+[only if relevant — legal requirements, certifications, data privacy]
+
+---
+
+## 8. Principais Riscos
+[table: risco | probabilidade | mitigação]
+
+---
+
+## 9. Próximos Passos
+[numbered checklist — concrete actions, not vague goals]
+[each item starts with [ ] for checkbox format]
+
+---
+*[footer: how document is maintained]*
+```
+
+## Rules specific to PROJETO.md
+
+- Roadmap phases should have realistic durations — don't compress timelines
+- Risks table must have mitigation for every risk, not just identification
+- Próximos Passos must be actionable in the next 2 weeks
+- Business model must include a note on benchmark (what competitors charge)
+- Never include features in the MVP section that aren't strictly necessary
+  for the core workflow to function end-to-end

package/src/cli.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { initCommand } from './commands/init.js';
+import { listCommand } from './commands/list.js';
+import { addCommand } from './commands/add.js';
+import { showCommand } from './commands/show.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+
+program
+  .name('claude-skills')
+  .description('Manage Claude AI skills for your projects')
+  .version(pkg.version);
+
+program
+  .command('init')
+  .description('Initialize skills in the current project (.claude/skills/)')
+  .option('-s, --skill <name>', 'Initialize a specific skill only')
+  .action(initCommand);
+
+program
+  .command('list')
+  .description('List all available skills')
+  .action(listCommand);
+
+program
+  .command('add <skill>')
+  .description('Add a specific skill to the current project')
+  .action(addCommand);
+
+program
+  .command('show <skill>')
+  .description('Print a skill\'s SKILL.md to stdout')
+  .action(showCommand);
+
+program.addHelpText('after', `
+${chalk.bold('Examples:')}
+  ${chalk.cyan('claude-skills init')}                  Copy all skills to .claude/skills/
+  ${chalk.cyan('claude-skills init -s project-docs')}  Copy only project-docs skill
+  ${chalk.cyan('claude-skills list')}                  Show available skills
+  ${chalk.cyan('claude-skills add github-sprint')}     Add a specific skill
+  ${chalk.cyan('claude-skills show project-docs')}     Print SKILL.md to stdout
+
+${chalk.bold('Usage with Claude:')}
+  After running ${chalk.cyan('init')}, upload the files from ${chalk.cyan('.claude/skills/')}
+  in your Claude conversation, or reference them by path.
+`);
+
+program.parse();

package/src/commands/add.js

@@ -0,0 +1 @@
+export { addCommand } from './list.js';