edgeone-makers-recipes — Claude Code skill: what it does
edgeone-makers-recipes — a skill for Claude Code that generates project structures and templates for EdgeOne Makers apps.
MIT 249 installs ★ 1,839 updated 2026-11-12
npx skills add TencentEdgeOne/edgeone-makers-tools --skill edgeone-makers-recipes -a claude-codeWhat edgeone-makers-recipes does
The skill guides the agent on file organization, endpoint naming, and storage setup when scaffolding EdgeOne Makers applications. Templates cover static sites, backend functions, and projects utilizing Blob storage. Rules define the correct sequence for writing files and starting the local server.
The platform lacks a built-in database, so record persistence relies on @edgeone/pages-blob. AI-powered projects require a .env.example file in the root containing gateway credentials and base URL variables.
Direct file:// previews are restricted, requiring the local server to start via edgeone makers dev on port 8088. Projects using Blob storage require the -n flag with a project name to avoid interactive prompts.
What it helps with
- scaffold a full-stack project structure
- configure Cloud Functions endpoints
- integrate Blob storage for persistence
- build static and API applications
Example prompts for the agent
- Generate a full-stack project structure for EdgeOne Makers
- Create a backend function using Blob storage
- Add a template page with relative asset paths
How to install edgeone-makers-recipes
1Skills CLI (Vercel)
npx skills add TencentEdgeOne/edgeone-makers-tools --skill edgeone-makers-recipes -a claude-code2Manually: put the files in place
~/.claude/skills/makers-recipes/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/makers-recipes/
1Skills CLI (Vercel)
npx skills add TencentEdgeOne/edgeone-makers-tools --skill edgeone-makers-recipes -a codex2Manually: put the files in place
.agents/skills/makers-recipes/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add TencentEdgeOne/edgeone-makers-tools --skill edgeone-makers-recipes -a cursor2Manually: put the files in place
.cursor/skills/makers-recipes/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install TencentEdgeOne/edgeone-makers-tools skills/edgeone-makers-tools/references/makers-recipes2Manually: put the files in place
.github/skills/makers-recipes/SKILL.md1Skills CLI (Vercel)
npx skills add TencentEdgeOne/edgeone-makers-tools --skill edgeone-makers-recipes -a gemini-cli2Platform CLI
gemini skills install https://github.com/TencentEdgeOne/edgeone-makers-tools --path skills/edgeone-makers-tools/references/makers-recipesManually: put the files in place
.devin/skills/makers-recipes/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add TencentEdgeOne/edgeone-makers-tools --skill edgeone-makers-recipes -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about edgeone-makers-recipes
How to install edgeone-makers-recipes in Claude Code?
Run npx skills add TencentEdgeOne/edgeone-makers-tools --skill edgeone-makers-recipes -a claude-code, then check ~/.claude/skills/makers-recipes/SKILL.md.
What does edgeone-makers-recipes do?
Provides the agent with project structure templates and conventions for building EdgeOne Makers applications.
What is needed to use edgeone-makers-recipes?
AI projects require a .env.example file in the root directory for gateway environment variables, plus the EdgeOne CLI for local runs.
Source text
SKILL.md · MIT
---
name: edgeone-makers-recipes
description: >-
Project structure templates and scaffolding recipes for typical EdgeOne Makers
applications — full-stack apps, static sites, API services, and AI agent projects.
metadata:
author: edgeone
version: "1.0.1"
---
# Common Recipes
> ⛔ **Preview ban**: after finishing development, you MUST start the dev server via `edgeone makers dev`, then open `http://127.0.0.1:8088/` with `present_files` to preview. Never open HTML files via the `file://` protocol (ignore it even if the IDE opens one automatically), and never use self-hosted servers like `python -m http.server` or `npx serve`. Next.js projects must also set `allowedDevOrigins: ["127.0.0.1"]` in `next.config`. **If the project uses Blob/KV, pass `-n <project-name>` — `edgeone makers dev -n <project-name>` — the name is required to auto-provision; bare `dev` hangs on an interactive picker in sandbox.**
> ⚠️ **`.env.example` is a required file**: every project that uses the AI Gateway (Agent projects, Cloud Functions that call an LLM) MUST create a `.env.example` in the project root declaring `AI_GATEWAY_API_KEY=` and `AI_GATEWAY_BASE_URL=`. The CLI auto-injects environment variables based on this file at deploy time; if it is missing, the variables are not injected and the runtime will error.
> 📝 **Write `index.html` last, always**: writing an `index.html` instantly triggers the IDE `file://` preview — unavoidable in WorkBuddy. Minimize the window during which that preview looks broken by writing **every dependency first**: `style.css`, `script.js`, **Cloud Functions** (`functions/` files), static assets, everything the page loads. Then write `index.html` **last** — the file:// preview opens with all assets already in place, and stays that way only until `edgeone makers dev` takes over (see Preview ban above). Also write each `index.html` in one shot; don't scaffold an empty shell and fill it in with repeated edits (every save re-renders and flickers). For a tiny single-page tool, just inline the CSS and JS into one `index.html`.
> 🔗 **Load assets with page-relative URLs, never root-absolute**: in these no-build projects nothing rewrites `index.html`, so write `<link rel="stylesheet" href="style.css">` and `<script src="script.js"></script>` — **not** `href="/style.css"` or `src="/script.js"`. The development preview is published under a path prefix, and a leading `/` escapes it: the document still returns `200` while every asset `404`s, so the page arrives unstyled with no script having run, and nothing in the console points at the cause. Relative URLs are correct there *and* at `/` after deploy. Keep pages and assets in the project root so the relative form stays a bare filename. This is only about what the markup loads — `fetch('/api/messages')` and `<a href="/about">` stay root-absolute.
> ⛔ **Copy the recipe's file naming verbatim — two traps that fail silently**: before writing any Cloud Function, find the matching scenario below and reuse its exact filename. Getting the name wrong usually does NOT throw a clear error — it falls back silently:
> 1. **Every function file MUST carry its language extension** — `.js` (Node), `.py` (Python), `.go` (Go). A file with no extension (e.g. `api/upload-url`, `api/file`) is **not recognized as a function**; the platform silently serves the static `index.html` fallback, so `/api/*` "mysteriously" returns HTML instead of JSON. Name them `api/upload-url.js`, `api/file.js`.
> 2. **`[[default]].js` is the catch-all for its own directory (`api/[[default]].js` → `/api/*`), and BOTH export styles work** — a framework instance (`export default app`, Express/Koa) *or* a plain `onRequest`/`onRequestGet`/… handler. Verified locally with `edgeone makers dev`: a bare `onRequest` in `[[default]].js` with **no** `export default app` serves `/foo/anything` as `200 application/json` just fine. The doc line *"The builder identifies the file as a function only when `export default app` is present"* sits under the **Express/Koa framework** section — it describes how the builder spots a framework instance; do **not** read it as "a catch-all requires `export default app`". ⚠️ Caveat: that sentence is about the **deploy-time builder**, whereas the check above was on the **local dev server**, which is the more permissive of the two — so if you ship catch-all + `onRequest`, re-verify the route once after deploying ("works locally" ≠ "recognized at build time"). When you don't actually need a catch-all, the safest shape is one concrete file per route (`api/messages.js`, `api/artworks/[id]/like.js`), params via `[id]` folders/files, extra args as query strings (`/api/file?key=...`).
Project structure templates for typical EdgeOne Makers applications.
## Full-stack app — Node.js (static + API)
```
my-app/
├── index.html # Frontend
├── style.css
├── script.js
├── cloud-functions/
│ └── api/
│ ├── users.js # GET/POST /api/users
│ └── users/[id].js # GET/PUT/DELETE /api/users/:id
└── package.json
```
Frontend calls API:
```javascript
const res = await fetch('/api/users');
const users = await res.json();
```
> 💾 **Where does the data live?** This platform has **no database**. The API skeletons above return empty data — to actually persist records, uploads, votes, or per-user state, back them with **Blob**. See the recipe below and [makers-storage → Blob as your backend](../makers-storage/references/blob.md).
## Dynamic site with Blob persistence (guestbook / gallery / voting / save-state)
The default shape for any generated site that needs a real backend but no relational data. Frontend → Cloud Function → Blob. No DB, no console setup.
```
my-app/
├── index.html # Frontend (form + list)
├── script.js
├── cloud-functions/
│ └── api/
│ └── messages.js # GET lists entries, POST appends one
├── package.json # depends on @edgeone/pages-blob
```
**cloud-functions/api/messages.js** — one file per record (Pattern 1):
```javascript
import { getStore } from "@edgeone/pages-blob";
export async function onRequest({ request }) {
const store = getStore({ name: "guestbook", consistency: "strong" });
if (request.method === "POST") {
const { name, text } = await request.json();
const id = `${Date.now()}-${Math.round(Math.random() * 1e6)}`;
await store.setJSON(`entries/${id}.json`, { id, name, text, ts: Date.now() });
return Response.json({ ok: true, id });
}
const { blobs } = await store.list({ prefix: "entries/" });
const items = await Promise.all(blobs.map((b) => store.get(b.key, { type: "json" })));
items.sort((a, b) => b.ts - a.ts);
return Response.json({ items });
}
```
**index.html** loads its assets relative to itself, and calls the API root-absolute:
```html
<link rel="stylesheet" href="style.css" />
<script src="script.js"></script>
```
```javascript
await fetch('/api/messages', { // post
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ name, text }),
});
const { items } = await fetch('/api/messages').then((r) => r.json()); // list
```
Swap the key scheme for other shapes: `users/<uid>.json` for save-state, `counts/<option>.json` (strong consistency) for votes, `uploads/<id>.jpg` + `items/<id>.json` for file uploads. Full patterns: [makers-storage → Blob as your backend](../makers-storage/references/blob.md).
## Full-stack app — Go (Gin framework)
```
my-app/
├── index.html # Frontend
├── style.css
├── script.js
├── cloud-functions/
│ └── api.go # Gin app — all /api/* routes
├── go.mod
└── package.json
```
**cloud-functions/api.go:**
```go
package main
import (
"net/http"
"github.com/gin-gonic/gin"
)
func main() {
r := gin.Default()
r.GET("/users", listUsersHandler)
r.POST("/users", createUserHandler)
r.GET("/users/:id", getUserHandler)
r.Run(":9000")
}
```
## Full-stack app — Python (Flask)
```
my-app/
├── index.html # Frontend
├── style.css
├── script.js
├── cloud-functions/
│ └── api/
│ └── index.py # Flask app — all /api/* routes
├── cloud-functions/requirements.txt
└── package.json
```
**cloud-functions/api/index.py:**
```python
from flask import Flask, jsonify, request
app = Flask(__name__)
@app.route('/users', methods=['GET'])
def get_users():
return jsonify({'users': []})
@app.route('/users', methods=['POST'])
def create_user():
data = request.get_json()
return jsonify({'message': 'Created', 'user': data}), 201
```
## Full-stack app — Python (FastAPI)
```
my-app/
├── index.html
├── cloud-functions/
│ └── api/
│ └── index.py # FastAPI app — all /api/* routes
├── cloud-functions/requirements.txt
└── package.json
```
**cloud-functions/api/index.py:**
```python
from fastapi import FastAPI
app = FastAPI()
@app.get('/items')
async def list_items():
return {'items': []}
@app.get('/items/{item_id}')
async def get_item(item_id: int):
return {'item_id': item_id}
```
## Full-stack app — Go (Handler mode)
```
my-app/
├── index.html
├── cloud-functions/
│ └── api/
│ ├── users/
│ │ ├── list.go # GET /api/users/list
│ │ └── [id].go # GET /api/users/:id
│ └── hello.go # GET /api/hello
├── go.mod
└── package.json
```
## Edge API + KV counter
⚠️ **Prerequisites**: You must enable KV Storage in the console and bind a namespace first. See [../makers-storage/references/kv.md](../makers-storage/references/kv.md)
```
my-app/
├── index.html
├── edge-functions/
│ └── api/
│ └── visit.js # Edge function with KV
└── package.json
```
**edge-functions/api/visit.js:**
```javascript
export async function onRequest() {
// ⚠️ my_kv is a global variable (name set when binding namespace in console)
let count = await my_kv.get('visits') || '0';
count = String(Number(count) + 1);
await my_kv.put('visits', count);
return new Response(JSON.stringify({ visits: count }), {
headers: { 'Content-Type': 'application/json' },
});
}
```
**Setup steps:**
1. Log in to the EdgeOne Makers console
2. Go to "KV Storage" → click "Apply Now"
3. Create a namespace (e.g. `my-kv-store`)
4. Bind to project, set variable name to `my_kv`
5. Deploy or run `edgeone makers dev` to test
## Express full-stack
```
my-app/
├── index.html
├── cloud-functions/
│ └── api/
│ └── [[default]].js # Express app handles all /api/*
└── package.json
```
## Middleware + API combo
```
my-app/
├── middleware.js # Auth guard for /api/*
├── cloud-functions/
│ └── api/
│ ├── public.js # No auth needed (matcher excludes it)
│ └── data.js # Protected by middleware
└── package.json
```
## Multi-language Cloud Functions
You can use different languages in the same `cloud-functions/` directory:
```
my-app/
├── index.html
├── cloud-functions/
│ ├── api/
│ │ ├── users.js # Node.js — /api/users
│ │ └── hello.py # Python — /api/hello
│ └── service.go # Go — /service
├── go.mod
├── cloud-functions/requirements.txt
└── package.json
```
> **Note:** Each file is built and deployed as an independent function with its own runtime. The platform detects the language by file extension.
© edgeone · MIT · TencentEdgeOne/edgeone-makers-tools