farhanhidayatulhaq-max/GAMUKIS / .agents/skills/skill-ai-engineering
skill-ai-engineering
VerifiedUse 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
- 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. - Define testable requirements: inputs, expected outputs, constraints, failure modes, and acceptance criteria.
- Audit existing integrations, request/response formats, model configurations, logging, caching, and error mechanisms. Do not introduce a secondary client or gateway without strong justification.
- Establish capability requirements prior to model selection: text, vision, tool calling, structured output, context window, and provider constraints.
- 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.
- Decouple prompt/instruction templates from business logic where project architecture supports it. Version critical prompts when required for evaluation and rollback.
- Validate model outputs before using them to trigger actions, persist to databases, or return product responses. Treat model output as untrusted input.
- Explicitly handle timeouts, rate limits, malformed output, provider errors, and cancellations. Restrict retry attempts and avoid blindly re-executing non-idempotent operations.
- 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.
- 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |