Skip to content

farhanhidayatulhaq-max/GAMUKIS / .agents/skills/skill-ai-engineering

skill-ai-engineering

Verified

Use when designing or implementing AI features in Gamukis, including model integration, prompts, tool calling, retrieval/RAG, output evaluation, token/context efficiency, and 9Router gateway usage.

AI Engineering — Gamukis

Purpose

Build testable, secure, context-efficient, and measurable AI features without duplicating existing routing capabilities. This skill addresses AI feature engineering; it is not a directive to always employ a specific model.

When to Use

Use when the task involves:

  • LLM or multimodal model integrations;
  • prompt templates and structured output schemas;
  • tool/function calling or agent workflows;
  • retrieval, embeddings, document search, or RAG architectures;
  • evaluating output quality, safety, latency, token consumption, and cost;
  • utilizing 9Router as a model gateway, where relevant to the task.

Operating Procedures

  1. Read AGENTS.md, the applicable PRD/dispatch, and related documentation. Determine whether the task modifies product features, agent workflows, or internal 9Router code; these three areas have distinct boundaries.
  2. Define testable requirements: inputs, expected outputs, constraints, failure modes, and acceptance criteria.
  3. Audit existing integrations, request/response formats, model configurations, logging, caching, and error mechanisms. Do not introduce a secondary client or gateway without strong justification.
  4. Establish capability requirements prior to model selection: text, vision, tool calling, structured output, context window, and provider constraints.
  5. When 9Router is used, adhere to approved endpoints and configurations. Rely on 9Router to manage combos, provider routing, and fallback policies according to its existing configuration; do not construct parallel combo engines in application code.
  6. Decouple prompt/instruction templates from business logic where project architecture supports it. Version critical prompts when required for evaluation and rollback.
  7. Validate model outputs before using them to trigger actions, persist to databases, or return product responses. Treat model output as untrusted input.
  8. Explicitly handle timeouts, rate limits, malformed output, provider errors, and cancellations. Restrict retry attempts and avoid blindly re-executing non-idempotent operations.
  9. Evaluate quality in tandem with cost and latency. Employ fixed test sets, acceptance criteria checks, or reviewer rubrics; never rely on a model to self-evaluate its own output.
  10. Execute permitted tests and clearly distinguish between mocked tests versus live network calls.

Routing, Tokens, and Cost

  • Select models based on required capabilities and minimum acceptable quality first, followed by cost optimization.
  • Do not route all tasks exclusively to the cheapest model; failure rates and repeated attempts increase total expenditure.
  • Distinguish between measured costs, estimates, and unavailable cost telemetry. Do not treat unknown costs as zero.
  • Measure cost per successfully completed task, not merely tokens per individual request.
  • Leverage existing token and context optimization mechanisms. Do not introduce redundant compressors without prior audit.
  • Do not strip constraints, essential code snippets, paths, stack traces, errors, or required tool outputs merely to compress tokens.
  • If context transformation fails, prioritize proceeding with original content under existing fail-open designs.

Security and Privacy

  • Never embed API keys, OAuth tokens, passwords, or credentials in prompts, source code, fixtures, or logs.
  • Do not transmit user data or private source code to external providers unless explicitly authorized by project configuration and policy.
  • Minimize logging of full prompts and sensitive outputs; log operational reason codes where sufficient.
  • Treat model outputs, retrieved documents, and tool execution outputs as untrusted input; validate before invoking system commands or modifying data.
  • Never grant models direct authority to bypass authentication, authorization permissions, or server-side security guards.
  • Do not store raw chain-of-thought traces. Persist only necessary final outputs and approved operational telemetry.

Gamukis AI Question Generation Integration Rules

Apply these rules when designing or implementing PDF-based question generation or another AI question workflow in Gamukis. They supplement AGENTS.md, the approved feature PRD, and the relevant frontend, backend, database, and game-development skills; they do not authorize implementation before the PRD gate is satisfied.

Preserve the Existing Frontend and Game Flow

  • Trace the active question lifecycle from class and subject selection through gamePage, inGame, the question modal, answer recording, and game history before proposing integration changes.
  • Keep the browser-to-Express boundary. The frontend must not call FastAPI or a model provider directly, and must not contain service credentials.
  • Do not put model calls, PDF parsing, or AI job polling inside the gameplay loop or on each question-modal opening. Resolve the question set before or at session start; gameplay must consume a prepared question DTO.
  • Preserve existing routes, response fields, answer recording, game-session behavior, and manual question sources unless an approved PRD explicitly defines a backward-compatible migration.
  • Use the existing frontend data-access conventions. Do not create a parallel API client or question source layer without an approved blueprint.
  • When the requested class or subject has no published questions, return a clear empty/unavailable state. Never silently substitute questions from another subject or an unrelated default pool.
  • Carry stable class and subject identifiers from selection through question retrieval and session results. Display labels are not canonical identifiers.
  • Keep loading, empty, and error states explicit. A FastAPI, model-provider, or network failure must not block unrelated class navigation or existing gameplay behavior.

Keep Express Authoritative and FastAPI Isolated

  • Express remains the public API boundary and authoritative owner of authentication, authorization, membership checks, question lifecycle, class/subject assignments, and durable state.
  • FastAPI is an internal processing service for PDF extraction, chunking/retrieval as approved, generation, and candidate validation. It must not directly publish to production or own student-facing question reads.
  • Treat FastAPI as an optional dependency for gameplay availability. Use bounded timeouts, bounded retries, idempotency keys, cancellation/state handling, and durable job state. Do not rely on in-process background tasks as the only record of long-running work.
  • Authenticate internal Express-to-FastAPI communication, restrict network exposure, validate callback/job identity, and never trust a client-supplied role or user ID forwarded through the AI service.
  • Do not make database, Redis, or Firebase dual writes from FastAPI. Persist lifecycle and publication changes through the designated Express/backend data layer.

Separate Candidate, Test, and Production Questions

  • Keep uploaded documents, generated candidates, Admin test results, reviewed drafts, and published questions distinguishable in durable records and access policies.
  • If MongoDB is selected for AI workflow data, configure separate Test and Production environments with distinct database names and credentials; use separate clusters when stronger isolation is required. Test credentials and jobs must be unable to access Production MongoDB.
  • Define MongoDB's Production role narrowly. MySQL remains the canonical source for published questions used by classes and gameplay unless an approved PRD changes the source of truth with a migration and consistency plan.
  • Treat MongoDB-to-MySQL publishing as a cross-database workflow, not an atomic transaction. Make promotion idempotent, auditable, and retry-safe; do not expose a candidate to students until the MySQL publish and class/subject assignment succeed.
  • Admin test runs and generated candidates must never appear in student question endpoints, class pools, game sessions, or production caches before an explicit authorized publish action.
  • Publish only selected and validated questions. Record the publishing actor, source/generation metadata, timestamp, and exact class/subject assignment as defined by the approved PRD.
  • Enforce Admin, Teacher, and Student permissions on the Express backend for every read and mutation. Hiding UI controls is not authorization. Admin privileges must be explicit in the permission model; membership limits must not accidentally override or broaden role permissions.
  • Define teacher-to-class authorization explicitly. Never infer class ownership from a frontend route, selected card, or request body alone.
  • After a successful publish transaction, invalidate or version the relevant production question caches. Cache keys must include all dimensions that affect eligibility, at minimum class and subject; candidate/test data must not share student-pool cache keys.

Validate Generated Content Before Use

  • Treat PDF contents, extracted text, retrieved passages, model output, and callbacks as untrusted input. A document's embedded instructions must never override system policy, permissions, or the generation task.
  • Validate generated questions against a strict versioned schema before persistence or publication, including required question text, supported answer format, option constraints, exactly valid correct-answer references, subject, difficulty, and source evidence/page references where available.
  • Reject malformed, incomplete, duplicated, unsupported, or out-of-scope items from publication; retain them only as isolated diagnostics if policy permits.
  • Never expose correct answers or explanations through student question-delivery responses before the answer is submitted. Follow the approved grading contract and keep answer validation authoritative on the backend.
  • Use reviewer approval and measurable evaluation criteria. A model's confidence or self-evaluation alone is not evidence that an item is correct or safe to publish.
  • Define PDF type/size/page limits, private storage, access control, retention/deletion, and provider data-sharing policy before sending extracted content to any external model.

Required Integration Checks

  • Before implementation, verify the active question API callers, local fallback behavior, class-detail data source, answer/history persistence, role middleware, membership entitlement checks, storage limits, Redis cache behavior, and deployment configuration.
  • The approved PRD and API contract must define canonical class/subject IDs, manual/AI shared question DTO, job states and idempotency behavior, candidate-to-publish transitions, student answer-key exposure, error semantics, cache invalidation, and compatibility with existing game sessions.
  • Test that existing manual questions remain playable when FastAPI is unavailable; candidates are invisible to students before publish; published questions are scoped to the exact class and subject; empty pools do not cross-fallback; repeated job requests do not duplicate candidates; and student responses do not reveal answer keys.
  • Distinguish mocked integration checks from live FastAPI/model-provider evaluations. Do not run paid or external-data evaluations without authorization and approved configuration.

Constraints

  • Do not modify internal code under 9router/ unless the dispatch explicitly authorizes it.
  • Do not alter providers, default models, combos, costs, or production fallback policies without approval.
  • Do not introduce agent frameworks, vector databases, or new dependencies before auditing existing project alternatives.
  • Do not claim cost savings or quality improvements without empirical measurement.
  • Do not execute paid or live network evaluations without explicit authorization if they incur financial cost or transmit data externally.

Completion Criteria

  • Requirements and acceptance criteria are measurable and verified.
  • Model outputs are validated prior to consumption by downstream systems.
  • Error handling, retries, and cancellation are properly bounded.
  • Evaluation encompasses quality, cost, and latency.
  • Secrets and sensitive data are excluded from logs and artifacts.
  • Handoff explicitly documents utilized models and configurations, evaluation metrics, executed tests, and unverified limitations.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall