heshengtao/super-agent-party / skills/sap-extension-creator
sap-extension-creator
VerifiedCreate Super Agent Party (SAP) extensions. This skill should be used when users want to create, build, or scaffold a new extension for Super Agent Party - including static HTML extensions (pure frontend) and Node.js backend extensions. Triggers on requests like "create a new SAP extension", "build an extension for Super Agent Party", "scaffold a plugin", "make a chat UI extension", or when working with sap extension projects.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 23.7 KB |
| assets/node-template/index.html | other | 16.5 KB |
| assets/node-template/index.js | script | 1.4 KB |
| assets/node-template/package.json | manifest | 381 B |
| assets/static-template/index.html | other | 15.8 KB |
| assets/static-template/package.json | manifest | 295 B |
| references/node-entry-spec.md | markdown | 3.4 KB |
| references/package-json-spec.md | markdown | 6.8 KB |
references/node-entry-spec.md
View on GitHub# Node.js Entry Point & Lifecycle Specification
How SAP manages Node.js extension processes.
## Launch Protocol
SAP starts the extension with:
```bash
node index.js <port>
```
Where `<port>` is the assigned port number.
## Required index.js Structure
```js
const PORT = parseInt(process.argv[2], 10);
const express = require('express');
const path = require('path');
const EXT_DIR = __dirname;
const app = express();
// 1. Serve all static files from extension directory
app.use(express.static(EXT_DIR));
// 2. Root route returns index.html
app.get('/', (req, res) => res.sendFile(path.join(EXT_DIR, 'index.html')));
// 3. Health check endpoint (SAP polls this to confirm readiness)
app.get('/health', (req, res) => res.json({ status: 'ok' }));
// 4. Add custom API routes here
// app.get('/api/data', (req, res) => { ... });
// app.post('/api/action', (req, res) => { ... });
// 5. Listen on assigned port at loopback only
app.listen(PORT, '127.0.0.1', () => {
console.log(`[ext] Ready at http://127.0.0.1:${PORT}`);
});
```
## Lifecycle
```
npm install (if needed)
↓
node index.js <port>
↓
SAP polls /health until 200
↓
Extension is LIVE — SAP proxies requests
↓
On shutdown: SIGTERM → process terminates
```
## Port Assignment
- `nodePort: 0` in package.json → SAP auto-assigns from available pool (3100-13999)
- `nodePort: 3000` → SAP tries port 3000 first
## npm install
- SAP runs `npm install --production` only when:
- `node_modules/` does not exist, OR
- `package.json` is newer than `node_modules/`
- If `dependencies` is empty/absent, npm install is skipped
## Environment Variables
| Variable | Value | Purpose |
|----------|-------|---------|
| `NODE_EXTENSION_ID` | ext_id string | The extension's ID |
| `ELECTRON_RUN_AS_NODE` | `"1"` | Set in Electron desktop mode only |
| `npm_config_registry` | mirror URL | Set when China proxy mode is enabled |
## Reverse Proxy
SAP proxies requests through:
```
/api/extensions/{ext_id}/node/{path}
```
The proxy forwards method, headers, body, and query params to `http://127.0.0.1:{port}/{path}`.
## MCP / AI Tool Registration
MCP tool registration is done in the **frontend** (`index.html`) via WebSocket, not in the Node.js backend. The `index.js` file handles:
- Static file serving
- Custom API routes (called by the frontend)
- Backend logic (DB queries, file processing, external API calls)
The frontend registers MCP tools via WebSocket and handles `call_mcp_tool` events. Those handlers can optionally call the Node.js backend API for server-side operations. See the main SKILL.md for MCP implementation details.
## Important Notes
- **Font Awesome**: Use CDN in `index.html` (`cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css`). Relative paths like `../../fontawesome/` do NOT work because the extension is served from Express on a different port, not from SAP's static file directory.
- **Static assets**: Place all CSS/JS files in the extension root directory. Express serves them via `express.static(EXT_DIR)`, so they are accessible at the same path level as `index.html`.
- **API routes**: Express JSON body parsing is NOT included by default. Add `app.use(express.json())` if your API routes need JSON request bodies.
## Cleanup
- On SAP shutdown, all extension processes receive `terminate()` signal
- Extensions should handle `SIGTERM` for graceful cleanup
- Stale ports are reclaimed automatically
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 |