APIMatic Portal Skill
Let your AI coding assistant build, configure, preview, and host an APIMatic developer portal.
The apimatic-portal skill turns your AI coding assistant into a guided portal builder. Describe what you want, and the agent signs you in, scaffolds your src directory, starts a local preview, and edits apimatic.json, your pages, and nav.json for you, all from within Claude Code, Cursor, or Codex.
What the skill does
| Area | What the skill covers |
|---|---|
| Setup | Checks for Node.js 24 and APIMatic CLI v2 (and offers to upgrade from v1), signs you in through the browser with an API key fallback |
| Project scaffolding | Creates a src directory from the APIMatic sample portal and swaps in your API definition |
| Local preview | Starts, checks, restarts, and stops the preview server, and tells you whether each edit was accepted |
| Portal details | Name, address, and description in portal.site |
| Branding | Logo, favicon, primary color, and light, dark, or both color modes in portal.brand |
| Header links | Links to portal pages or external sites in portal.navigation.links |
| AI page actions | Turning "open in an AI assistant" on or off with portal.ai.pageActions |
| Pages and navigation | .md and .mdx pages with front matter, sidebar order and folder titles in nav.json, and tabs in src/content/nav.json |
| SDK languages | Adding C#, Python, or TypeScript to languages, so each gets an SDK card, a getting started page, and code samples |
| Context Plugins | Adding a Context Plugin page with a plugin block or portal.pluginUrl |
| Build and hosting | apimatic portal generate for static hosting, hosting under a path such as /docs, CI/CD with an API key, and the OAuth redirect URI for the API playground |
| Upgrading | Moving an older project from APIMATIC-BUILD.json and toc.yml to apimatic.json and nav.json |
The skill also knows what isn't available in the current CLI, such as API Recipes, API Copilot, custom themes and fonts, custom header and footer HTML, and versioned portals. If you ask for one, it says so and offers the closest supported option instead of inventing a setting.
When the agent uses this skill
The agent activates apimatic-portal automatically when you ask about:
- Creating, previewing, building, or deploying an APIMatic developer portal
- Changing the portal's name, logo, favicon, colors, color mode, header links, or AI page actions
- Adding pages, changing the sidebar order, or setting up tabs
- Showing SDKs or a Context Plugin page in the portal
- Working with
src/apimatic.json, or upgrading a project that hassrc/APIMATIC-BUILD.json
For generating, customizing, or publishing SDKs on their own, the agent uses the APIMatic SDK skill instead.
Use the skill
After you install the skill, open your project in Claude Code, Cursor, or Codex and describe what you want.
Example prompts
Starting from scratch:
"I have an OpenAPI definition at
./spec.yaml. Set up an APIMatic developer portal for it and start a local preview."
Branding:
"Use
static/images/logo.svgas the logo, set the primary color to#1E40AF, and only offer dark mode."
Pages and navigation:
"Add a getting started guide after the introduction, and put the SDKs and API Reference in their own tabs."
Hosting:
"I'll host the portal at
https://example.com/docs. Build it and create a GitHub Actions workflow that deploys it on every push."
Upgrading:
"This project still uses
APIMATIC-BUILD.json. Upgrade it to the current APIMatic CLI."
What happens behind the scenes
For a first-time setup, the agent:
- Checks for Node.js 24 and APIMatic CLI v2, and installs or upgrades the CLI if needed.
- Signs you in through the browser, with an API key fallback.
- Asks where your API definition is.
- Scaffolds
src/from the APIMatic sample portal and adds your API definition tosrc/spec/. - Starts the local preview and shows you its URL. The first start downloads your SDKs and code samples, so it can take a minute or two.
After that, each change follows the same loop: the agent edits the right file, checks whether the preview picked it up or needs a restart, and tells you when your changes are live. It then suggests what to work on next: branding, custom pages, navigation, or a Context Plugin page.
When the preview needs a restart
Most edits show up in the preview within a second or two: page text, any nav.json, the portal block of apimatic.json, and removing a language or the plugin block. These need the preview restarted, which the agent does for you:
- Adding or removing a page
- Adding a language or a
pluginblock - Creating
src/static/for the first time - Adding, removing, or replacing files in
src/spec/ - Changing the path in
portal.site.url
The preview server stops on its own after 30 minutes of inactivity. To stop it sooner, tell the agent: "shut down the portal".
Troubleshooting
Sign-in fails
Check that your APIMatic account is active and has portal generation enabled. If browser sign-in doesn't work, ask the agent to sign in with an API key instead. You can create one in the APIMatic Dashboard under Account > API Keys.
The CLI refuses to run
The APIMatic CLI needs Node.js 24 or later, locally and in CI. npm lets the install finish on older versions, but the CLI won't start. Install Node.js 24 from nodejs.org and try again.
The preview shows an old version after an edit
The CLI rejected the edit and keeps showing the last version it accepted. The agent reads the CLI's explanation, fixes the problem, and checks again. Common causes are a page without a title in its front matter, a nav.json entry with a file extension or a path, or a setting the portal block doesn't support.
The portal loads without styles when hosted under a path
Put the full address, path included, in portal.site.url (for example, https://example.com/docs) and rebuild.