PHASE 6 OF 7

Submission

What to put in your Devpost, README, and demo video, and when to submit.

The Submission Advantage

Judges pick winners after you've left the room. When they can't remember a project, the Devpost, repo, and demo video are the tiebreaker.

TL;DR Set aside 1-2 hours before the deadline for the Devpost, the README, and the demo video.

DEVPOST
Devpost README

For judges who missed your live demo, this is the project. Tell the whole story: problem, solution, tech, and what's next.

GITHUB
GitHub README

Technical judges click through to your repo to see how it works.

The Devpost is for every judge and the README is for the developers, so you need both.

VIDEO
Demo Video

The only part of your demo that's still there at deliberation. If a judge has forgotten your project, the video is how they see it working again.

Devpost calls the demo video one of the most important elements of your submission.

The Devpost README — Section by Section

Devpost gives every project the same seven sections, in this order.

TL;DR Open every section with its most concrete line, like a number or a named sponsor API.

1

Inspiration

Start with a number that makes the judge feel the problem. Our Dispatch AI opener (UC Berkeley AI Hackathon 2024) was "82% of emergency call centers are understaffed," from the 2023 NENA and Carbyne survey.

Skip "We wanted to help people." If you don't have a number you can source, open with a concrete scenario instead.

2

What It Does

Two or three sentences, then bullet the features. "Users check balances, transfer funds, and pay bills using voice commands" says something. "An AI-powered banking solution" doesn't.

The test: could a judge explain your project to another judge from this section alone?

3

How We Built It

Diagram first, then every API, framework, and service, grouped by frontend, backend, AI/ML, and infrastructure.

Sponsor judges want to see how you used their tech, so name it (Intel Dev Cloud, Hume, Retell) where they can't miss it.

4

Challenges We Ran Into

Name the ones that actually slowed you down. "Integrating multiple real-time APIs with different auth patterns" tells a judge what was hard. "We didn't have any challenges" reads like you didn't push.

5

Accomplishments

Tie them back to the problem you opened with. On Dispatch AI, "fine-tuned Mistral for emergency response" answered the understaffing stat.

If you measured something, put the number in, like "80% decrease in processing time" or "support for 6 languages."

6

What We Learned

Name the specific thing you learned, like "how to design multi-agent systems" or "the importance of multi-layered security."

This one matters more on educational and "best beginner" tracks.

7

What's Next

Two to four concrete steps, like "expand training data" or "partner with local emergency services for testing." Leave out the pie-in-the-sky stuff.

The GitHub README — Structure for Credibility

Technical judges open this one. Write it for someone who wants to know how it works and how to run it.

TL;DR Get the seven essentials into your repo README before you touch any of the extras.

MUST HAVE
Essential Elements
Do these first.
  • Project title + one-line description
  • Prize/award badge at the top (shields.io)
  • Demo video or hero screenshot
  • Tech stack badges (React, TypeScript, Tailwind, etc.)
  • Architecture diagram
  • Getting started / installation steps
  • Key features list

bonus points

NICE TO HAVE
Bonus Elements
Worth adding if you have time, or if the project will keep going after the hackathon.
  • Contributing guide
  • Detailed API documentation
  • Environment variable reference
  • Deployment instructions
  • License file

Show, Don't Tell

What to put in the Devpost besides text, and how much of each.

TL;DR Add an architecture diagram, 4-6 annotated screenshots, and a 60-90 second demo video.

DIAGRAMS
Architecture Diagrams

Draw the flow: user action → frontend → API → AI model → response. Put it at the top of “How We Built It.” The architecture slide from our Dispatch AI pitch showed the 911 call audio pipeline, the fine-tuned model, the dashboard, and where Twilio, Retell, and Hume fit in.

A diagram in Excalidraw takes about 15 minutes. Figma or a whiteboard photo works too.

SCREENSHOTS
Annotated Screenshots

Label the key flows with callouts and arrows. Then add a design-process image, the way DoggoAI's submission did: user personas, wireframes, and high-fidelity mockups next to the final product.

