SuperAPI AI Directory

findy-hackathon

General & other

View repository

Updated 10-16 11:21

About this skill

Findy Campus Hackathon #2 support skill

This skill is for supporting participants of Findy Campus Hackathon #2 "Build and publish your favorite AI app with Cloudflare!" all the way from idea to deploy (publish).

Your (the coding agent's) role is not to force choices on participants, but to chart a path that fits what they want to make and their skill level. The "choices" below are just a map, not something to make them decide firmly at the start. Start from what they want to do, and only provide traffic control when necessary.


0. Prerequisites (participant's environment)

This is the minimum needed to get started.

  • Node.js (v20+) — npx / npm must be available. This first.
  • Coding agent — Claude Code / Cursor / GitHub Copilot / Gemini CLI, etc. (some are available for free).

Additional requirements when deploying (publishing):

  • Cloudflare account — the free tier is fine. Workers AI also has a free tier.
  • For authentication, npx wrangler login(No global installation of Wrangler is needed. It is bundled with the starter and runs with npx wrangler ... ).

Git is not required (the starter's npx degit も npx skills add also does not require git because it uses a tarball download). It is useful when you want to version-control and push your deliverables.

When you want to check the environment:node -v(v20+ か)、npx wrangler whoami(whether you are logged in).


1. The range of what you can build (choices)

The range of what you can build is broad, and any of them is correct. You don't need to decide firmly at the start, and you can change it along the way. If you're unsure, start by building the smallest thing and decide as you go.

At first, this is almost all you need to keep in mind:

  • Use Cloudflare / don't use it — whether you use it changes the starter (using it makes both local development and publishing easier).

The following two can be decided later or added later. You don't need to worry about them first:

  • Use AI / don't use it — if you use it, Workers AI is easy (no key required). If you want to go elaborate, use the Agents SDK to build an agent (input is basically chat). A normal web app without AI is also fine (→ Chapter 4).
  • Deploy / local only — the theme is "publishing," so once it works, it's good to deploy it once. If you don't want to show it, local only is fine too (→ Chapter 5).

Don't force this axis on participants. Ask what they want to do first, and use it for traffic control only when necessary. For how to build, refer to "2. How to start" and "3. The form you want" below.


2. How to start (when using Cloudflare)

Rather than creating a directory yourself and building from scratch, it's faster to degit an all-in-one starter. Even for a normal web app that doesn't use AI, you can start with this (having the Agents SDK dependency included doesn't hurt).

  1. Get and run the starter (all-in-one with Hono + Vite + React + Agents SDK)

    npx degit yusukebe/findy-campus-hackathon-02 my-hackathon-app
    cd my-hackathon-app && npm install
    npm run dev
    
  2. Install the whole skill set with npm run setup:skills (installed into.agents/skills/ と .claude/skills/ ). In addition to this skill (findy-hackathon),hono / cloudflare / wrangler / workers-best-practices / agents-sdk / durable-objects is introduced. If you can read this skill, it's already installed, so no guidance is needed. The same command works when you want to reinstall it.

  3. After that, proceed according to what you want to build while referring to "3. The shape you want". Before deploying, wrangler.jsonc の name prompt them to change it to their own app name (it becomes the name in the public URL).

If you need additional skills, you can add them later with npx skills add (e.g., npx skills add cloudflare/skills --skill sandbox-sdk)。 --list lets you check the list of skills in the repository.

If you're not using Cloudflare, any environment is fine. However, since the theme is "public", think together about the publication method at the end. If you use Hono, the bundled skill (hono / cloudflare) is directly useful.


3. The shape you want (reference recipes)

The following is not meant to make you choose, but as a reference for when you can see the shape you want. You can mix them or change them later.

Web app

A normal web app that has a database and returns responses (HTML pages or JSON) according to requests. The basic structure is the screen (src/client) + API + data storage (such as D1). AI is not required. When you want to add summarization, proofreading, translation, image generation, chat, etc., go to "4. How to incorporate AI".

AI agent

Make use of the Cloudflare Agents SDK. The input channel is basically chat, but depending on the user's wishes, others are possible as well. The details of the implementation are in the agents-sdk skill, so be sure to read it. The main features you'll want to make use of:

  • Chat — a streaming chat UI (AIChatAgent / useAgentChat , etc.). The basic entry point for the agent.
  • State sync — setState / useAgent synchronizes server ⇄ browser in real time.
  • Scheduling — this.schedule() for delayed/periodic execution (reminders, periodic batches, etc.).
  • Tool calling — have the AI execute external APIs, DB operations, etc.
  • Persistence — storage/SQL built into the Agent.
  • As needed, also MCP, human-in-the-loop, Workflows, etc.

Example (minimal working example): yusukebe/memo2task — "when you write a memo, the AI turns it into a task, and notifies you when the time comes". Interpretation with Workers AI / setState / this.schedule() 's 3 features make it work. Ideal for grasping the shape. Reference: yusukebe/agents-examples。

Plus α: Make use of Cloudflare products

It gives the app more depth and also fits the theme. Try adding from the easiest ones to use (details are in the cloudflare / agents-sdk skill).

  • Workers AI — Inference (text/image generation, etc.). No key needed and easy to use.
  • D1 — SQLite-based DB. For apps that store data.
  • R2 — Object storage (images/files). For upload-type apps.
  • Durable Objects / Agents SDK — State, real-time, coordination. The core of chats and agents.
  • Browser Run — Browser operations from Workers (screenshots, scraping, PDF conversion, etc.).
  • There are also KV (simple key-value), Queues, Vectorize (vector search), and more.

4. How to integrate AI

Broadly two ways. At a hackathon, Workers AI is easy (no API key required, bundled with Cloudflare, free tier available).

(a) Use Workers AI (recommended, no key required)

wrangler.jsonc Add an AI binding to , andenv.AI.run(...) call it with .

// wrangler.jsonc
{
  "ai": { "binding": "AI" }
}
const res = await env.AI.run('@cf/meta/llama-3.2-3b-instruct', {
  messages: [{ role: 'user', content: 'こんにちは' }]
})

Model IDs go stale, so before using one, check the list to confirm → https://developers.cloudflare.com/workers-ai/models/。

(b) Use an external LLM API (such as Claude)

When you want to use a smarter model, call an external API. Do not hardcode API keys in code; put them in a secret.

npx wrangler secret put ANTHROPIC_API_KEY   # デプロイ環境用
# ローカルは .dev.vars に ANTHROPIC_API_KEY=... を書く(.gitignore 済みであること)

If you use the AI SDK, @ai-sdk/anthropic use a provider such as . For the latest available models and API details, if unsure, check claude-api skills (if this agent has them) or the official documentation.


5. Deploy (publish)

If you want to publish, don't wait for it to be finished; once it works, deploy it once.

npx wrangler login      # 初回のみ
npm run deploy          # = wrangler deploy。完了するとURLが出る
  • Once the public URL appears, open it in a browser to check that it works → that URL can be used for submission/demo.
  • wrangler.jsonc After editing , npm run cf-typegen regenerate types with .
  • Secrets in the deployment environment use wrangler secret put, and locally use .dev.vars。.env / .dev.vars Do not commit .

6. Notes on cost, tokens, and cleanup

To avoid accidents during and after the hackathon, be careful from the start.

  • Delete when done — Delete prototype Workers and unnecessary resources (D1 / R2 / KV / Durable Objects, etc.). Workers are npx wrangler delete. Leaving things around causes cost and confusion. Do a cleanup once after the hackathon. You can also check from the dashboard.
  • Don't leak secrets — Do not hardcode or commit API keys..dev.vars(local) / npx wrangler secret put(production), and .env / .dev.vars が .gitignore check whether it has been done. After the hackathon, revoke/rotate the keys.
  • Watch token usage — External LLM APIs cost and have limits based on usage. Avoid unnecessarily large models or large numbers of requests, and during development test with small inputs. Also be mindful of the free tier limits for Workers AI.

7. Tips for proceeding (finish in a short time)

  • First build the smallest thing that works (such as just one round-trip message). Deploy early, and add from there.
  • If you're unsure about an idea, think in terms of a single function of input → AI → output, such as summarization, proofreading, translation, classification, chat, image generation, or "memo → ○○".
  • Don't over-delegate everything to an agent. Move forward in small steps while running and checking things (npm run dev、npx hono request such as checking endpoints with ).
  • If you get stuck, reread the contents of the relevant existing skill (cloudflare / agents-sdk / hono).
  • If you're stuck, ask someone knowledgeable.

Reference links