Updating the Quality Skills

The skills that improve spec quality and the rules that detect sensitive data live in the microservice-api-docs plugin, in the kalt-ai-plugin-marketplace repository. This page explains how to change them, test your change on a real microservice, and get it approved.

What You Can Change

All paths are relative to the root of kalt-ai-plugin-marketplace:

Step by Step

1. Clone the marketplace

git clone https://github.com/kaltura/kalt-ai-plugin-marketplace
cd kalt-ai-plugin-marketplace

2. Open Claude

claude

3. Ask Claude to edit the plugin

Describe the change. For example, to improve a fix skill:

Edit the plugin 'microservice-api-docs'. In the 'fix-nestjs' skill, also add descriptions to query parameters declared with @ApiQuery.

Or to add a sensitive data rule:

Edit the plugin 'microservice-api-docs'. In references/sensitive-data-rules.md, add a rule that flags AWS account IDs in examples and descriptions.

4. Test it on a microservice

Open Claude in a microservice repo that uses the stack you changed, and load the plugin from your local clone instead of the published version:

cd <path-to-microservice-repo>
claude --plugin-dir <path-to-marketplace>/plugins/microservice-api-docs

Then run the skill you changed:

/microservice-api-docs:quality        # sensitive data rules and scoring
/microservice-api-docs:fix-nestjs     # NestJS fix skill
/microservice-api-docs:fix-fastapi    # FastAPI fix skill

Don't commit the changes the fix skill makes to the microservice repo. That run only tests the skill.

To see how the changed specs look on the docs site, preview them locally.

5. Create a PR

When the change works, go back to the Claude session in kalt-ai-plugin-marketplace and ask it to open the PR:

Create a PR with my changes to the microservice-api-docs plugin.

6. Ask for review

Ask Yossi Papiashvilli, the plugin owner, to review and approve the PR. Once it is merged, the next staging and production deploys use the updated skills.

Previewing Spec Changes Locally

You can render a microservice's specs on your machine before anything is deployed: first publish them into a local clone of platform-content-registry, then run the docs site against that clone.

Update the registry from your microservice repo

1. Clone the registry:

   git clone https://github.com/kaltura/platform-content-registry
   cd platform-content-registry

2. Create the script's .env from the example:

   cp scripts/update-microservices-spec/.env.example scripts/update-microservices-spec/.env

   Uncomment the block for your microservice and set MS_PATH to your local microservice repo:

   MS_PATH=/Users/you/dev/github/kaltura/ovp-agentic-api
   DOMAIN=agentic-api

3. Run the update script:

   ./scripts/update-microservices-spec/update.sh

   It generates the specs from the microservice repo, copies them into microservices/servers/<domain>/<version>/, and points stagingVersion to that version.

The script starts the microservice to generate the specs, so the microservice repo needs its dependencies installed and its .env in place.

The version is named after the microservice's current commit (<commit-date>-<commit>), and an existing version is never overwritten. If you change the microservice again without committing, delete that version folder in your local registry before running the script again.

Run the docs site locally

1. Clone the docs site and install its dependencies:

   git clone https://github.com/kaltura/docs-kaltura-com
   cd docs-kaltura-com
   npm install

   If you already have a clone, pull the latest main instead:

   git checkout main
   git pull origin main

2. Create .env from the example and point it to your local registry:

   cp .env.example .env

   CONTENT_REGISTRY_PATH=/Users/you/dev/github/kaltura/platform-content-registry

3. Start the dev server:

   npm run dev

4. Every time you update the registry again or pull main, stop the dev server (Ctrl+C) and run npm run dev again. It doesn't pick up those changes on its own.