Recording Tools

Screen Studio (affiliate link) (Mac, my pick) or CanVid (Windows). Auto-zoom and webcam overlay mean editing takes minutes.

Video Length

60-90 seconds: the main flow, once. One take is fine.

Screenshot Count

4-6 images: hero shot, architecture diagram, 2-3 key flows, one design-process image.

The Demo Video

The video goes on the Devpost with everything else. The question is when you record it.

TL;DR If your event lets you edit the Devpost after the deadline, record the video in the gap before judging.

TIMING TIP

The demo video doesn't have to come out of your coding hours

At a lot of events the deadline freezes your code but not the Devpost entry, and judging often starts 1 to 2 hours later. If so, lock the repo, submit, then record the video and paste the YouTube link in that gap, so it doesn't eat 2 hours of feature work.

Check your event's rules first. Some count any edit after the deadline as a violation, or require the video link to submit. In that case, record before the deadline.

See two winning demo videos broken down, plus the recorder I use

On the pitching page: the TalkTuahBank and SoundSearch demos, and why they work.

Common Mistakes

A README nobody can skim, and a submission that lands a minute late.

TL;DR Submit 30 minutes before the deadline, with a README a judge can skim.

Wall of Text

A 2,000-word README with no images is hard to skim. Add headers, and put each screenshot beside the paragraph it illustrates.

Late Submission

Devpost deadlines are hard cutoffs. If you hit "submit" at 11:59 and Devpost lags, you're out.

Submission Checklist

The whole page as a list, in the order you'd do it.

TL;DR Work this list top to bottom in the 1-2 hours you blocked off before the deadline.

Write the Devpost README before the hackathon ends

Open Inspiration with a sourced number or a concrete scenario

Include an architecture diagram and 4-6 annotated screenshots in the submission

Record a 60-90 second demo video with a webcam overlay (Screen Studio or CanVid)

Write a separate GitHub README with tech badges, install instructions, and the architecture diagram

Name every sponsor technology in "How We Built It"

Submit to Devpost 30 minutes before the deadline

Proofread once and cut every word you don't need

AI Prompt Templates

Paste one into Claude, ChatGPT, or any AI tool, then fill in your project details at the bottom.

TL;DR Paste messy, detailed notes into the project section, then check every number in the output against them.

DEVPOST
Devpost README Generator
Writes all seven Devpost sections using the rules on this page, and only uses numbers you give it.

What to Paste Along With the Prompt

Project nameProblem / inspirationWhat it doesTech stack & APIs usedChallenges facedKey accomplishmentsWhat you learnedFuture plansSponsor technologies used
You are a hackathon submission expert. Generate a Devpost README for my hackathon project using the information I provide below.

Follow these rules strictly:

INSPIRATION SECTION:
- Open with a striking statistic, vivid scenario, or concrete number that makes the reader feel the problem BEFORE describing any solution. Only use numbers that appear in my project information; if there are none, open with a scenario
- Use bold markdown for key stats
- Do NOT start with "We wanted to..." or "Our team decided to...". Lead with the problem, not yourself
- 2-3 short paragraphs maximum. Make every sentence earn its place.

WHAT IT DOES SECTION:
- Start with 2-3 sentences summarizing the product from the user's perspective
- Then list 3-5 key features as bullet points with bold titles
- Be concrete and specific: "Users check balances, transfer funds, and pay bills using voice commands" NOT "An AI-powered solution"
- If relevant, mention the core user flow

HOW WE BUILT IT SECTION:
- Group technologies by category: Frontend, Backend, AI/ML, Infrastructure, APIs
- Name EVERY API, framework, library, and service used, especially sponsor technologies
- Describe the architecture briefly (e.g., "User speaks → Twilio captures audio → GPT-4 processes → response streamed back")
- If there's a system design or architecture image, reference it with ![Architecture](URL)
- Mention any custom datasets, fine-tuned models, or novel technical approaches

