Skip to content
Skills Library
Programming · Building & coding

server-plugins

/server-plugins

Framework server plugins and the `/_agent-native/` route namespace. Use when adding a custom server plugin, deciding whether to create an `/api/` route vs an action, or debugging auto-mounted framework routes.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Framework server plugins and the `/_agent-native/` route namespace. Use when adding a custom server plugin, deciding whether to create an `/api/` route vs an action, or debugging auto-mounted framework routes.

Original author description

Framework server plugins and the `/_agent-native/` route namespace. Use when adding a custom server plugin, deciding whether to create an `/api/` route vs an action, or debugging auto-mounted framework routes.

How it works

  1. Default Plugins (auto-mount)
  2. Framework Route Namespace: /agent-native/
  3. Actions-First Approach
  4. Related Skills
Original SKILL.md headings · 75 lines, 494 words
SKILL.md preview
---
name: server-plugins
description: >-
  Framework server plugins and the `/_agent-native/` route namespace. Use when
  adding a custom server plugin, deciding whether to create an `/api/` route vs
  an action, or debugging auto-mounted framework routes.
scope: dev
metadata:
  internal: true
---

# Server Plugins & Framework Routes

## Default Plugins (auto-mount)

Five default plugins auto-mount when your app doesn't have a custom version in `server/plugins/`:

| Plugin        | Default behavior                                  | Customize when                              |
| ------------- | ------------------------------------------------- | ------------------------------------------- |
| `agent-chat`  | Agent chat endpoints                              | Custom `mentionProviders` or `systemPrompt` |
| `auth`        | Auth middleware                                   | Custom `publicPaths` or Google OAuth config |
| `core-routes` | `/_agent-native/poll`, `/_agent-native/ping`, etc | Custom `envKeys` or `sseRoute`              |
| `resources`   | Resource CRUD                                     | Rarely                                      |
| `terminal`    | Terminal emulator                                 | Rarely                                      |

**Only create plugin files for plugins you need to customize.** Let defaults auto-mount.

## Framework Route Namespace: `/_agent-native/`

All framework-level routes live under `/_agent-native/` to avoid collisions with template-specific `/api/*` routes.

### Hard rule

- **ALL framework routes go under `/_agent-native/`.**
- Templates own `/api/*` only for route-only domain concerns such as uploads,
  streaming, webhooks, OAuth callbacks, or non-JSON protocols.
- Never put framework routes under `/api/`.
- Never put template routes under `/_agent-native/` — that namespace is reserved.
- Never create `/api/*` routes that only wrap, proxy, or re-export actions. Use
  the existing `/_agent-native/actions/:name` endpoint or the React action hooks.

### Auto-mounted framework routes

| Route                                                         | Purpose                                  |
| ------------------------------------------------------------- | ---------------------------------------- |
| `GET /_agent-native/poll`                                     | Polling endpoint for DB change detection |
| `GET /_agent-native/events`                                   | SSE endpoint for real-time sync          |
| `GET /_agent-native/ping`                                     | Health check                             |
| `GET/PUT/DELETE /_agent-native/application-state/:key`        | Application state CRUD                   |
| `GET/PUT/DELETE /_agent-native/application-state/compose/:id` | Compose draft CRUD                       |
| `POST /_agent-native/agent-chat`                              | Agent chat SSE endpoint                  |
| `GET /_agent-native/agent-chat/mentions`                      | Mention search for @-tagging             |
| `GET /_agent-native/env-status`                               | Env key configuration status             |
| `POST /_agent-native/env-vars`                                | Save env vars                            |
| `/_agent-native/auth/*`                                       | Authentication (login, session, logout)  |
| `/_agent-native/google/*`                                     | Google OAuth (callback, auth-url, etc.)  |
| `/_agent-native/resources/*`                                  | Resource CRUD                            |
| `/_agent-native/actions/:name`                                | Auto-mounted action endpoints            |
| `/_agent-native/available-clis`                               | Available CLI tools                      |
| `/_agent-native/agent-terminal-info`                          | Terminal connection info                 |
| `/_agent-native/collab/*`                                     | Real-time collaboration (see `real-time-collab`) |
| `/_agent-native/a2a`                                          | A2A JSON-RPC endpoint (see `a2a-protocol`) |

## Actions-First Approach

For standard CRUD and data operations, use `defineAction` in `actions/` — the framework auto-mounts them as HTTP endpoints at `/_agent-native/actions/:name`. Only create custom `/api/*` routes for things actions can't do:

- File uploads with multipart form data
- Streaming responses
- Webhooks from external services
- OAuth callbacks

Before adding a route, inspect the existing action files. Reuse the action if
it already encodes the business rule, or add a new action if the operation
should be available to both the agent and the UI. A route whose implementation
mostly calls an action is usually the wrong abstraction.

The Nitro Vite plugin handles both `/api/` and `/_agent-native/` prefixes via file-based routing in `server/routes/`.

## Related Skills

- `actions` — Prefer actions over custom `/api/` routes
- `authentication` — Auth middleware and session handling
- `portability` — Use H3 (not Express) for all routes

Versions

The database has no other skills named server-plugins.

Database snapshot: 13.11.2026 · package version 198153c90784 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100xmake-custom-plugins
    Use when authoring a custom xmake plugin / task — defining `task(...)` with `set_menu`, running logic in `on_run`, packaging as a standalone plugin under `~/.xmake/plugins/` or inside an xmake-repo, using `import()` to reuse xmake core modules, and distributing plugins.…
  • 100uniapp-native-plugin
    A comprehensive skill for developing native plugins for uni-app. Use this skill when building Android/iOS native plugins, integrating native capabilities, or publishing plugins based on official native plugin docs.
  • 100prettier-plugins
    Use when prettier plugins including plugin ecosystem, custom parsers, and plugin development.
  • 100api-patterns
    API route implementation patterns with RLS, Zod validation, and error handling. Use when creating API routes, implementing endpoints, or adding server-side validation.
  • 100api-patterns
    API route implementation patterns with RLS, Zod validation, and error handling. Use when creating API routes, implementing endpoints, or adding server-side validation.
  • 100publish-plugins
    (project) Use when editing any file under skills/ or plugins/ to bump the plugin version and check the manifests

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.