kavak-documentation
Kavak Documentation
Search Kavak's internal documentation first via platform_docs_search and search_resource MCP tools, then complement with other sources.
Related Skills:
backend-development- After finding Kavak patterns, implement using backend best practices- Check
references/folder for detailed Kavak implementation guides
Core Principle
Search Kavak docs first, always. Internal platform knowledge reduces agent errors and ensures proper Kavak patterns.
When to Use
- Planning new features or architecture
- Architecture, kbroker, STS, SDKs, databases
- Creating new services/workloads (Go, TypeScript, Python, Java)
- GitLab CI/CD pipelines and configurations
- Docker/container configurations
- Development workflow, logs, metrics best practices
- Kavak CLI usage/installation
Quick Start
- Verify
kavak-platformMCP is configured - Use
platform_docs_searchfor documentation queries andsearch_resourcefor workload/infrastructure info - Complement results with other tools as needed
Workflow
1. Check MCP Availability
Ensure kavak-platform MCP server is enabled. If MCP is unavailable, fall back to: searching kavak-it repos via gitlab_code_search/gitlab_file_content, or checking the project's existing patterns as the next best source of truth.
2. Query Documentation
Rules for platform_docs_search:
- One question per call (avoid compound questions)
- Use
llm: truefor synthesized answers,llm: falsefor raw doc chunks - Run multiple queries in parallel when you have several questions
Good queries:
"How to create a new Go workload?"
"What is kbroker and how to publish events?"
"How does STS authentication work?"
"What are the logging best practices?"
"How to configure GitLab CI pipeline for a Go service?"
"What is the standard Dockerfile for TypeScript services?"
"How to set up container registry in GitLab?"
Bad queries:
"Tell me about architecture, kbroker, and how to create services" # Too many topics
"Explain everything about the platform" # Too broad
3. Interpret Results
The response comes from an LLM - extract key information and apply to your context.
4. Complement if Needed
After Kavak docs, use additional sources:
- Context7 for external library docs
- Web search for general patterns
- Codebase search for existing implementations
Topics & References
| Topic | Example Query | Reference |
|---|---|---|
| Architecture | "What is the platform architecture?" | - |
| Kbroker (pub/sub) | "How to publish events with kbroker?" | references/kbroker.md |
| STS (auth) | "How does secure token service work?" | references/microservice-auth.md |
| Workload creation | "How to scaffold a new TypeScript service?" | references/workload-config.md |
| SDKs | "What internal SDKs are available?" | references/logging-metrics.md |
| Databases | "Database best practices for platform?" | - |
| Logs & Metrics | "How to implement structured logging?" | references/logging-metrics.md |
| CLI | "How to install and use kavak CLI?" | - |
| GitLab CI/CD | "How to configure GitLab pipeline for deployment?" | references/gitlab-ci.md |
| Docker | "What is the standard Dockerfile template?" | references/docker-images.md |
| Container Registry | "How to push images to Kavak registry?" | references/docker-images.md |
| Pipeline Stages | "What are the required CI stages for a service?" | references/gitlab-ci.md |
| Job Queues | "How to implement rate limiting?" | references/queues-ratelimit.md |
CI/CD & Docker Queries
When working with pipelines or containers, query these topics:
"What is the standard .gitlab-ci.yml template?"
"How to configure multi-stage Docker builds?"
"What are the required pipeline stages for production?"
"How to configure environment variables in CI?"
"What base images should I use for Go/TypeScript/Python?"
"How to set up automated testing in GitLab CI?"
"How to configure deployment to staging/production?"
Anti-Patterns
- Skipping Kavak docs and going straight to external sources
- Asking multiple questions in one query
- Writing overly long or vague queries
- Ignoring platform-specific patterns in favor of generic solutions
- Using generic Dockerfile templates instead of Kavak standards
- Copying CI configs from external projects without checking Kavak patterns
References
| Reference | When to Use |
|---|---|
references/kbroker.md |
Publish/subscribe events between services |
references/queues-ratelimit.md |
Job queues, rate limiting with River/pg-boss |
references/microservice-auth.md |
Authenticate between services (STS) |
references/gitlab-ci.md |
Set up kavak-it/ci-jobs v3 pipelines |
references/docker-images.md |
Build with docker-debian base |
references/workload-config.md |
Configure .kavak/ dir, cron jobs |
references/logging-metrics.md |
Use kvklog, kvkmetric SDKs |
More from carvalab/k-skills
code-review
Use this skill as the FINAL step after writing or modifying code — reviews for logic bugs, architecture violations, security issues, and performance problems. Trigger after completing a feature, fixing a bug, before merging, or when asked to "review this code", "check my changes", or "is this ready to merge". Fixes issues directly and runs quality gates (lint, typecheck, build, tests). Delegates style to automation, focuses on what matters.
38refactor-cleaner
Use this skill to find and remove dead code, unused dependencies, duplicate logic, and unused exports using detection tools (knip, depcheck, ts-prune, deadcode, staticcheck). Trigger on "clean up dead code", "remove unused", "find dead code", "reduce bundle size", "dependency audit", or when the codebase feels bloated. For simplifying living code (readability, naming, complexity reduction) without detection tools, use code-simplifier instead. Use this skill during maintenance windows or before major refactors.
36code-simplifier
Use this skill after writing or modifying code to simplify it — reduces complexity, eliminates redundancy, and improves naming while preserving exact behavior. Trigger after implementing a feature, after a refactor, or when asked to "clean up this code", "simplify this", "make this more readable", or "reduce complexity". Also use when code feels too nested, verbose, or hard to follow. For removing dead code and unused dependencies with detection tools (knip, ts-prune, deadcode), use refactor-cleaner instead.
24backend-development
Use this skill for ANY task in a Node.js/TypeScript or Go backend codebase — adding features, fixing bugs, refactoring, adding flows, modifying handlers, changing business logic, or writing new code. Trigger even when the task is vague like "add the flow to this", "implement this feature", "fix this", or "add X like Y" — if the project has go.mod, nest-cli.json, express routes, or server-side TypeScript, this skill applies. Covers REST APIs, PostgreSQL, Redis, authentication, job queues, events, microservices, Docker, CI/CD, Clean Architecture, SOLID, DRY, and code reuse patterns. When in doubt whether this is backend work, use this skill.
24doc-updater
Use this skill when documentation needs updating — after adding features, changing APIs, modifying architecture, or updating dependencies. Trigger on "update the docs", "generate codemap", "refresh the README", "document this", "update architecture docs", or when code changes make existing documentation stale. Generates codemaps from actual code, updates READMEs, architecture diagrams, and guides.
22frontend-development
Use this skill for ANY task in a Next.js or React frontend codebase — adding pages, building components, fixing UI bugs, styling, handling forms, fetching data, or modifying layouts. Trigger even when the task is vague like "add this feature", "fix the UI", "make this page", or "update the form" — if the project has next.config.*, React components, or client-side TypeScript, this skill applies. Covers App Router, Server Components, Server Actions, MUI styling, Zod validation, caching, and design quality. When in doubt whether this is frontend work, use this skill.
21