CHALLENGES WE RAN INTO SECTION:
- List 3-5 real, specific challenges, NOT generic ones
- Be honest. "Integrating multiple real-time APIs with different auth patterns" is good. "Time management" is lazy.
- Briefly mention how you overcame each challenge or what you learned from it

ACCOMPLISHMENTS THAT WE'RE PROUD OF SECTION:
- Tie accomplishments back to the original problem statement
- Include quantitative results only if I gave them to you (e.g., "80% reduction in inference time", "supports 6 languages")
- Mention any technical firsts or novel approaches

WHAT WE LEARNED SECTION:
- Focus on genuine technical and personal growth
- Be specific: "How to orchestrate multi-agent LLM systems" NOT "We learned a lot about AI"
- 3-5 bullet points

WHAT'S NEXT SECTION:
- 3-5 concrete, realistic next steps
- Mix short-term (next month) and medium-term (next year) goals
- Show the idea has legs beyond the hackathon without being delusional

GENERAL RULES:
- Use markdown formatting: bold for emphasis, bullet points for lists, headers for sections
- Follow the inverted pyramid: most important information first in every section
- Apply Orwell's rule: if a word can be cut without losing meaning, cut it
- Write in first person plural ("we") with energy and confidence
- Never invent statistics, metrics, awards, or quotes. Every number must come from my project information below.
- Total length: 800-1500 words. Comprehensive but not bloated.

---

HERE IS MY PROJECT INFORMATION (replace this section with your actual details):

