IdkwhatImD0ing The Submission Advantage
Your submission is the artifact that outlives your pitch. Judges deliberate without you, so your Devpost, README, and demo video speak on your behalf.
TL;DR Judges deliberate without you, so your Devpost, README, and demo video are what win the room.
Treat the submission as a first-class deliverable, not a last-30-minutes rush. Your Devpost README, GitHub repo, and demo video are what judges reference during deliberation. When they can't remember your project, the submission is the tiebreaker.
Devpost README
Most judges read this during deliberation. It frames your project for everyone, including those who never saw your live demo. Tell the full story: problem, solution, tech, and vision.
Most hackathon winners allocate 1-2 hours specifically for writing this. It's not an afterthought.
GitHub README
Technical judges will click your repo link. Clean code, clear structure, and a README with architecture diagrams separate serious teams from weekend projects.
The GitHub README is for developers. The Devpost is for everyone. Write both.
Demo Video
Visual proof that persists into deliberation. When judges forget your project (it happens often), the demo video is the reminder. Nothing beats seeing it actually work.
Devpost calls the demo video one of the most important elements of your submission.
Tom Preston-Werner — GitHub Co-founder, “Readme Driven Development,” 2010
“Until you've written about your software, you have no idea what you'll be coding.”
Writing the README forces you to understand what you built. Documenting is clarifying, for yourself and for judges.
The Devpost README — Section by Section
Every Devpost submission follows the same template. Here's how to write each section so judges remember your project during deliberation.
TL;DR Lead every section with the point: a striking stat, a concrete feature, a named sponsor API.
Inspiration
Open with a striking stat that makes judges feel the problem. "82% of emergency call centers are understaffed." "1.7 billion adults remain unbanked." Make them care before you describe the solution.
Skip vague openers like "We wanted to help people." Concrete numbers stick in judges' minds during deliberation.
What It Does
2-3 sentences max, then bullet the key features. Be concrete and specific: "Users check balances, transfer funds, and pay bills using voice commands" beats "An AI-powered banking solution."
Name the user. Name the action. Name the outcome. Judges should be able to repeat your pitch to another judge from this section alone.
How We Built It
Architecture diagram first, then bullet every API, framework, and service. One system design image explains what 500 words cannot. Group by Frontend, Backend, AI/ML, and Infrastructure.
Name-drop sponsor tech prominently. Used Intel Dev Cloud, Hume, or Retell? Make it impossible to miss.
Challenges We Ran Into
Be honest and specific. "Integrating multiple APIs" or "fine-tuning the model for edge cases" reads as real. "We didn't have any challenges" signals you didn't push hard enough.
Challenges show maturity. Judges want real problems solved, not a project where everything went perfectly.
Accomplishments
Tie wins back to the original problem. "Fine-tuned Mistral for emergency response" closes the loop on the 82% understaffing stat. Connect problem to proof.
Quantify: "80% decrease in processing time," "support for 6 languages," "functional prototype in 18 hours."
What We Learned
Show growth, not just output. "How to design multi-agent systems" or "the importance of multi-layered security" prove depth of understanding beyond the code.
Especially important for educational and "best beginner" tracks. It proves the hackathon taught you something.
What's Next
Prove the idea has legs beyond the weekend. "Expand training data," "partner with local emergency services for testing," "mobile app integration." Show this isn't a throwaway.
List 2-4 concrete next steps. Skip pie-in-the-sky claims; judges spot the line between ambition and delusion.
The GitHub README — Structure for Credibility
Technical judges will click your repo link. A clean GitHub README with architecture diagrams and install instructions separates serious teams from weekend projects.
TL;DR A clean repo README with badges, a diagram, and install steps is your technical credibility signal.
Essential Elements
Every winning GitHub README includes these. No exceptions.
- 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
Non-negotiable
these make or break technical credibility
bonus points
bonus points
Bonus Elements
Extra polish that signals you care about quality beyond the hackathon.
- Contributing guide
- Detailed API documentation
- Environment variable reference
- Deployment instructions
- License file
Extra credit
separates good from great
Remember: The GitHub README is for developers and technical judges. The Devpost is for everyone. Write both, and tailor each to its reader.
TL;DR Lead with impact, cut every spare word, and show readers depth only when they ask for it.
The Inverted Pyramid
Put the most important information first. Judges skim, so your opening line decides whether they keep reading or move on to the next project.
Lead with impact, not backstory. “82% of call centers are understaffed” hooks instantly. “We're a team of four students who…” does not.
— Inverted pyramid, in widespread newspaper use since the early 1900s
The 6-Page Memo
“The reason writing a good 4 page memo is harder than ‘writing’ a 20 page powerpoint is because the narrative structure of a good memo forces better thought and better understanding of what's more important than what, and how things are related.”
Bezos banned PowerPoint at Amazon in 2004 in favor of structured narrative memos. Same idea for your Devpost: writing a coherent story forces you to understand what you built and why it matters.
— Jeff Bezos, Amazon founder and CEO, email to Amazon's S-Team, June 9, 2004
6 Rules for Clear Writing
“If it is possible to cut a word out, always cut it out.”
Orwell's 1946 rules fit hackathon submissions: never use a long word where a short one will do, never use the passive where you can use the active, and break any rule sooner than say anything barbarous.
— Politics and the English Language, 1946
Progressive Disclosure
Show essentials first, let readers drill deeper. Stripe's docs, the gold standard, do exactly this: quickstart at the top, architecture further down.
Apply to your README: hero screenshot and one-liner first. Architecture and install instructions for those who want depth.
Show, Don't Tell
A screenshot is worth a thousand words. An architecture diagram is worth a thousand meetings. A demo video is worth a thousand Devpost entries.
TL;DR Don't describe your app, show it: diagram the architecture and record it working.
“In descriptions of Nature one must seize on small details, grouping them so that when the reader closes his eyes he gets a picture. For instance, you'll have a moonlit night if you write that on the mill dam a piece of glass from a broken bottle glittered like a bright little star…”
Chekhov's principle for fiction applies perfectly to hackathon submissions. Don't describe your app; show it. Don't explain your architecture; diagram it. Don't claim it works; record it working.
Architecture Diagrams
One image beats 500 words of “How We Built It.” Show the flow: user action → frontend → API → AI model → response. Use Excalidraw, Figma, or a whiteboard photo.
Every winning Devpost in the examples above included an architecture diagram. It's not optional.
Annotated Screenshots
4-6 annotated shots of key flows, not raw captures. Add callouts, arrows, and labels that guide the reader. DoggoAI added design-process images that dramatically elevated its submission.
Include: user personas, wireframes, high-fidelity mockups, and the final product side-by-side. Show the journey.
Recording Tools
Screen Studio (Mac, my pick) or CanVid (Windows). Auto-zoom, instant effects, webcam overlay. Minutes, not hours.
Video Length
60-90 seconds. Long enough to show the flow, short enough to hold attention. One take is fine; authenticity beats polish.
Screenshot Count
4-6 annotated images. Hero shot, architecture diagram, 2-3 key flow screenshots, and one design process image.
The Demo Video
Your demo video is part of the submission: record it, link it on Devpost, and let the product on screen do the talking.
TL;DR Record a tight demo, link it on Devpost, and use the deadline gap so it never costs you build time.
The demo video does not have to come out of your coding hours
Deadlines freeze the code, not the listing. Devpost entries (including the YouTube link) usually stay editable after the deadline, and judging rarely starts for another 1 to 2 hours. Lock the repo, submit the Devpost, then record and paste the link in that gap. You get a polished demo without losing build time.
Confirm your hackathon's post-submission edit window before relying on it. The point: never let “I have to record a video” cost you 2 hours of feature work.
[See two winning demo videos broken down, plus the recorder I use
On the pitching page: the TalkTuahBank and SoundSearch demos, why they work, and the screen recorder for a polished demo.](https://thehackathonplaybook.dev/playbook/pitching#the-demo-video)
Common Mistakes
These six submission mistakes kill otherwise strong projects. Avoid them and you're already ahead of 80% of teams.
TL;DR Avoiding these six errors puts you ahead of 80% of teams before judging starts.
No Demo Video
Instant disadvantage. Judges can't remember what they can't see. A 60-second recording is your highest-ROI activity.
Wall of Text
Nobody reads a 2000-word README with no images. Break it up with screenshots, diagrams, and headers. Make judges scroll to find the point and you've lost them.
Vague Inspiration
"We wanted to help people" vs "82% of call centers are understaffed." The second makes judges care. The first makes them yawn.
Missing Tech Details
Sponsor judges want HOW you built it, not just WHAT. Name every API, framework, and service. Include the architecture diagram.
No Architecture Diagram
Makes the project feel unplanned and thrown together. One Excalidraw diagram takes 15 minutes and completely changes the perception of technical depth.
Late Submission
Devpost deadlines are hard cutoffs. Submit 30 minutes early. Teams lose every hackathon because they hit "submit" at 11:59 and Devpost lagged.
“…the narrative structure of a good memo forces better thought and better understanding of what's more important than what, and how things are related.”
— Jeff Bezos, Amazon founder and CEO, email to Amazon's S-Team, June 9, 2004
Your submission isn't an afterthought; it's the document that represents your project when you're not in the room. Teams that write great Devpost READMEs aren't adding fluff. They're forcing themselves to understand what they built, why it matters, and how to make someone else care.
Every section is an act of clarity. Inspiration forces you to articulate the problem. “How We Built It” forces you to understand your architecture. “What's Next” forces you to think beyond the weekend.
The best submission doesn't describe the project; it makes the reader wish they had built it.
Submission Checklist
A step-by-step summary for crafting your submission. Allocate 1-2 hours before the deadline: this is not optional.
TL;DR Block 1-2 hours before the deadline and work this list top to bottom.
Write the Devpost README BEFORE the hackathon ends. Allocate 1-2 dedicated hours.
Lead Inspiration with a striking stat or scenario, not "we wanted to help people"
Include an architecture diagram and 4-6 annotated screenshots in the submission
Record a 60-90 second demo video with Screen Studio or CanVid, with webcam overlay for personality
Write a separate GitHub README with tech badges, install instructions, and the architecture diagram
Name-drop every sponsor technology prominently in "How We Built It"; make it impossible to miss
Submit to Devpost 30 minutes before the deadline; never cut it close
Proofread once for Orwell: cut every word that doesn't earn its place
Remember: Judges deliberate without you. Your Devpost README, demo video, and GitHub repo are your advocates, the difference between “I think that project was good” and “I remember exactly why we should pick that one.”
AI Prompt Templates
Copy these prompts into Claude, ChatGPT, or any AI tool along with your project details. They're designed to generate submission-ready READMEs that follow every principle on this page.
TL;DR Paste these prompts plus your project details to generate a README that follows every rule above.
Devpost README Generator
Generates a complete Devpost submission using this page's winning patterns. Paste the prompt into any AI tool, then add your project details where indicated.
What to Paste Along With the Prompt
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
- Use bold markdown for key stats (e.g., **82% of call centers are understaffed**)
- 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 
- 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 where possible (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
- 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 README Generator
Generates a polished GitHub README with badges, architecture placeholders, and install instructions. Paste into any AI tool with your project details.
What to Paste Along With the Prompt
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: 
- 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:
cp .env.example .env # Fill in your API keys - How to run:
npm run dev
- KEY FEATURES (if not covered above)
- Detailed feature descriptions with sub-bullets if needed
- CHALLENGES AND LEARNINGS
- Brief section on technical challenges overcome
- Key learnings from the project
- WHAT'S NEXT
- 3-5 concrete future plans
- TEAM / CONTRIBUTORS
- List team members with their roles and GitHub links
- Format: Name - Role - @github
- 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 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.]
Pro tip: These prompts work best with raw, detailed input, even messy bullets. The AI structures it. Then proofread with Orwell's rule: cut every word that doesn't earn its place.
## Generate It With a Skill
Prefer an agent that reads your repo and does the work? Install these two skills to draft your GitHub README and Devpost writeup. They are part of the Ship-It Toolkit.
TL;DR Install the readme-writer and devpost-writer skills to draft both submission deliverables straight from your repo.
#### 1\. Write Your GitHub README
Writes a README with a centered hero, badges, a clickable demo video, an architecture diagram, and team cards, then sets the repo's About description, website, and topics to match. Reads your repo first, asks for facts it can't find, and never invents 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](https://thehackathonplaybook.dev/non-coders/skills/readme-writer)
#### 2\. Write Your Devpost
Writes the Devpost story section by section (inspiration, what it does, how you built it, challenges, what's next), plus the Built With tags and Try it out links. Reads your repo first and keeps every section honest.
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.](https://thehackathonplaybook.dev/playbook/post-hackathon#the-ship-it-toolkit)