Working With AI Agents

AI coding agents can help you explore Ovok, plan an integration, and implement application code. They work best when you give them the context of your application and ask them to verify platform behavior against the current Ovok documentation.

Runtime AI is a different topic

Building AI into your application at runtime, such as clinical summarization, agents acting on patient data, or MCP-driven workflows, is a different topic; see Build with AI on Ovok for Ovok's documented $ai feature. This page is about using AI to develop on Ovok.

What the Ovok skill does

The Ovok skill gives a coding agent a repeatable way to work with Ovok. It tells the agent to:

• inspect your application repository, its AGENTS.md instructions, framework, and existing code patterns before making changes;
• check the current Ovok docs and available source for the API route, FHIR resource, SDK method, request and response shape, and error behavior involved;
• identify project setup requirements, including authentication, access policies, feature switches, settings, and their prerequisites;
• use the Console for project administration, such as settings, email templates, CMS content, and billing, and use APIs or SDKs for application integrations;
• preserve tenant and patient boundaries, keep secrets and clinical data out of client code and logs, and flag behavior it cannot verify;
• report the implementation, setup a project administrator must complete, and any remaining assumptions.

The skill is guidance for the coding agent. It does not sign in to Ovok, grant the agent access to a project, create credentials, or change project settings by itself. The agent can only inspect or change files and systems allowed by the tools and permissions in your development environment.

Install the Ovok skill

Install it from the repository where you plan to use your coding agent:

npx skills add Actimi/ovok-landing --skill ovok

The Skills CLI detects the current coding agent. To choose Codex explicitly, run:

npx skills add Actimi/ovok-landing --skill ovok --agent codex

The default installation is for the current project. To install it for your user account instead, add --global:

npx skills add Actimi/ovok-landing --skill ovok --global

List installed skills to confirm it is available:

npx skills ls

The skill source is in the Actimi/ovok-landing repository. After installing it, open your application repository in the agent. Skills-enabled agents may select it automatically for relevant work; you can also ask explicitly: “Use the ovok skill for this task.”

Give the agent the right docs

Ovok Docs publishes Markdown for AI tools alongside each rendered page:

• Start with the docs index for AI agents. It explains how the docs are organized and links to every page.
• For a focused task, give the agent the page-specific Markdown URL, such as FHIR Basics or Settings and features. The same pattern works for every docs page: /path/to/page/llms.txt.
• For broad discovery, use the complete docs bundle. It contains the full documentation and is large; for most implementation tasks, the index and a few relevant pages are easier for an agent to work with.

For example, you can ask: “Read the Ovok docs index, then fetch the page-specific Markdown for authentication, FHIR resources, and settings that apply to this workflow. Use those docs as the source of truth and cite the relevant pages in your plan.”

Give the agent enough context

“Build something with Ovok” leaves important decisions open. Describe the product workflow and the people who will use it. Include:

• The user and their role: for example, a patient recording a blood-pressure reading or a practitioner reviewing observations.
• The workflow: what starts it, what the user does, and what should happen next.
• The data: which clinical concepts, devices, or records are involved, and which system is authoritative.
• Access rules: who may create, read, update, or share each record.
• The application: its framework, existing authentication, and relevant repository conventions.
• The environment: whether the work is a code example, sandbox integration, or production change.
• The expected result: screens or API behavior to implement, plus how you will decide it is complete.

For example:

Use the ovok skill. In this repository, add a practitioner view for reviewing a patient's recent blood-pressure observations.

First inspect the app structure and repository instructions. Then check the current Ovok docs for authentication, the relevant FHIR resources and search parameters, and any project setup required for this workflow. Use the existing app patterns. Keep tokens and patient data out of browser logs. Before coding, summarize the endpoint and access-policy assumptions; after coding, list the files changed and any Console setup an admin still needs to do. Use sandbox URLs in examples.

You can ask the agent to explain or plan a workflow before it edits files. For example: “Map this user journey to Ovok resources and endpoints. Show the required settings, features, access policies, and failure cases, and cite the docs you used. Do not change code yet.” This is useful when the data model or permissions need review first.

A practical workflow

For a feature that uses Ovok, work through these steps with the agent:

1. Map the user journey. Identify the actors, project, records, and actions. Decide what the patient, practitioner, and application can each do.
2. Confirm the Ovok contract. Have the agent find the exact docs for authentication, FHIR basics, FHIR R4 resources, Ovok primitives, settings and features, and the Web SDK or Native SDK, as relevant. Ask it to distinguish standard FHIR behavior from Ovok-specific operations and to verify request, response, and error details.
3. Check project setup. Identify required feature switches, settings, access policies, app URLs, and other prerequisites. The skill warns about common configuration traps: for example, a feature-list PATCH replaces the complete list, an unset setting may behave differently from the value returned by GET, and a setting does not replace an access policy.
4. Separate Console work from code. Project creation and administration—settings, email templates, CMS content, billing, memberships, and access configuration—belong in the OVOK Console. FHIR requests and application behavior belong in your application code through documented APIs or SDKs. Ask the agent to list Console steps separately from code changes.
5. Implement against the existing application. Keep patient and project scope explicit. Put credentials on the server where required. Use the sandbox for example requests and test data; do not put production tokens or real patient data in prompts, fixtures, or logs.
6. Review the result. Check changed files, FHIR version, query parameters, resource references, permissions, and error handling. Complete any Console setup, then exercise the workflow with appropriate test accounts before using it with patients.

Review AI-generated changes

AI gets things wrong; review its output

Agents are fast and often right, but they hallucinate fields, mix FHIR versions, and produce plausible-but-wrong code. Treat everything an agent writes as a draft to review, not a finished answer. Apply extra scrutiny to anything that affects security or data exposure, especially access policies, ProjectMembership scopes, and PHI handling.

Ask the agent to show the docs behind an endpoint or behavior it relies on. Review authorization and data access yourself, and test important cases—including unauthorized access, missing configuration, invalid input, and partial or failed writes. Do not treat a successful build as proof that a clinical workflow or permission model is correct.

The skill also asks agents to keep product claims precise: Ovok is not described as a certified medical-device platform, and the regulatory status of an application depends on its own intended purpose. For Signals behavior, verify the current Signals documentation and your product's requirements.