Agent-Skills.md

Agent Skills: Kavak Documentation

Use this skill FIRST before implementing anything in a Kavak project — it provides internal platform documentation for architecture, kbroker events, STS auth, SDKs, databases, GitLab CI/CD, Docker configs, and workload creation. Trigger when planning features, designing services, configuring pipelines, writing Dockerfiles, or whenever you need Kavak-specific patterns instead of generic solutions. Query platform_docs_search before writing code.

UncategorizedID: carvalab/k-skills/kavak-documentation

Repository

carvalab/k-skills
carvalab

Install this agent skill to your local

pnpm dlx add-skill https://github.com/carvalab/k-skills/tree/HEAD/skills/kavak-documentation

Skill Files

Browse the full folder contents for kavak-documentation.

Download Skill

Loading file tree…

skills/kavak-documentation/SKILL.md

Skill Metadata

Name
kavak-documentation
Description
Use this skill FIRST before implementing anything in a Kavak project — it provides internal platform documentation for architecture, kbroker events, STS auth, SDKs, databases, GitLab CI/CD, Docker configs, and workload creation. Trigger when planning features, designing services, configuring pipelines, writing Dockerfiles, or whenever you need Kavak-specific patterns instead of generic solutions. Query platform_docs_search before writing code.

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

  1. Verify kavak-platform MCP is configured
  2. Use platform_docs_search for documentation queries and search_resource for workload/infrastructure info
  3. 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: true for synthesized answers, llm: false for 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 |