From c4d0a07be4e7de4b54a212ec32bdb652918658af Mon Sep 17 00:00:00 2001 From: paoloanzn Date: Sun, 22 Mar 2026 23:31:23 +0100 Subject: [PATCH 1/2] feat: add flare-edge-cli agent skill --- .gitignore | 2 +- skills/flare-edge-cli/SKILL.md | 100 ++++++++++++++++++ skills/flare-edge-cli/agents/openai.yaml | 4 + .../flare-edge-cli/references/ai-workers.md | 50 +++++++++ .../references/install-and-release.md | 29 +++++ skills/flare-edge-cli/references/workflows.md | 60 +++++++++++ 6 files changed, 244 insertions(+), 1 deletion(-) create mode 100644 skills/flare-edge-cli/SKILL.md create mode 100644 skills/flare-edge-cli/agents/openai.yaml create mode 100644 skills/flare-edge-cli/references/ai-workers.md create mode 100644 skills/flare-edge-cli/references/install-and-release.md create mode 100644 skills/flare-edge-cli/references/workflows.md diff --git a/.gitignore b/.gitignore index c7bc50e..9ee49da 100644 --- a/.gitignore +++ b/.gitignore @@ -3,7 +3,7 @@ .env.* .idea/ .vscode/ -flare-edge-cli +/flare-edge-cli bin/ coverage.out dist/ diff --git a/skills/flare-edge-cli/SKILL.md b/skills/flare-edge-cli/SKILL.md new file mode 100644 index 0000000..0170bcb --- /dev/null +++ b/skills/flare-edge-cli/SKILL.md @@ -0,0 +1,100 @@ +--- +name: flare-edge-cli +description: Use this skill when the task is to scaffold, validate, build, develop, deploy, inspect, operate, or tear down Go-based Cloudflare Workers with flare-edge-cli. Trigger on requests about Cloudflare edge functions, Go/Wasm Workers, Workers AI in Go, or cleanup of ephemeral Cloudflare resources created through flare-edge-cli. +license: MIT +metadata: + author: Gladium AI + version: 1.0.0 + category: developer-tools + tags: + - cloudflare + - workers + - golang + - wasm + - workers-ai + - deployment +--- + +# Flare Edge CLI + +Use this skill to operate `flare-edge-cli` safely and consistently. + +## Use This Skill For + +- Creating a new Go-based Cloudflare Worker project +- Validating Go-for-Wasm compatibility before build or deploy +- Building and running local dev flows for Workers +- Deploying or operating KV, D1, R2, routes, secrets, releases, and logs +- Creating or testing Go-based Workers AI projects +- Tearing down disposable Workers and attached side effects + +## Core Rules + +- Prefer `flare-edge-cli` over raw `wrangler` when the task fits the CLI surface. +- Prefer `--json` output when another agent or program will consume the result. +- Keep project work scoped to an explicit `--path` when you are not already inside the generated project directory. +- Do not run `auth logout --all` unless the user explicitly asks to clear Cloudflare auth. +- For disposable test environments, finish with `flare-edge-cli teardown` so remote side effects are removed. +- If a task involves real Cloudflare AI usage, note that local dev still uses remote Workers AI and may incur charges. + +## Quick Workflow + +1. Verify prerequisites. +2. Initialize or inspect the project. +3. Run compatibility and build checks. +4. Use `dev` for local validation. +5. Use `deploy` for live rollout. +6. Use service-specific commands for KV, D1, R2, secrets, routes, logs, and releases. +7. Use `teardown` for cleanup when the environment is temporary. + +## Prerequisites + +- `flare-edge-cli` available on `PATH`, or use the repo-local binary/build path. +- Go installed. +- Wrangler installed. +- Cloudflare auth already configured. + +For the latest install flow and release-binary behavior, see [references/install-and-release.md](references/install-and-release.md). + +## Standard Command Path + +For a standard Worker: + +```bash +flare-edge-cli doctor --json +flare-edge-cli project init my-worker --template edge-http +flare-edge-cli compat check --path ./my-worker --json +flare-edge-cli build --path ./my-worker --json +flare-edge-cli dev --path ./my-worker --local +flare-edge-cli deploy --path ./my-worker --json +``` + +For an AI Worker: + +```bash +flare-edge-cli project init my-ai-worker --template ai-chat +flare-edge-cli build --path ./my-ai-worker --json +flare-edge-cli dev --path ./my-ai-worker --local +flare-edge-cli deploy --path ./my-ai-worker --json +``` + +Load [references/ai-workers.md](references/ai-workers.md) when the task is about AI templates, current model defaults, or how to test Workers AI locally. + +## Cleanup + +If you create temporary infrastructure or disposable test projects, tear them down explicitly: + +```bash +flare-edge-cli teardown --path ./my-worker --json +``` + +Use `--keep-bindings` only when the user wants to preserve KV, D1, or R2 resources. + +## Troubleshooting + +- Start with `flare-edge-cli doctor`. +- If deployment succeeds but the Worker fails at runtime, use `flare-edge-cli logs tail`. +- If a command mutates Cloudflare resources, verify whether the target project path and Worker name are correct before rerunning it. +- If a project mixes manual Wrangler edits with CLI-managed config, inspect both `flare-edge.json` and `wrangler.jsonc`. + +For common command sequences and operational guidance, read [references/workflows.md](references/workflows.md). diff --git a/skills/flare-edge-cli/agents/openai.yaml b/skills/flare-edge-cli/agents/openai.yaml new file mode 100644 index 0000000..679271b --- /dev/null +++ b/skills/flare-edge-cli/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Flare Edge CLI" + short_description: "Operate Go-based Cloudflare Workers and AI Workers with flare-edge-cli" + default_prompt: "Use flare-edge-cli to scaffold, validate, build, deploy, test, or tear down a Go-based Cloudflare Worker and return the concrete commands, outputs, and cleanup actions." diff --git a/skills/flare-edge-cli/references/ai-workers.md b/skills/flare-edge-cli/references/ai-workers.md new file mode 100644 index 0000000..fe4822e --- /dev/null +++ b/skills/flare-edge-cli/references/ai-workers.md @@ -0,0 +1,50 @@ +# AI Workers With Flare Edge CLI + +`flare-edge-cli` supports first-class Workers AI scaffolds for Go/Wasm Workers. + +## Supported AI Templates + +- `ai-text` +- `ai-chat` +- `ai-vision` +- `ai-stt` +- `ai-tts` +- `ai-image` +- `ai-embeddings` + +## Current Default Models + +- `ai-text` / `ai-chat`: `@cf/moonshotai/kimi-k2.5` +- `ai-vision`: `@cf/moonshotai/kimi-k2.5` +- `ai-stt`: `@cf/deepgram/nova-3` +- `ai-tts`: `@cf/deepgram/aura-2-en` +- `ai-image`: `@cf/black-forest-labs/flux-2-klein-9b` +- `ai-embeddings`: `@cf/qwen/qwen3-embedding-0.6b` + +## Local Testing Guidance + +- `flare-edge-cli dev --local` still uses the remote Cloudflare AI binding. +- Expect real account usage and potential charges during local testing. +- First request in a fresh `wrangler dev` session may prompt for Cloudflare account selection. + +## Typical AI Workflow + +```bash +flare-edge-cli project init demo-ai --template ai-chat +flare-edge-cli build --path ./demo-ai --json +flare-edge-cli dev --path ./demo-ai --local +``` + +Then test the local endpoint with a simple request, for example: + +```bash +curl 'http://127.0.0.1:8787/?prompt=Reply%20with%20OK' +``` + +## Cleanup + +If the AI Worker was created for a temporary run, prefer: + +```bash +flare-edge-cli teardown --path ./demo-ai --json +``` diff --git a/skills/flare-edge-cli/references/install-and-release.md b/skills/flare-edge-cli/references/install-and-release.md new file mode 100644 index 0000000..d089390 --- /dev/null +++ b/skills/flare-edge-cli/references/install-and-release.md @@ -0,0 +1,29 @@ +# Install And Release + +## Install Options + +One-line installer: + +```bash +curl -fsSL https://raw.githubusercontent.com/Gladium-AI/flare-edge-cli/main/install.sh | sh +``` + +Source build: + +```bash +make build +make install +``` + +## Release Assets + +GitHub releases publish binaries for: + +- `linux/amd64` +- `linux/arm64` +- `darwin/amd64` +- `darwin/arm64` +- `windows/amd64` +- `windows/arm64` + +Release assets are attached automatically by the GitHub Actions release workflow when a GitHub release is published. diff --git a/skills/flare-edge-cli/references/workflows.md b/skills/flare-edge-cli/references/workflows.md new file mode 100644 index 0000000..8189510 --- /dev/null +++ b/skills/flare-edge-cli/references/workflows.md @@ -0,0 +1,60 @@ +# Flare Edge CLI Workflows + +Use these patterns when operating `flare-edge-cli` projects. + +## 1. Bootstrap a Standard Worker + +```bash +flare-edge-cli doctor --json +flare-edge-cli project init hello-edge --template edge-http +flare-edge-cli compat check --path ./hello-edge --json +flare-edge-cli build --path ./hello-edge --json +flare-edge-cli dev --path ./hello-edge --local +flare-edge-cli deploy --path ./hello-edge --json +``` + +## 2. Bootstrap an AI Worker + +```bash +flare-edge-cli project init hello-ai --template ai-chat +flare-edge-cli build --path ./hello-ai --json +flare-edge-cli dev --path ./hello-ai --local +flare-edge-cli deploy --path ./hello-ai --json +``` + +## 3. Operate an Existing Project + +```bash +flare-edge-cli project info --path ./hello-edge --json +flare-edge-cli compat check --path ./hello-edge --json +flare-edge-cli build --path ./hello-edge --json +flare-edge-cli logs tail --path ./hello-edge +``` + +## 4. Provision Data Resources + +```bash +flare-edge-cli kv namespace create CACHE --path ./hello-edge --json +flare-edge-cli d1 create DB --path ./hello-edge --json +flare-edge-cli r2 bucket create FILES --path ./hello-edge --json +``` + +## 5. Safe Cleanup + +For temporary resources created during tests or agent workflows: + +```bash +flare-edge-cli teardown --path ./hello-edge --json +``` + +If the local project should also be removed: + +```bash +flare-edge-cli teardown --path ./hello-edge --delete-project --json +``` + +## Notes + +- Prefer `--json` for machine consumption. +- Prefer `--path` over relying on the current working directory when the target project is not obvious. +- Use `doctor` early if auth or tooling health is uncertain. From b6e70f49d38c8b1298100391f5f50ee508db0a06 Mon Sep 17 00:00:00 2001 From: paoloanzn Date: Sun, 22 Mar 2026 23:37:38 +0100 Subject: [PATCH 2/2] docs: add skill install command --- README.md | 8 ++++++ install-skill.sh | 69 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 77 insertions(+) create mode 100755 install-skill.sh diff --git a/README.md b/README.md index 360247b..0f41234 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,14 @@ The implementation is intentionally biased toward agent use: ## Install +Install the Claude Code skill: + +```bash +curl -fsSL https://raw.githubusercontent.com/Gladium-AI/flare-edge-cli/main/install-skill.sh | sh +``` + +That installs the skill to `~/.claude/skills/flare-edge-cli` by default. Override the target directory with `SKILLS_DIR=/path/to/skills`. + Build the binary from the repository root: ```bash diff --git a/install-skill.sh b/install-skill.sh new file mode 100755 index 0000000..010f154 --- /dev/null +++ b/install-skill.sh @@ -0,0 +1,69 @@ +#!/bin/sh +set -eu + +REPO="${REPO:-Gladium-AI/flare-edge-cli}" +REF="${REF:-main}" +SKILL_NAME="${SKILL_NAME:-flare-edge-cli}" +SKILL_PATH="${SKILL_PATH:-skills/${SKILL_NAME}}" +SKILLS_DIR="${SKILLS_DIR:-${CLAUDE_CODE_SKILLS_DIR:-$HOME/.claude/skills}}" + +download() { + url="$1" + out="$2" + + if command -v curl >/dev/null 2>&1; then + curl -fsSL "$url" -o "$out" + return + fi + + if command -v wget >/dev/null 2>&1; then + wget -q "$url" -O "$out" + return + fi + + echo "Error: curl or wget is required" >&2 + exit 1 +} + +copy_skill() { + src="$1" + dst="${SKILLS_DIR}/${SKILL_NAME}" + + mkdir -p "$SKILLS_DIR" + rm -rf "$dst" + cp -R "$src" "$dst" + printf 'Installed skill to %s\n' "$dst" +} + +if [ -n "${SOURCE_DIR:-}" ]; then + src="${SOURCE_DIR%/}/${SKILL_PATH}" + if [ ! -d "$src" ]; then + echo "Error: skill directory not found at $src" >&2 + exit 1 + fi + copy_skill "$src" + exit 0 +fi + +tmpdir="$(mktemp -d)" +trap 'rm -rf "$tmpdir"' EXIT INT TERM + +archive="$tmpdir/repo.tar.gz" +url="https://codeload.github.com/${REPO}/tar.gz/refs/heads/${REF}" + +download "$url" "$archive" +tar -xzf "$archive" -C "$tmpdir" + +root_dir="$(find "$tmpdir" -mindepth 1 -maxdepth 1 -type d | head -n 1)" +if [ -z "$root_dir" ]; then + echo "Error: could not extract repository archive" >&2 + exit 1 +fi + +src="${root_dir}/${SKILL_PATH}" +if [ ! -d "$src" ]; then + echo "Error: skill directory not found in downloaded archive: $src" >&2 + exit 1 +fi + +copy_skill "$src"