Project Name: [YOUR PROJECT NAME]
Hackathon: [HACKATHON NAME]
Problem/Inspiration: [Describe the problem you're solving and why it matters]
What it does: [Describe what your project does from the user's perspective]
Tech stack: [List all technologies, APIs, frameworks, and services used]
Sponsor technologies: [List any sponsor APIs or tools you used; these are critical]
Challenges: [List the main challenges you faced]
Accomplishments: [What went well? Any metrics or quantitative results?]
What you learned: [Genuine learnings, technical and personal]
What's next: [Future plans for the project]
Additional context: [Any other details: team background, special features, design process, etc.]
GITHUB
GitHub README Generator
Writes a GitHub README with badges, architecture placeholders, and install instructions.

What to Paste Along With the Prompt

Project nameOne-line descriptionTech stackKey featuresInstall / setup stepsPrize won (if any)Hackathon nameTeam members
You are a developer documentation expert. Generate a polished GitHub README.md for my hackathon project using the information I provide below.

Follow these rules strictly:

STRUCTURE (in this exact order):

1. PROJECT TITLE AND BADGES
- Start with: # ProjectName
- If a prize was won, add a line like: ### 🏅 [Hackathon Name] - [Prize Won]
- Add a centered block of shields.io tech stack badges using this format:
  <img src="https://img.shields.io/badge/[TECH]-[COLOR]?style=for-the-badge&logo=[LOGO]&logoColor=white" alt="[TECH]">
- Group badges by "Frontend built with:" and "Backend built with:" with <br> tags
- Use the for-the-badge style for all badges

2. HERO SECTION
- Add a centered screenshot or demo video placeholder:
  <p align="center"><img width="1728" alt="Screenshot" src="YOUR_SCREENSHOT_URL"></p>
- Below it, write 2-3 sentences describing the project's purpose and impact
- Include a key statistic or problem statement in bold

3. WHAT IT DOES
- 2-3 sentence overview
- Bullet list of key features with bold titles

4. ARCHITECTURE / HOW WE BUILT IT
- Reference an architecture diagram: ![Architecture](URL)
- List the tech stack organized by category (Frontend, Backend, AI/ML, Infrastructure)
- For each technology, briefly explain WHY it was chosen and what role it plays
- Name every API and service

5. GETTING STARTED
- Prerequisites section with required tools/versions
- Step-by-step installation:
  ```bash
  git clone https://github.com/username/repo.git
  cd repo
  npm install  # or pip install -r requirements.txt
  ```
- Environment variables section:
  ```bash
  cp .env.example .env
  # Fill in your API keys
  ```
- How to run:
  ```bash
  npm run dev
  ```

6. KEY FEATURES (if not covered above)
- Detailed feature descriptions with sub-bullets if needed

7. CHALLENGES AND LEARNINGS
- Brief section on technical challenges overcome
- Key learnings from the project

8. WHAT'S NEXT
- 3-5 concrete future plans

9. TEAM / CONTRIBUTORS
- List team members with their roles and GitHub links
- Format: **Name** - Role - [@github](https://github.com/username)

10. LICENSE
- MIT License (or as specified)

GENERAL RULES:
- Use clean, consistent markdown formatting
- Code blocks should specify the language (bash, typescript, python, etc.)
- Keep descriptions concise — this README is for developers and technical judges
- Use shields.io badges for ALL technologies in the tech stack
- Include placeholder comments like <!-- Add screenshot here --> where images should go
- Write in a professional but energetic tone
- The README should make someone want to clone the repo and try it

---

HERE IS MY PROJECT INFORMATION (replace this section with your actual details):

Project Name: [YOUR PROJECT NAME]
One-line Description: [One sentence describing what it does]
Hackathon: [HACKATHON NAME]
Prize Won: [Prize name, or "N/A"]
Tech Stack - Frontend: [e.g., Next.js, React, TypeScript, Tailwind CSS, shadcn/ui]
Tech Stack - Backend: [e.g., Python, FastAPI, Node.js]
Tech Stack - AI/ML: [e.g., GPT-4, Whisper, custom fine-tuned model]
Tech Stack - Infrastructure: [e.g., Vercel, Supabase, Firebase, AWS]
APIs Used: [e.g., Twilio, Hume, Retell, Google Maps]
Key Features: [List 3-5 main features]
Install Steps: [How to set up and run the project locally]
Environment Variables Needed: [List required env vars like OPENAI_API_KEY, etc.]
Team Members: [Names, roles, and GitHub usernames]
License: [MIT / Apache 2.0 / etc.]
Additional Context: [Architecture details, special setup, hardware requirements, etc.]

Generate It With a Skill

If you'd rather have an agent read your repo and draft both, install these two skills from the Ship-It Toolkit.

TL;DR Install the readme-writer and devpost-writer skills to draft the GitHub README and the Devpost from your repo.

GITHUB WRITER SKILL
1. Write Your GitHub README
Reads your repo, asks for what it can't find, and writes the README (hero, badges, demo video, architecture diagram, team cards) plus the repo's About section. It won't invent awards or stats.
Install the GitHub Writer skill from https://github.com/IdkwhatImD0ing/hackathonstarterkit by running this in your terminal:

npx skills add IdkwhatImD0ing/hackathonstarterkit --skill readme-writer

Then use the readme-writer skill to write a winner-grade README for this hackathon project. Read the repo first to detect the stack and structure, then ask me for anything you can't find: the demo video link, the live URL and Devpost, any awards, the event details, and the team members with their GitHub and LinkedIn. Also set the repo's About metadata to match: the description, the website, and the topics/tags, using the gh CLI if it's available. Do not invent awards, stats, or prizes.
See the full GitHub Writer skill
DEVPOST WRITER SKILL
2. Write Your Devpost
Reads your repo and writes the Devpost section by section, plus the Built With tags and Try it out links. It won't invent awards, stats, or challenges.
Install the Devpost Writer skill and run it:

npx skills add IdkwhatImD0ing/hackathonstarterkit --skill devpost-writer

Use the devpost-writer skill to write our Devpost submission for this project. Read the repo first, then ask me for the demo video, the live URL, the hackathon and any awards, and the challenges we hit and what's next. Write the standard Devpost sections (inspiration, what it does, how we built it, challenges, accomplishments, what we learned, what's next), the Built With tags, and the Try it out links. Do not invent awards, stats, or challenges.

Building your portfolio site or YouTube description too?

The full Ship-It Toolkit, plus a single prompt that generates all four deliverables, is on the post-hackathon page.