Prompt Engineering
Relevant source files
The following files were used as context for generating this wiki page:Prompt engineering is a core feature of this application, responsible for transforming raw YouTube video transcripts into structured, high-value content. This is achieved by sending carefully crafted instructions, or "prompts," to the Google Gemini AI model. The system uses a suite of specialized prompts to generate different content formats, from concise notes to social media posts, all derived from the same source transcript.
The overall goal is to turn linear video content into a "Random Access Intelligence" engine, where different facets of the information can be accessed and repurposed on demand. The prompts are designed to be specific, rule-based, and format-aware to ensure the AI's output is consistent, reliable, and directly usable by the frontend components.
Sources: README.md, services/geminiService.ts
Content Generation Architecture
The content generation process is initiated after a video transcript is successfully loaded. The App.tsx component triggers this process, which is managed by the useContentGenerator hook. This hook orchestrates parallel API calls to the Gemini service for various content types.
Sources: App.tsx:40-45, hooks/useContentGenerator.ts:89-95
High-Level Data Flow
The following sequence diagram illustrates the flow from loading a transcript to displaying the generated content.
This diagram shows how useContentGenerator acts as a central coordinator, calling specific functions in geminiService.ts which contain the prompt logic for the Gemini API.
Sources: hooks/useContentGenerator.ts:98-103, App.tsx:40-45
System Instructions (Prompts)
The geminiService.ts file contains several constant strings that serve as system instructions for the AI. Each prompt is tailored for a specific task, defining the AI's persona, the desired output format, and a set of rules to follow.
Sources: services/geminiService.ts
Transcript Cleaning
This is the most fundamental prompt, used for generating "Margin Notes" when a user highlights text in the transcript.
- Purpose: To transform a raw, potentially messy transcript snippet into a concise, grammatically correct sentence.
- Persona: "Expert editor for video transcripts".
- Output: Cleaned text, with no introductory or concluding remarks.
const SYSTEM_INSTRUCTION = `
You are an expert editor for video transcripts.
Your task is to take a raw snippet of text from a YouTube transcript (which may contain filler words, stuttering, or lack punctuation) and transform it into a concise, grammatically correct summary sentence or bullet point.
Retain the original meaning and context.
Do not add any introductory or concluding remarks. Just output the cleaned text.
`;
This prompt is used by the cleanTranscriptText function, which is called from the useNotes hook when a user creates a new note.
Sources: services/geminiService.ts:4-11, hooks/useNotes.ts:31-32
Smart Board Content Generation
The "Smart Board" feature generates multiple content formats from the full transcript. Each format has a dedicated prompt with strict output requirements.
Twitter Thread
- Purpose: To create a viral-style Twitter thread (7-10 tweets).
- Persona: "Viral content creator for Twitter/X".
- Output: A numbered list of tweets, each under 240 characters. The service then parses this numbered list into a string array.
const THREAD_INSTRUCTION = `
You are a viral content creator for Twitter/X.
Your task is to convert a video transcript into a high-engagement Twitter thread (7-10 tweets).
- Tweet 1: Catchy hook that makes people want to read.
- Middle Tweets: Key insights, value, or storytelling from the transcript.
- Final Tweet: Conclusion or key takeaway.
Rules:
1. Each tweet MUST be under 240 characters (to leave room for quote-tweets).
2. Format the output as a numbered list with NO empty lines between tweets.
3. Use a clear pattern: "1. [Content]", "2. [Content]", etc.
4. Do not add any introductory or concluding text. Just the tweets.
`;
Sources: services/geminiService.ts:80-95
LinkedIn Post
- Purpose: To create a professional LinkedIn post.
- Persona: "Professional LinkedIn thought leader".
- Output: A strict JSON object with
hook,body,cta, andhashtagskeys.
const LINKEDIN_INSTRUCTION = `
You are a professional LinkedIn thought leader. Convert this video transcript into a compelling LinkedIn post.
Output EXACTLY in this JSON format (no markdown, no code blocks):
{"hook":"[Attention-grabbing first line]","body":"[3-4 paragraphs of value]","cta":"[Call to action]","hashtags":["tag1","tag2","tag3"]}
Rules:
- Hook: Bold statement or question (under 100 chars)
- Body: Professional tone, insights, lessons learned
- CTA: Encourage engagement
- Hashtags: 3-5 relevant tags
`;
Sources: services/geminiService.ts:160-171
Blog Post Outline
- Purpose: To generate an SEO-friendly blog post outline.
- Persona: "SEO content strategist".
- Output: A strict JSON object with
title,sections(an array of headings and bullet points), andseoKeywords.
const BLOG_INSTRUCTION = `
You are an SEO content strategist. Convert this video transcript into a blog post outline.
Output EXACTLY in this JSON format (no markdown, no code blocks):
{"title":"[SEO-optimized title]","sections":[{"heading":"H2 heading","bullets":["point1","point2"]}],"seoKeywords":["keyword1","keyword2"]}
Rules:
- Title: Compelling, under 60 chars
- Sections: 3-5 H2 headings with 2-4 bullet points each
- SEO Keywords: 5-7 relevant terms
`;
Sources: services/geminiService.ts:173-182
Key Takeaways
- Purpose: To extract 5-7 actionable key takeaways.
- Persona: "Learning assistant".
- Output: A strict JSON array of objects, each containing an
emojiandtext.
const TAKEAWAYS_INSTRUCTION = `
You are a learning assistant. Extract 5-7 key takeaways from this video transcript.
Output EXACTLY in this JSON format (no markdown, no code blocks):
[{"emoji":"🎯","text":"Takeaway 1"},{"emoji":"💡","text":"Takeaway 2"}]
Rules:
- Each takeaway is actionable and concise (under 100 chars)
- Use relevant emojis that match the content
- Focus on the most valuable insights
`;
Sources: services/geminiService.ts:184-193
Generic JSON Content Generation
To handle the prompts that require a specific JSON output, a generic helper function generateAIContent is used. This function abstracts the API call, response parsing, and error handling.
Sources: services/geminiService.ts:110-143
generateAIContent Flow
This flowchart shows the logic within the generateAIContent function.
This reusable pattern ensures that if the AI fails to return valid JSON, the application does not crash and instead receives a predefined fallback value.
Sources: services/geminiService.ts:110-143
API Call Configuration
All AI generation calls use the gemini-2.0-flash model and share a common structure for configuration, with temperature being the main variable to control creativity.
| Parameter | Value/Description | Source File |
|---|---|---|
model | gemini-2.0-flash | services/geminiService.ts:50 |
contents | The transcript text (sliced to AI_LIMITS.TRANSCRIPT_SLICE) | services/geminiService.ts:118 |
config.systemInstruction | The specific prompt string for the task. | services/geminiService.ts:119 |
config.temperature | Varies by task: 0.3 (Cleaning), 0.7 (Thread), 0.6 (LinkedIn), 0.5 (Blog), 0.4 (Takeaways) | services/geminiService.ts |
config.maxOutputTokens | 100 for transcript cleaning. Not specified for others. | services/geminiService.ts:52 |
Output Data Structures
The prompts are engineered to produce outputs that map directly to TypeScript interfaces defined in types.ts. This strong typing ensures data integrity between the AI service and the React components.
This diagram shows the relationship between the main ContentOutput type and the structures generated by the prompts.
Sources: types.ts:31-57
Extended Prompting: AI-Assisted Code Generation
Beyond transcript analysis, the repository contains an example of prompt engineering for a completely different domain: frontend code generation. The frontend-design/SKILL.md file is a detailed prompt designed to guide a large language model in creating "production-grade frontend interfaces" that avoid generic aesthetics.
This document demonstrates advanced prompting techniques:
- Persona Adoption: The AI is instructed to act with a "BOLD aesthetic direction."
- Conceptual Guidance: It provides abstract concepts like "Design Thinking," "Tone," and "Differentiation" to guide the AI's creative process.
- Negative Constraints: It explicitly tells the AI what to avoid ("NEVER use generic AI-generated aesthetics").
- Detailed Heuristics: It gives specific, actionable advice on typography, color, motion, and layout to achieve a high-quality result.
This file serves as a meta-prompt, a set of instructions for an AI on how to perform a complex, creative task, showcasing a sophisticated use of prompt engineering.
Sources: extensions/frontend-design/skills/frontend-design/SKILL.md