From 535c39cb7f834ffe7bbabd11cacc3ce6e3b43591 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:49:11 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 + README.md | 3 + plugin.lock.json | 64 ++ skills/content-brief-generator/SKILL.md | 496 ++++++++++++ .../references/content_frameworks.md | 707 +++++++++++++++++ .../references/seo_guidelines.md | 730 ++++++++++++++++++ .../references/tone_voice_guide.md | 690 +++++++++++++++++ .../scripts/generate_brief.sh | 568 ++++++++++++++ .../scripts/validate_brief.sh | 372 +++++++++ 9 files changed, 3642 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 plugin.lock.json create mode 100644 skills/content-brief-generator/SKILL.md create mode 100644 skills/content-brief-generator/references/content_frameworks.md create mode 100644 skills/content-brief-generator/references/seo_guidelines.md create mode 100644 skills/content-brief-generator/references/tone_voice_guide.md create mode 100755 skills/content-brief-generator/scripts/generate_brief.sh create mode 100755 skills/content-brief-generator/scripts/validate_brief.sh diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..300a671 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "content-brief-generator", + "description": "Generate comprehensive content briefs for writers, ensuring clarity, alignment, and strategic content creation across all formats.", + "version": "0.0.0-2025.11.28", + "author": { + "name": "James Rochabrun", + "email": "jamesrochabrun@gmail.com" + }, + "skills": [ + "./skills/content-brief-generator" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..19f5304 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# content-brief-generator + +Generate comprehensive content briefs for writers, ensuring clarity, alignment, and strategic content creation across all formats. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..ef736aa --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,64 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:jamesrochabrun/skills:content-brief-generator", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "aae7fbbb5316872513b4f33fab4fe0885b882423", + "treeHash": "16c649cee9b976c82947d92c3232c865093496bd8d206300b34d3e15824aeca9", + "generatedAt": "2025-11-28T10:17:45.949725Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "content-brief-generator", + "description": "Generate comprehensive content briefs for writers, ensuring clarity, alignment, and strategic content creation across all formats." + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "141b870b3737c1af89ca66524932f04404eeae1bc4519d09989bfeda4ebc682b" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "3f222e2672c0b0456302e9d80925d05ac06153b7586ae508dc8c13edab3c1003" + }, + { + "path": "skills/content-brief-generator/SKILL.md", + "sha256": "c095d8bba8680c204e8cc42d02136572f096ac2e9f1bdbb572668f09d36240d8" + }, + { + "path": "skills/content-brief-generator/references/seo_guidelines.md", + "sha256": "7412aaea577c3c169bdbd32ee973a52fb6024749787f33ae1dbc5dd5d52b32fa" + }, + { + "path": "skills/content-brief-generator/references/content_frameworks.md", + "sha256": "6ce59fb58f08890ff4e88958608eadcf0fe91b39d50f4cd3f3081e72847c3589" + }, + { + "path": "skills/content-brief-generator/references/tone_voice_guide.md", + "sha256": "e22d903c004908701049061a187567b4ba0b11f3562360934e2479c79b5540a6" + }, + { + "path": "skills/content-brief-generator/scripts/generate_brief.sh", + "sha256": "af93aaa4111d2525299eab4789525c674cd32dbd37dcde48e24cf172ec60e022" + }, + { + "path": "skills/content-brief-generator/scripts/validate_brief.sh", + "sha256": "2722d6e31f2135d1b3d97a68a6088c512a4a418254355fb18f54a0f39b5a3805" + } + ], + "dirSha256": "16c649cee9b976c82947d92c3232c865093496bd8d206300b34d3e15824aeca9" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/content-brief-generator/SKILL.md b/skills/content-brief-generator/SKILL.md new file mode 100644 index 0000000..ef344e8 --- /dev/null +++ b/skills/content-brief-generator/SKILL.md @@ -0,0 +1,496 @@ +--- +name: content-brief-generator +description: Generate comprehensive content briefs for writers, ensuring clarity, alignment, and strategic content creation across all formats. +--- + +# Content Brief Generator + +A comprehensive skill for creating detailed content briefs that guide writers, ensure consistency, and align content with business goals. + +## What This Skill Does + +Helps you create professional content briefs for: +- **Blog posts and articles** - Thought leadership, tutorials, how-tos +- **Technical documentation** - API docs, guides, README files +- **Marketing copy** - Landing pages, email campaigns, ads +- **Social media content** - Posts, campaigns, threads +- **Case studies** - Customer success stories +- **Whitepapers and reports** - In-depth research content +- **Product descriptions** - E-commerce and product pages +- **Video scripts** - YouTube, explainer videos, demos + +## Why Content Briefs Matter + +**Without a brief:** +- Unclear expectations and scope +- Multiple rounds of revisions +- Inconsistent tone and messaging +- Missing SEO opportunities +- Wasted time and resources + +**With a brief:** +- Clear direction and goals +- Fewer revisions needed +- Consistent quality +- SEO-optimized content +- Efficient workflow + +## Core Components of a Content Brief + +### 1. Content Overview +- Title/working title +- Content type (blog, doc, landing page, etc.) +- Target audience +- Primary goal (educate, convert, entertain, etc.) +- Key message or takeaway + +### 2. Audience & Context +- Target persona +- Reader's knowledge level +- Pain points and needs +- Where they are in the funnel +- How they'll discover content + +### 3. Strategic Elements +- Business objectives +- SEO keywords and intent +- Competitive landscape +- Success metrics +- CTAs and conversion goals + +### 4. Content Requirements +- Tone and voice +- Length/word count +- Structure and sections +- Research requirements +- Visual/media needs + +### 5. SEO & Distribution +- Primary and secondary keywords +- Search intent +- Meta description +- Internal/external links +- Distribution channels + +## Content Types & Templates + +### Blog Post Brief +**Use for:** Thought leadership, tutorials, listicles, how-tos + +**Key elements:** +- Hook and introduction angle +- Main points (typically 3-7) +- Examples and data to include +- Call-to-action +- Internal linking strategy + +### Technical Documentation Brief +**Use for:** API docs, guides, developer documentation + +**Key elements:** +- Technical accuracy requirements +- Code examples needed +- Audience technical level +- Prerequisites +- Related documentation + +### Landing Page Brief +**Use for:** Product pages, signup pages, campaign pages + +**Key elements:** +- Value proposition +- Benefits vs. features +- Social proof requirements +- Conversion goal +- A/B testing plan + +### Case Study Brief +**Use for:** Customer success stories, testimonials + +**Key elements:** +- Customer background +- Problem/solution/results framework +- Metrics and outcomes +- Quotes needed +- Industry context + +## Content Structure Frameworks + +### AIDA (Attention, Interest, Desire, Action) +**Best for:** Marketing copy, sales pages + +1. **Attention:** Grab with headline +2. **Interest:** Build with benefits +3. **Desire:** Create want with proof +4. **Action:** Drive with clear CTA + +### PAS (Problem, Agitate, Solve) +**Best for:** Blog posts, email campaigns + +1. **Problem:** Identify pain point +2. **Agitate:** Emphasize urgency +3. **Solve:** Present solution + +### Inverted Pyramid +**Best for:** News, technical docs + +1. Most important info first +2. Supporting details +3. Background context + +### Storytelling Arc +**Best for:** Case studies, narratives + +1. Setup (character/situation) +2. Conflict (challenge) +3. Resolution (solution) +4. Takeaway (lesson) + +## SEO Integration + +### Keyword Strategy +- Primary keyword (1) +- Secondary keywords (2-3) +- Long-tail variations (3-5) +- LSI keywords (related terms) + +### Search Intent +- **Informational:** Learn about something +- **Navigational:** Find specific page +- **Commercial:** Compare options +- **Transactional:** Ready to buy + +### On-Page SEO +- Title tag (include primary keyword) +- Meta description (compelling + keyword) +- Headers (H1, H2, H3 with keywords) +- Image alt text +- Internal linking + +## Tone & Voice Guidelines + +### Tone Spectrum +- **Formal ↔ Casual** +- **Serious ↔ Playful** +- **Respectful ↔ Irreverent** +- **Enthusiastic ↔ Matter-of-fact** + +### Voice Attributes +Define your brand voice: +- **Professional but approachable** (like Stripe) +- **Technical but friendly** (like Twilio) +- **Playful and bold** (like Mailchimp) +- **Authoritative and trustworthy** (like HubSpot) + +### Writing Style +- Active vs. passive voice +- Person (1st, 2nd, 3rd) +- Sentence length +- Paragraph structure +- Use of jargon + +## Research & Sourcing + +### Research Requirements +- **Primary research:** Interviews, surveys, original data +- **Secondary research:** Industry reports, competitor analysis +- **Expert quotes:** SME interviews, third-party experts +- **Data and statistics:** Credible sources, recent data +- **Examples:** Real-world cases, screenshots + +### Citation Standards +- Link to original sources +- Attribute quotes +- Recent data (within 1-2 years) +- Authoritative sources +- Fact-checking requirements + +## Visual & Media Requirements + +### Images +- Hero image specifications +- In-content images (how many, what type) +- Screenshots or diagrams +- Charts or infographics +- Alt text requirements + +### Video/Audio +- Video length and format +- Screen recordings needed +- B-roll requirements +- Audio quality standards + +### Other Media +- Code snippets +- Downloadable resources +- Interactive elements +- Embedded content + +## Workflow & Process + +### 1. Brief Creation (This Skill) +Use `generate_brief.sh` to create comprehensive brief + +### 2. Research & Outline +Writer researches and creates outline + +### 3. First Draft +Writer creates content following brief + +### 4. Review & Edit +Editor reviews against brief requirements + +### 5. SEO Optimization +SEO review and optimization + +### 6. Final Approval +Stakeholder sign-off + +### 7. Publication +Publish and distribute + +### 8. Performance Tracking +Monitor metrics defined in brief + +## Success Metrics by Content Type + +### Blog Post +- Organic traffic +- Time on page (3+ minutes) +- Scroll depth +- Social shares +- Backlinks +- Lead generation + +### Technical Documentation +- Page views +- Time on page +- Search rankings +- Feedback ratings +- Support ticket reduction + +### Landing Page +- Conversion rate +- Bounce rate +- Time on page +- Click-through rate +- Form submissions + +### Case Study +- Downloads +- Leads generated +- Sales pipeline influence +- Share rate + +## Common Content Brief Mistakes + +### ❌ Avoid These + +**Too Vague:** +"Write about our product" +→ No clear audience, goal, or angle + +**No Research:** +Missing competitor analysis and keyword research +→ Content won't rank or differentiate + +**Unclear Voice:** +"Make it engaging" +→ Not specific enough for consistency + +**Missing CTAs:** +No clear next step for readers +→ Missed conversion opportunities + +**Ignoring SEO:** +No keyword strategy +→ Content won't be discovered + +### ✅ Do This Instead + +**Specific:** +"Write 1500-word tutorial for junior developers on JWT authentication, including code examples in Node.js" + +**Research-Backed:** +"Target keyword 'JWT authentication tutorial' (2.4K monthly searches), compete with existing articles from Auth0 and FreeCodeCamp" + +**Clear Voice:** +"Technical but approachable - explain like a senior dev mentoring a junior, use examples, avoid jargon" + +**Action-Oriented:** +"CTA: Sign up for free API key, secondary: Join Discord community" + +**SEO-Optimized:** +"Primary: 'JWT authentication', Secondary: 'JSON web token Node.js', 'secure API authentication'" + +## Using This Skill + +### Generate a Content Brief + +```bash +./scripts/generate_brief.sh +``` + +Interactive workflow will guide you through: +1. Content type and audience +2. Goals and objectives +3. SEO requirements +4. Structure and requirements +5. Success metrics + +### Validate a Brief + +```bash +./scripts/validate_brief.sh path/to/brief.md +``` + +Checks for: +- Required sections present +- Keyword strategy defined +- Target audience specified +- Success metrics included +- Completeness score + +### Access Templates + +``` +references/content_brief_template.md - Complete template +references/seo_guidelines.md - SEO best practices +references/content_frameworks.md - Structure frameworks +references/tone_voice_guide.md - Voice guidelines +``` + +## Content Brief Checklist + +- [ ] **Clear title** and content type +- [ ] **Target audience** defined with persona details +- [ ] **Primary goal** and business objective +- [ ] **Keyword research** completed +- [ ] **Search intent** identified +- [ ] **Tone and voice** specified +- [ ] **Word count** target +- [ ] **Structure** and key sections outlined +- [ ] **Research sources** identified +- [ ] **Examples** and data requirements +- [ ] **Visual needs** specified +- [ ] **CTAs** defined +- [ ] **Success metrics** established +- [ ] **Competitor content** analyzed +- [ ] **Distribution plan** outlined + +## Quick Start Examples + +### "Create a blog post brief" +System generates comprehensive brief with: +- SEO keyword strategy +- Audience targeting +- Structure recommendations +- Success metrics + +### "Write technical documentation brief for API" +System creates technical brief with: +- Technical requirements +- Code example specifications +- Audience skill level +- Documentation standards + +### "Generate landing page brief" +System builds conversion-focused brief with: +- Value proposition guidance +- CTA strategy +- A/B testing recommendations +- Conversion metrics + +## Best Practices + +### 1. Start With Research +- Analyze top-ranking content +- Understand search intent +- Identify content gaps +- Review competitor approach + +### 2. Be Specific +- Exact word count +- Specific examples needed +- Clear tone guidelines +- Defined success metrics + +### 3. Align With Strategy +- Connect to business goals +- Fit content calendar +- Support funnel stage +- Match brand voice + +### 4. Make It Actionable +- Clear deliverables +- Specific requirements +- Concrete examples +- Measurable outcomes + +### 5. Iterate and Improve +- Track performance +- Update based on results +- Refine over time +- Learn from top performers + +## Integration With Other Workflows + +### Content Calendar +Brief creation triggers calendar entry + +### SEO Tools +Keywords from SEMrush, Ahrefs, etc. + +### Project Management +Brief becomes Jira/Asana task + +### CMS +Brief exported to content management system + +### Analytics +Success metrics tracked in dashboards + +## Tips for Different Writer Types + +### Content Writers +- Focus on audience and storytelling +- Emphasize research requirements +- Clear brand voice guidelines + +### Technical Writers +- Specify technical accuracy needs +- Define audience knowledge level +- Include code example requirements + +### Copywriters +- Highlight conversion goals +- Specify A/B testing needs +- Clear CTA strategy + +### Content Marketers +- Connect to funnel stage +- Define distribution strategy +- Specify lead generation goals + +## Resources + +All reference materials included: +- Complete content brief template +- SEO optimization guidelines +- Content structure frameworks +- Tone and voice development guide +- Copywriting formulas and examples + +## Summary + +Content briefs ensure: +- **Clarity** - Everyone knows expectations +- **Efficiency** - Fewer revisions needed +- **Quality** - Consistent, strategic content +- **Results** - Content that achieves goals + +Use this skill to create comprehensive briefs that guide writers to success. + +--- + +**Remember:** Time spent on a good brief saves 10x time in revisions. Get it right before writing begins. diff --git a/skills/content-brief-generator/references/content_frameworks.md b/skills/content-brief-generator/references/content_frameworks.md new file mode 100644 index 0000000..bdb914e --- /dev/null +++ b/skills/content-brief-generator/references/content_frameworks.md @@ -0,0 +1,707 @@ +# Content Structure Frameworks + +Proven frameworks for organizing and writing compelling content. + +--- + +## Overview + +Content frameworks are repeatable structures that guide writing and ensure your content achieves its goals. Use these templates to outline before writing. + +--- + +## AIDA (Attention, Interest, Desire, Action) + +**Best for:** Marketing copy, sales pages, landing pages, email campaigns + +### Structure + +**1. Attention (Headline/Hook)** +- Grab attention immediately +- Promise a benefit +- Create curiosity + +**2. Interest (Build engagement)** +- Explain the problem +- Show you understand their pain +- Present relevant information + +**3. Desire (Create want)** +- Show benefits and outcomes +- Provide social proof +- Paint a picture of success + +**4. Action (Drive conversion)** +- Clear call-to-action +- Remove friction +- Create urgency + +### Example Outline + +```markdown +# Stop Wasting Hours on Manual Testing [Attention] + +## Testing doesn't have to be painful [Interest] +- Current state of manual testing +- Why it's time-consuming +- Hidden costs of bugs in production + +## Automated testing changes everything [Desire] +- Save 20 hours per week +- Catch bugs before deployment +- Team testimonials +- ROI calculator + +## Start automating today [Action] +- Free trial (no credit card) +- 5-minute setup +- CTA button +``` + +--- + +## PAS (Problem, Agitate, Solve) + +**Best for:** Blog posts, emails, social media, persuasive content + +### Structure + +**1. Problem** +- Identify the pain point +- Show you understand it +- Make it relatable + +**2. Agitate** +- Amplify the problem +- Show consequences of inaction +- Create urgency +- Use emotion + +**3. Solve** +- Present your solution +- Show how it solves the problem +- Provide proof +- Call-to-action + +### Example Outline + +```markdown +# Problem: Your API is slow +- Users complain about response times +- You're losing customers +- You don't know why + +# Agitate: It's getting worse +- Every 100ms delay = 1% revenue loss +- Competitors are faster +- Your reputation suffers +- Engineers are overwhelmed debugging + +# Solve: Our monitoring platform +- Real-time performance tracking +- Identify bottlenecks instantly +- Optimize before users notice +- Case study: 50% faster in 2 weeks +- CTA: Start free trial +``` + +--- + +## Inverted Pyramid + +**Best for:** News articles, technical documentation, business content + +### Structure + +**1. Most important (Lead)** +- Who, what, when, where, why (5 Ws) +- Key information first +- Answer main question + +**2. Supporting details** +- Context and background +- Additional facts +- Quotes and data + +**3. Background information** +- Less critical details +- Historical context +- Related information + +### Example Outline + +```markdown +# Lead (Most important) +Next.js 14 released today with major performance improvements: +- 50% faster builds +- Built-in caching +- Server Actions stable + +# Supporting details +- How Server Actions work +- Performance benchmarks +- Migration guide from v13 +- Developer quotes + +# Background +- History of Next.js +- Previous version features +- Future roadmap +``` + +--- + +## Storytelling Arc + +**Best for:** Case studies, brand stories, narrative content, testimonials + +### Structure + +**1. Setup (Character & Context)** +- Introduce protagonist +- Set the scene +- Establish normal state + +**2. Conflict (Challenge)** +- Problem arises +- Stakes are established +- Tension builds + +**3. Resolution (Solution)** +- How problem was solved +- Journey and obstacles +- Transformation + +**4. Takeaway (Lesson)** +- What was learned +- Broader implications +- Call-to-action + +### Example Outline + +```markdown +# Setup +- Meet Sarah, CTO of startup +- Team of 20 engineers +- Managing infrastructure manually + +# Conflict +- Infrastructure costs spiraling +- Deployment taking 4 hours +- Engineers frustrated +- Investors questioning spend + +# Resolution +- Discovered our platform +- Implemented in 2 weeks +- Automated deployments +- Cut costs 60% + +# Takeaway +- Infrastructure-as-code is essential +- Right tools unlock velocity +- CTA: See how you can automate +``` + +--- + +## How-To / Tutorial + +**Best for:** Educational content, guides, tutorials, instructions + +### Structure + +**1. Introduction** +- What you'll learn +- Why it matters +- Prerequisites +- Time estimate + +**2. Step-by-step instructions** +- Numbered sequential steps +- One action per step +- Screenshots/code examples +- Expected results + +**3. Troubleshooting** +- Common errors +- Solutions +- How to get help + +**4. Conclusion** +- What you accomplished +- Next steps +- Related resources + +### Example Outline + +```markdown +# How to Deploy a Next.js App to Vercel + +## Introduction +- What you'll build +- Prerequisites: Node.js, Git, Next.js app +- Time: 10 minutes + +## Steps +1. Create Vercel account + - Go to vercel.com + - Sign up with GitHub + - Screenshot + +2. Connect repository + - Click "New Project" + - Select repo + - Screenshot + +3. Configure settings + - Framework: Next.js + - Build command + - Environment variables + +4. Deploy + - Click "Deploy" + - Wait for build + - View live site + +## Troubleshooting +- Build fails: Check Node version +- ENV vars missing: Add in settings + +## Next Steps +- Custom domain +- CI/CD integration +- Performance monitoring +``` + +--- + +## Listicle + +**Best for:** Top X articles, roundups, comparison posts, curated lists + +### Structure + +**1. Introduction** +- Why this list matters +- How items were selected +- Quick overview + +**2. List items (typically 5-10)** +- Each item: Title + description +- Benefits and features +- Examples or screenshots +- Why it's on the list + +**3. Conclusion** +- Summary +- Recommendation +- CTA + +### Listicle Types + +**Numbered (Ranked):** +- Best to worst +- Most to least important +- Sequential order + +**Bulleted (Unranked):** +- Equal weight +- Any order +- No hierarchy + +### Example Outline + +```markdown +# 7 Essential VS Code Extensions for Python Developers + +## Introduction +- Why VS Code for Python +- How we selected these +- All are free + +## List +1. Pylance + - What it does + - Key features + - Installation + - Screenshot + +2. Python (Microsoft) + - Core extension + - Debugging features + - Why it's #1 + +[Continue for 7 items] + +## Conclusion +- Start with top 3 +- Try others as needed +- CTA: Share your favorites +``` + +--- + +## Comparison / Versus + +**Best for:** Product comparisons, alternative posts, decision content + +### Structure + +**1. Introduction** +- What's being compared +- Why it matters +- Quick verdict (optional) + +**2. Overview of each option** +- Brief description +- Key features +- Ideal user + +**3. Head-to-head comparison** +- Feature by feature +- Use table format +- Pros and cons + +**4. Use cases** +- When to use Option A +- When to use Option B +- Special scenarios + +**5. Verdict** +- Recommendation +- Decision framework +- CTA + +### Example Outline + +```markdown +# React vs Vue: Which Framework to Choose in 2024 + +## Introduction +- Both are popular +- Key differences matter +- We'll help you decide + +## React Overview +- Created by Facebook +- JSX syntax +- Large ecosystem +- Best for: Enterprise + +## Vue Overview +- Progressive framework +- Template syntax +- Gentle learning curve +- Best for: Rapid development + +## Feature Comparison + +| Feature | React | Vue | +|---------|-------|-----| +| Learning curve | Steep | Gentle | +| Performance | Excellent | Excellent | +| Ecosystem | Huge | Growing | + +## Use Cases +- Choose React if: Large team, TypeScript +- Choose Vue if: Solo dev, quick prototype + +## Verdict +- No wrong choice +- Context matters +- CTA: Try both with tutorial +``` + +--- + +## Ultimate Guide / Pillar Content + +**Best for:** Comprehensive resources, cornerstone content, authority building + +### Structure + +**1. Introduction (Table of Contents)** +- What's covered +- Who it's for +- How to use guide +- Jump links to sections + +**2. Fundamentals** +- Basic concepts +- Terminology +- Why it matters + +**3. Deep Dive Sections** +- Multiple major sections +- Each could be standalone post +- Comprehensive coverage + +**4. Advanced Topics** +- Expert-level content +- Edge cases +- Best practices + +**5. Resources** +- Tools and software +- Further reading +- Related guides + +**6. FAQ** +- Common questions +- Quick answers + +### Example Outline + +```markdown +# The Complete Guide to API Authentication (2024) + +## Table of Contents +[Jump links to all sections] + +## Introduction +- Why authentication matters +- What you'll learn +- Who this is for + +## Part 1: Authentication Basics +- What is authentication vs authorization +- Common methods overview +- Security principles + +## Part 2: API Keys +- How they work +- Implementation guide +- Pros and cons +- Best practices + +## Part 3: OAuth 2.0 +- OAuth flow explained +- Implementation +- Use cases +- Security considerations + +## Part 4: JWT Tokens +- How JWT works +- Implement in Node.js +- Refresh tokens +- Security tips + +## Part 5: Best Practices +- Security checklist +- Performance optimization +- Error handling +- Testing authentication + +## Tools & Resources +- Libraries and frameworks +- Testing tools +- Further reading + +## FAQ +- 10+ common questions + +## Conclusion +- Key takeaways +- Choose right method +- Next steps +``` + +--- + +## Feature Announcement + +**Best for:** Product launches, new feature releases, updates + +### Structure + +**1. Headline + Visual** +- Clear announcement +- What's new +- Eye-catching graphic + +**2. The Problem** +- What users struggled with +- Why we built this + +**3. The Solution** +- How feature solves it +- Key benefits +- Demo or video + +**4. How It Works** +- Step-by-step +- Screenshots +- Technical details + +**5. Availability** +- Who can use it +- How to access +- Pricing (if applicable) + +**6. What's Next** +- Future improvements +- Feedback request +- Related features + +### Example Outline + +```markdown +# Introducing Real-Time Collaboration + +[Hero image/GIF] + +## The Problem +- Users couldn't work together +- Version conflicts +- Lost changes + +## The Solution +- Live cursors +- Instant updates +- Conflict resolution +- 50ms latency + +## How It Works +1. Invite team members +2. See who's online +3. Work simultaneously +4. Changes sync instantly + +## Available Now +- All Pro plans +- No additional cost +- Enable in settings + +## What's Next +- Comments coming soon +- Video chat integration +- We'd love your feedback +``` + +--- + +## Thought Leadership / Opinion + +**Best for:** Industry commentary, trend analysis, hot takes + +### Structure + +**1. Strong Opening** +- Contrarian take or +- Bold prediction or +- Provocative question + +**2. Current State** +- What most people think +- Common assumptions +- Status quo + +**3. Your Perspective** +- Why you disagree or +- What others are missing +- Your unique insight + +**4. Evidence** +- Data and examples +- Trends you're seeing +- Expert opinions + +**5. Implications** +- What this means +- Who's affected +- What should change + +**6. Call-to-Action** +- What readers should do +- Discussion prompt +- Share thoughts + +### Example Outline + +```markdown +# Microservices Are Overrated (And Here's Why) + +## Opening +- Everyone wants microservices +- Most don't need them +- Monoliths are underrated + +## Current State +- Industry trends +- Why microservices are popular +- What blogs/consultants say + +## My Perspective +- Complexity costs +- Most apps aren't at scale +- Premature optimization + +## Evidence +- Case studies of failures +- Cost analysis +- When microservices make sense + +## Implications +- Start with monolith +- Extract services later +- Focus on business value + +## Conclusion +- Challenge the hype +- Make informed decisions +- Share your experience +``` + +--- + +## Framework Selection Guide + +**Choose framework based on:** + +| Goal | Best Framework | +|------|----------------| +| Drive conversions | AIDA, PAS | +| Educate/inform | Inverted Pyramid, How-To | +| Build authority | Ultimate Guide, Thought Leadership | +| Compare options | Comparison, Listicle | +| Tell story | Storytelling Arc | +| Announce feature | Feature Announcement | + +**Multiple frameworks:** +- Can combine frameworks +- Example: Storytelling intro + How-To body +- Adapt to your needs + +--- + +## Template for Any Framework + +```markdown +# [Compelling Title] + +## Hook (First 100 words) +- Grab attention +- State problem or benefit +- Include primary keyword + +## Body (Main content) +- [Apply chosen framework] +- Use subheadings +- Include examples +- Add visuals + +## Conclusion +- Summarize key points +- Reinforce main takeaway +- Clear CTA + +## Additional Resources +- Internal links +- External references +- Further reading +``` + +--- + +**Remember:** Frameworks are starting points, not rigid rules. Adapt them to your content needs and audience. diff --git a/skills/content-brief-generator/references/seo_guidelines.md b/skills/content-brief-generator/references/seo_guidelines.md new file mode 100644 index 0000000..05ad811 --- /dev/null +++ b/skills/content-brief-generator/references/seo_guidelines.md @@ -0,0 +1,730 @@ + + +# SEO Guidelines for Content Briefs + +Comprehensive SEO best practices for content writers to rank higher and drive organic traffic. + +--- + +## SEO Fundamentals + +### What is SEO? + +**Search Engine Optimization (SEO)** is the practice of optimizing content to rank higher in search engine results pages (SERPs) and drive organic (unpaid) traffic. + +**Key components:** +- **Technical SEO:** Site structure, performance, indexing +- **On-page SEO:** Content optimization, keywords, meta tags +- **Off-page SEO:** Backlinks, domain authority, social signals + +**This guide focuses on on-page SEO for content creation.** + +--- + +## Keyword Research + +### Finding the Right Keywords + +**1. Start with seed keywords** +- Your main topic or product +- What users search for +- Industry terminology + +**2. Expand with keyword tools** +- **Google Keyword Planner** (free) +- **Ahrefs** (paid, comprehensive) +- **SEMrush** (paid, competitive analysis) +- **Ubersuggest** (freemium) +- **AnswerThePublic** (question-based keywords) + +**3. Analyze keyword metrics** + +| Metric | What It Means | Good Target | +|--------|---------------|-------------| +| Search Volume | Monthly searches | 500-10K for most content | +| Keyword Difficulty | Competition (0-100) | < 40 for newer sites | +| CPC | Paid ad cost | Higher = more commercial | +| SERP Features | Rich snippets, featured boxes | Opportunity to capture | + +**4. Evaluate search intent** + +**Types of search intent:** +- **Informational:** "how to", "what is", "guide to" +- **Navigational:** Brand names, specific pages +- **Commercial:** "best", "review", "comparison" +- **Transactional:** "buy", "price", "discount" + +**Match content type to intent:** +- Informational → Blog posts, guides, tutorials +- Commercial → Reviews, comparisons, listicles +- Transactional → Product pages, landing pages + +--- + +## Keyword Strategy + +### Primary Keyword +**One main target keyword per piece of content** + +**Characteristics:** +- Relevant to topic +- Moderate search volume (500-10K typically) +- Achievable difficulty +- Matches search intent + +**Example:** +For a tutorial on JWT authentication: +- Primary: "JWT authentication tutorial" (2,400/month, KD 35) + +### Secondary Keywords +**2-4 related keywords that support the primary** + +**Types:** +- Synonyms: "JSON web token tutorial" +- Related terms: "JWT Node.js", "secure API authentication" +- Long-tail variations: "how to implement JWT authentication" + +**Example:** +- Secondary: "JSON web token Node.js", "JWT implementation guide", "API authentication tutorial" + +### LSI Keywords (Latent Semantic Indexing) +**Related terms that provide context** + +**How to find:** +- Google "related searches" at bottom of SERP +- "People also ask" boxes +- LSIGraph tool +- Ahrefs "Also rank for" section + +**Example:** +For JWT content: "access token", "refresh token", "bearer token", "authentication flow", "authorization header" + +--- + +## On-Page SEO Elements + +### Title Tag (H1) + +**Requirements:** +- Include primary keyword +- 50-60 characters (to avoid truncation) +- Compelling and click-worthy +- Front-load important words + +**Formula:** +`[Primary Keyword]: [Benefit/Hook] | [Brand]` + +**Examples:** + +❌ Bad: +- "Authentication" (too vague) +- "The Complete, Comprehensive, Ultimate Guide to JSON Web Token Authentication in Node.js Applications" (too long) + +✅ Good: +- "JWT Authentication Tutorial: Secure Your Node.js API in 10 Minutes" +- "How to Implement JWT Authentication | Complete Node.js Guide" + +**Best practices:** +- Use power words: "Complete", "Ultimate", "Essential", "Proven" +- Include numbers: "10 Minutes", "5 Steps", "2024 Guide" +- Address user intent: "How to", "Step-by-Step", "Quick Start" + +--- + +### Meta Description + +**Requirements:** +- 150-160 characters +- Include primary keyword +- Compelling call-to-action +- Accurate summary + +**Not a ranking factor but affects CTR (click-through rate)** + +**Formula:** +`[Problem] + [Solution] + [Benefit/CTA]` + +**Examples:** + +❌ Bad: +- "Learn about JWT authentication" (boring, no value) +- "This article covers everything you need to know about JSON Web Tokens, including how they work, how to implement them, and best practices" (too long, truncated) + +✅ Good: +- "Learn JWT authentication with Node.js in 10 minutes. Step-by-step tutorial with code examples. Secure your API today." +- "Implement JWT authentication in your Node.js app. Complete guide with Express.js examples and security best practices." + +--- + +### Headers (H2, H3, H4) + +**Purpose:** +- Structure content for readability +- Signal topic relevance to search engines +- Improve featured snippet chances + +**Best practices:** + +**H2 (Main sections):** +- Include keywords naturally +- 3-7 H2s per article typically +- Descriptive and scannable + +**H3 (Subsections):** +- Support H2 topics +- Use long-tail keywords +- Answer specific questions + +**Examples:** + +✅ Good header structure: +``` +# JWT Authentication Tutorial [H1] + +## What Is JWT Authentication? [H2 - keyword + question] + +## How JWT Authentication Works [H2 - keyword + process] +### The Authentication Flow [H3] +### Access Tokens vs Refresh Tokens [H3] + +## Implementing JWT in Node.js [H2 - keyword + action] +### Installing Dependencies [H3] +### Creating JWT Tokens [H3] +### Verifying JWT Tokens [H3] + +## JWT Security Best Practices [H2 - keyword + value] +``` + +**Avoid:** +- Generic headers: "Introduction", "Conclusion" +- Keyword stuffing: "JWT JWT JWT Authentication" +- Skipping heading levels (H2 → H4) + +--- + +### Content Body + +**Keyword usage:** + +**Primary keyword placement:** +- [ ] First 100 words (important!) +- [ ] In H1 (title) +- [ ] In at least one H2 +- [ ] In URL slug +- [ ] 3-5 times throughout content (naturally) +- [ ] In conclusion + +**Secondary keywords:** +- [ ] Sprinkle naturally throughout +- [ ] In H2s and H3s where relevant +- [ ] In image alt text +- [ ] In anchor text for internal links + +**Keyword density:** +- **Target: 0.5-2.5%** of total words +- Don't obsess over exact percentage +- Prioritize natural writing +- Use synonyms and variations + +**Example:** + +❌ Bad (keyword stuffing): +"JWT authentication is important. JWT authentication secures your API. Implementing JWT authentication with JWT authentication libraries makes JWT authentication easier." + +✅ Good (natural use): +"JWT authentication provides a secure way to handle user sessions in modern APIs. This token-based approach offers several advantages over traditional session management..." + +--- + +### Internal Linking + +**Why it matters:** +- Distributes page authority +- Helps search engines discover pages +- Improves user engagement +- Reduces bounce rate + +**Best practices:** +- **3-5 internal links** per blog post +- Link to relevant related content +- Use descriptive anchor text (not "click here") +- Link to authoritative pages +- Create content clusters + +**Anchor text examples:** + +❌ Bad: +- "Click here to learn more" +- "Read this article" +- Full URLs as anchor text + +✅ Good: +- "Learn about [secure API design patterns](link)" +- "Our [Node.js security guide](link) covers..." +- "For more on [authentication vs authorization](link)..." + +**Content clustering:** +``` +Pillar Page: "Complete Guide to API Authentication" + ├─ Cluster: "JWT Authentication Tutorial" + ├─ Cluster: "OAuth 2.0 Implementation Guide" + ├─ Cluster: "API Key Best Practices" + └─ Cluster: "Session vs Token Authentication" +``` + +--- + +### External Linking + +**Why link externally:** +- Provides value to readers +- Signals trust and authority +- May earn reciprocal links +- Shows you're not keyword-focused + +**Best practices:** +- **2-3 external links** to authoritative sources +- Link to original research/data +- Link to tools/resources mentioned +- Open in new tab (user preference) +- Use `rel="nofollow"` for untrusted sources + +**Authority sources:** +- Official documentation +- Government sites (.gov) +- Educational institutions (.edu) +- Industry research firms +- Reputable publications + +--- + +### Images & Alt Text + +**SEO value:** +- Image search traffic +- Featured snippets with images +- Improved user engagement +- Accessibility (screen readers) + +**Image optimization:** + +**File size:** +- Compress images (< 200KB ideal) +- Use WebP format when possible +- Lazy loading for below-fold images + +**File names:** +- Descriptive, not "IMG_1234.jpg" +- Include keyword: "jwt-authentication-flow.png" +- Use hyphens, not underscores + +**Alt text:** +- Describe image content +- Include keyword naturally +- 10-15 words typical +- Don't stuff keywords + +**Examples:** + +❌ Bad: +- Alt: "image" or empty +- File: "screenshot-2024.png" + +✅ Good: +- Alt: "JWT authentication flow diagram showing token generation and verification" +- File: "jwt-authentication-flow-diagram.png" + +--- + +## URL Structure + +**SEO-friendly URLs:** + +**Best practices:** +- **Include primary keyword** +- **Short and descriptive** (3-5 words) +- **Use hyphens**, not underscores +- **Lowercase only** +- **Avoid parameters** (?id=123) + +**Examples:** + +❌ Bad: +- `/blog/post?id=12345` +- `/blog/2024/01/15/new-post` +- `/JWT_Authentication_Tutorial_Complete_Guide` + +✅ Good: +- `/jwt-authentication-tutorial` +- `/blog/jwt-authentication-nodejs` +- `/guides/api-authentication` + +--- + +## Content Length & Quality + +### Optimal Length + +**General guidelines:** + +| Content Type | Optimal Length | Rationale | +|--------------|----------------|-----------| +| Blog post | 1,500-2,500 words | Comprehensive coverage | +| Tutorial | 2,000-3,000 words | Detailed instructions | +| Listicle | 1,000-2,000 words | Quick, scannable | +| Landing page | 500-1,000 words | Concise, conversion-focused | +| Product page | 300-500 words | Key info only | + +**But length isn't everything:** +- Match top-ranking content length +- Cover topic comprehensively +- Don't add fluff to hit word count +- Value > length + +### Content Quality Signals + +**E-E-A-T (Experience, Expertise, Authoritativeness, Trustworthiness):** + +**Experience:** +- First-hand knowledge +- Personal insights +- Real-world examples + +**Expertise:** +- Author credentials +- Technical accuracy +- Depth of coverage + +**Authoritativeness:** +- Backlinks from reputable sites +- Author byline +- Citations and references + +**Trustworthiness:** +- Accurate information +- Proper citations +- Clear sources +- Privacy policy, contact info + +--- + +## Technical SEO Checklist + +### Page Speed +- [ ] Page loads in < 3 seconds +- [ ] Images optimized and compressed +- [ ] Lazy loading implemented +- [ ] Minified CSS/JS +- [ ] Browser caching enabled + +### Mobile-Friendly +- [ ] Responsive design +- [ ] Text readable without zooming +- [ ] Touch targets 48x48px+ +- [ ] No horizontal scrolling + +### Core Web Vitals +- [ ] LCP (Largest Contentful Paint) < 2.5s +- [ ] FID (First Input Delay) < 100ms +- [ ] CLS (Cumulative Layout Shift) < 0.1 + +### Indexing +- [ ] Pages not blocked by robots.txt +- [ ] XML sitemap submitted +- [ ] Canonical tags set correctly +- [ ] No duplicate content + +--- + +## Featured Snippets & Rich Results + +### What Are Featured Snippets? + +**"Position 0" results** that appear above organic listings + +**Types:** +- **Paragraph** (definitions, answers) +- **List** (steps, rankings) +- **Table** (comparisons, data) +- **Video** (tutorials) + +### How to Win Snippets + +**1. Target question keywords** +- "What is", "How to", "Why does" +- "Best", "Top", "Checklist" + +**2. Structure for snippets** + +**Paragraph snippets:** +- Answer question in 40-60 words +- Place answer directly after H2 +- Define terms clearly + +**List snippets:** +- Use numbered lists (for steps) +- Use bullet lists (for items) +- 5-8 items optimal + +**Table snippets:** +- Use HTML tables +- Clear headers +- Comparison data + +**Example:** + +```markdown +## What Is JWT Authentication? + +JWT (JSON Web Token) authentication is a stateless authentication method that uses cryptographically signed tokens to verify user identity. Instead of storing session data on the server, JWT embeds user information in a secure token that clients include with each request. + +### How JWT Authentication Works: + +1. User logs in with credentials +2. Server validates and creates JWT +3. Token sent to client +4. Client includes token in requests +5. Server verifies token signature +``` + +--- + +## Schema Markup + +**Structured data** that helps search engines understand content + +**Common types for content:** +- **Article:** Blog posts, news +- **HowTo:** Step-by-step guides +- **FAQPage:** FAQ sections +- **VideoObject:** Embedded videos +- **BreadcrumbList:** Navigation + +**Example (JSON-LD):** +```json +{ + "@context": "https://schema.org", + "@type": "Article", + "headline": "JWT Authentication Tutorial", + "author": { + "@type": "Person", + "name": "John Developer" + }, + "datePublished": "2024-01-15", + "image": "https://example.com/jwt-tutorial.jpg" +} +``` + +**Tools:** +- [Google Rich Results Test](https://search.google.com/test/rich-results) +- [Schema Markup Generator](https://technicalseo.com/tools/schema-markup-generator/) + +--- + +## SEO Content Writing Process + +### 1. Keyword Research (1-2 hours) +- [ ] Identify primary keyword +- [ ] Find secondary keywords +- [ ] Analyze top 10 results +- [ ] Determine search intent +- [ ] Note target word count + +### 2. Content Outline (30 min) +- [ ] Create H2/H3 structure +- [ ] Include keywords in headers +- [ ] Plan internal links +- [ ] Identify research needs + +### 3. Write First Draft (2-4 hours) +- [ ] Write naturally first +- [ ] Focus on value +- [ ] Answer user questions +- [ ] Include examples + +### 4. SEO Optimization (30-60 min) +- [ ] Primary keyword in first 100 words +- [ ] Keywords in headers (natural) +- [ ] Add internal links (3-5) +- [ ] Add external links (2-3) +- [ ] Optimize images and alt text +- [ ] Write meta description +- [ ] Check keyword density + +### 5. Quality Check (30 min) +- [ ] Fact-check all claims +- [ ] Verify links work +- [ ] Read aloud for flow +- [ ] Check readability score +- [ ] Proofread carefully + +--- + +## SEO Tools + +### Free Tools +- **Google Search Console** - Monitor performance +- **Google Analytics** - Track traffic +- **Google Keyword Planner** - Keyword research +- **Ubersuggest** - Limited keyword data +- **AnswerThePublic** - Question keywords +- **Yoast SEO (WordPress)** - On-page optimization + +### Paid Tools +- **Ahrefs** ($99-$999/mo) - All-in-one SEO +- **SEMrush** ($119-$449/mo) - Comprehensive suite +- **Surfer SEO** ($49-$199/mo) - Content optimization +- **Clearscope** ($170+/mo) - Content intelligence +- **MarketMuse** ($149-$600/mo) - Content planning + +### Free Browser Extensions +- **Keywords Everywhere** - Search volume data +- **MozBar** - Domain authority checker +- **SEO Meta in 1 Click** - View meta tags +- **Detailed** - View structured data + +--- + +## Common SEO Mistakes + +### ❌ Avoid These + +**1. Keyword stuffing** +- Overusing keywords unnaturally +- Hurts readability and rankings + +**2. Thin content** +- < 500 words without depth +- Doesn't fully answer question + +**3. Duplicate content** +- Copying content across pages +- Plagiarizing from other sites + +**4. Ignoring mobile** +- Non-responsive design +- 60%+ of traffic is mobile + +**5. Slow page speed** +- Large uncompressed images +- Too many scripts +- Poor hosting + +**6. No internal linking** +- Isolated pages +- Lost link equity + +**7. Bad user experience** +- Intrusive popups +- Auto-playing videos +- Difficult navigation + +**8. Ignoring search intent** +- Wrong content type +- Doesn't answer query + +--- + +## Measuring SEO Success + +### Key Metrics + +**Rankings:** +- Track target keyword positions +- Monitor ranking changes +- Tool: Google Search Console, Ahrefs + +**Organic Traffic:** +- Sessions from organic search +- Growth over time +- Tool: Google Analytics + +**Click-Through Rate (CTR):** +- % of impressions that click +- Improve with better titles/descriptions +- Tool: Google Search Console + +**Engagement:** +- Time on page (3+ minutes good) +- Pages per session +- Bounce rate (< 60% good) + +**Conversions:** +- Goal completions from organic +- Newsletter signups +- Lead forms submitted + +### Timeline for Results + +**Realistic expectations:** +- **Week 1-4:** Indexed, minimal movement +- **Month 2-3:** Start ranking for long-tail +- **Month 4-6:** Ranking for target keywords +- **Month 6-12:** Established authority + +**Factors affecting timeline:** +- Domain authority +- Competition +- Content quality +- Backlinks + +--- + +## SEO Checklist for Writers + +### Before Writing +- [ ] Keyword research complete +- [ ] Search intent identified +- [ ] Top 10 results analyzed +- [ ] Target word count determined + +### During Writing +- [ ] Primary keyword in first 100 words +- [ ] Keywords in H1, H2s naturally +- [ ] Internal links planned (3-5) +- [ ] External links identified (2-3) +- [ ] Images with descriptive file names + +### After Writing +- [ ] Meta description written (150-160 chars) +- [ ] All images have alt text +- [ ] URL slug optimized +- [ ] Schema markup added (if applicable) +- [ ] Links tested +- [ ] Readability check (Flesch score 60+) +- [ ] Mobile preview +- [ ] Page speed check + +--- + +## Quick Reference + +### Optimal Keyword Density +- Primary: 0.5-2.5% of content +- Don't force it, write naturally + +### Word Count Targets +- Blog: 1,500-2,500 words +- Tutorial: 2,000-3,000 words +- Landering page: 500-1,000 words + +### Link Targets +- Internal: 3-5 per post +- External: 2-3 to authority sites + +### Title Length +- 50-60 characters +- Include primary keyword + +### Meta Description +- 150-160 characters +- Include keyword + CTA + +### Image Optimization +- < 200KB file size +- Descriptive file name +- Alt text 10-15 words + +--- + +**Remember:** SEO is important, but user experience comes first. Write for humans, optimize for search engines. diff --git a/skills/content-brief-generator/references/tone_voice_guide.md b/skills/content-brief-generator/references/tone_voice_guide.md new file mode 100644 index 0000000..e4b4eb7 --- /dev/null +++ b/skills/content-brief-generator/references/tone_voice_guide.md @@ -0,0 +1,690 @@ +# Tone & Voice Guide + +Complete guide to developing and maintaining consistent voice and tone in your content. + +--- + +## Voice vs. Tone + +### Voice +**Your brand's personality** - consistent across all content + +**Think of it as:** +- Who you are as a brand +- Your character +- Never changes + +**Examples:** +- Mailchimp: "Friendly, helpful, human" +- Stripe: "Direct, technical, trustworthy" +- Nike: "Inspirational, motivational, bold" + +### Tone +**How voice adapts** to context - changes based on situation + +**Think of it as:** +- Your emotional state +- How you say something +- Varies by context + +**Examples:** +- **Error message:** Apologetic, helpful +- **Success message:** Congratulatory, encouraging +- **Technical docs:** Professional, precise +- **Marketing:** Enthusiastic, persuasive + +**Analogy:** +Voice = Your personality +Tone = Your mood + +--- + +## Defining Your Voice + +### Voice Attributes Framework + +Choose 3-4 core attributes that define your brand voice: + +**The Spectrum:** + +``` +Formal ←────────────→ Casual +Serious ←────────────→ Funny +Respectful ←────────────→ Irreverent +Enthusiastic ←────────────→ Matter-of-fact +Traditional ←────────────→ Innovative +``` + +### Example Voice Definitions + +**Mailchimp:** +- Friendly but not silly +- Clever but not overly witty +- Helpful but not overbearing +- Expert but not bossy + +**Slack:** +- Professional but approachable +- Technical but not intimidating +- Playful but not childish +- Direct but not cold + +**Atlassian:** +- Straightforward and honest +- Enthusiastically professional +- Conversational yet informative +- Smart but not condescending + +--- + +## Voice Dimensions + +### 1. Formality + +**Formal:** +- Professional language +- Complete sentences +- No contractions +- Third person + +**Example:** +"The application has been successfully deployed to the production environment." + +**Casual:** +- Conversational language +- Contractions okay +- First/second person +- Shorter sentences + +**Example:** +"You're all set! Your app is live." + +**When to use:** +- Formal: Legal, compliance, enterprise docs +- Casual: Blogs, social media, onboarding + +--- + +### 2. Enthusiasm + +**Highly Enthusiastic:** +- Exclamation points +- Superlatives (amazing, incredible) +- Energy and excitement +- Emojis (in appropriate contexts) + +**Example:** +"This is amazing! You just saved 10 hours of work. Let's celebrate! 🎉" + +**Neutral/Matter-of-fact:** +- Period instead of exclamation +- Factual statements +- No hyperbole +- Professional tone + +**Example:** +"The task has been completed successfully. You saved 10 hours." + +**When to use:** +- Enthusiastic: Consumer products, celebrations, achievements +- Neutral: Technical docs, business content, data reports + +--- + +### 3. Technical Level + +**Highly Technical:** +- Industry jargon +- Assumes expert knowledge +- Technical accuracy paramount +- Detailed specifications + +**Example:** +"The WebSocket connection establishes a persistent, full-duplex communication channel over a single TCP connection." + +**Accessible:** +- Plain language +- Explain jargon +- Analogies and examples +- Beginner-friendly + +**Example:** +"WebSockets let your app and server talk back and forth in real-time, like a phone call instead of sending letters." + +**When to use:** +- Technical: API docs, developer tools, architecture guides +- Accessible: Getting started guides, general audience, marketing + +--- + +### 4. Humor + +**Funny/Playful:** +- Jokes and puns +- Pop culture references +- Light-hearted +- Personality shines + +**Example:** +"Oops! Looks like something went wrong. Our bad. We're on it faster than you can say 'Have you tried turning it off and on again?'" + +**Serious:** +- Professional +- No jokes +- Straightforward +- Business-like + +**Example:** +"An error has occurred. Our team has been notified and is working to resolve the issue." + +**When to use:** +- Playful: Consumer brands, creative industries, social media +- Serious: Financial services, healthcare, legal, critical errors + +--- + +## Writing in Your Voice + +### Voice Checklist + +For every piece of content, ask: + +- [ ] **Does this sound like us?** (matches voice attributes) +- [ ] **Is it consistent** with previous content? +- [ ] **Would our audience recognize us** without our logo? +- [ ] **Does it feel authentic** or forced? + +### Voice Examples by Sentence + +**Same content, different voices:** + +**Topic: User made an error** + +**Mailchimp (friendly, helpful):** +"Oops! It looks like that email address isn't quite right. Try checking for typos?" + +**Stripe (direct, technical):** +"Invalid email format. Use format: user@example.com" + +**Innocent (playful, quirky):** +"That email address looks a bit wonky. Give it another go?" + +**IBM (formal, professional):** +"The email address entered is invalid. Please verify and try again." + +--- + +## Adapting Tone + +### Tone Guidelines by Context + +| Context | Tone | Example | +|---------|------|---------| +| **Error message** | Apologetic, helpful | "Sorry about that! Here's how to fix it..." | +| **Success** | Encouraging | "Nice work! You're all set." | +| **Warning** | Urgent but calm | "Action required: Your payment failed." | +| **Education** | Patient, clear | "Let's walk through this together." | +| **Marketing** | Persuasive, exciting | "Transform your workflow in minutes!" | +| **Legal** | Formal, precise | "By continuing, you agree to the terms." | +| **Support** | Empathetic, solution-focused | "I understand this is frustrating. Let's solve it." | + +--- + +## Person & Perspective + +### First Person (We, Our) + +**When to use:** +- Brand speaking +- Company announcements +- Team perspective + +**Example:** +"We're excited to announce our new feature. We built this based on your feedback." + +**Pros:** +- Personal connection +- Shows team behind brand +- Takes ownership + +**Cons:** +- Can feel self-focused +- Less about user + +--- + +### Second Person (You, Your) + +**When to use:** +- Most common +- User instructions +- Direct communication +- Marketing copy + +**Example:** +"You can now collaborate in real-time. Your team will love it." + +**Pros:** +- User-focused +- Clear and direct +- Creates connection + +**Cons:** +- Can feel pushy if overused + +--- + +### Third Person (They, User, Customer) + +**When to use:** +- Documentation +- Objective content +- Case studies about others + +**Example:** +"The user navigates to settings. The system validates their credentials." + +**Pros:** +- Professional +- Objective +- Clear for documentation + +**Cons:** +- Less personal +- Can feel distant + +--- + +## Active vs. Passive Voice + +### Active Voice (Preferred) + +**Structure:** Subject performs action + +**Examples:** +- "You can deploy your app in minutes." +- "The system processes your request." +- "Click the button to continue." + +**Why use:** +- Clearer +- More direct +- Easier to read +- Stronger + +--- + +### Passive Voice (Avoid Usually) + +**Structure:** Action performed on subject + +**Examples:** +- "Your app can be deployed in minutes." +- "Your request is processed by the system." +- "The button should be clicked to continue." + +**When to use:** +- Actor unknown: "The server was restarted." +- Actor irrelevant: "The file was deleted." +- Soften message: "An error was encountered." + +--- + +## Sentence Structure + +### Short Sentences +- Easy to read +- Scannable +- Mobile-friendly +- Clear + +**Example:** +"Deploy your app fast. No config needed. It just works." + +**When to use:** +- Headlines +- Key points +- Mobile content +- Emphasis + +--- + +### Varied Length +- More natural +- Maintains interest +- Provides rhythm + +**Example:** +"Deploy your app fast. No configuration needed, no complicated setup process, no hours wasted on devops. It just works." + +**When to use:** +- Blog posts +- Long-form content +- Storytelling + +--- + +## Word Choice + +### Simple vs. Complex + +**Prefer simple:** +- Use vs. utilize +- Help vs. assist +- Buy vs. purchase +- Start vs. commence +- Show vs. demonstrate + +**Exception:** Technical accuracy requires specific terms + +--- + +### Positive vs. Negative + +**Positive framing (preferred):** +- "Remember your password" +- "Include your address" +- "Make sure to save" + +**Negative framing (avoid):** +- "Don't forget your password" +- "Don't leave out your address" +- "Don't lose your work" + +--- + +### Concrete vs. Abstract + +**Concrete (preferred):** +- "Save 10 hours per week" +- "Deploy in 5 minutes" +- "99.9% uptime" + +**Abstract (avoid):** +- "Save time" +- "Fast deployment" +- "Reliable service" + +--- + +## Common Writing Guidelines + +### Contractions + +**Use them for conversational tone:** +- Don't vs. Do not +- You're vs. You are +- We've vs. We have + +**Skip them for:** +- Legal content +- Very formal contexts +- When emphasis needed: "Do not delete this" + +--- + +### Exclamation Points + +**Use sparingly:** +- Celebrations and achievements +- Very exciting news +- Strong emphasis + +**Limit to:** +- Once per paragraph max +- Never multiple (!!!) +- Not in B2B formal content + +--- + +### Emojis + +**When appropriate:** +- Consumer brands +- Casual social media +- Internal communications +- In-app celebrations + +**Avoid in:** +- Enterprise B2B +- Documentation +- Legal/compliance +- Serious topics + +--- + +## Brand Voice Examples + +### Technology/Developer Tools + +**Stripe:** +- **Voice:** Direct, technical, trustworthy +- **Example:** "Accept payments in minutes. Get started with a few lines of code." +- **Why it works:** Developers want clarity and speed + +**Vercel:** +- **Voice:** Modern, enthusiastic, technical +- **Example:** "Deploy your Next.js app. It's crazy fast." +- **Why it works:** Balances technical and excitement + +**Twilio:** +- **Voice:** Friendly, technical, empowering +- **Example:** "Build the future of communications. We make it simple." +- **Why it works:** Technical but approachable + +--- + +### Consumer Products + +**Mailchimp:** +- **Voice:** Friendly, helpful, sometimes quirky +- **Example:** "That email looks a bit wonky. Want to check it?" +- **Why it works:** Makes tedious tasks feel human + +**Slack:** +- **Voice:** Professional-casual, helpful, clear +- **Example:** "Work, simplified. Your team will thank you." +- **Why it works:** Professional without being stuffy + +**Headspace:** +- **Voice:** Calm, supportive, encouraging +- **Example:** "Take a moment for yourself. You deserve it." +- **Why it works:** Matches meditation/wellness mission + +--- + +### Enterprise/B2B + +**Salesforce:** +- **Voice:** Professional, empowering, visionary +- **Example:** "Transform your business. Connect with customers in a whole new way." +- **Why it works:** Aspirational but credible + +**Atlassian:** +- **Voice:** Straightforward, enthusiastic, smart +- **Example:** "Teamwork doesn't have to be hard. Let's make it easier." +- **Why it works:** Acknowledges real problems, offers solutions + +--- + +## Developing Your Voice + +### Step 1: Define Core Attributes + +Choose 3-4 from these dimensions: + +**Formality:** +- Formal, professional, casual, conversational + +**Humor:** +- Serious, playful, witty, irreverent + +**Enthusiasm:** +- Energetic, neutral, understated + +**Technical:** +- Expert, accessible, simple + +**Empathy:** +- Warm, neutral, distant + +--- + +### Step 2: Create Voice Chart + +| Attribute | We are | We are not | Example | +|-----------|---------|------------|---------| +| Professional | Clear and helpful | Stuffy or robotic | "Here's how to..." not "One must..." | +| Friendly | Warm and welcoming | Overly casual | "Welcome!" not "Sup!" | +| Technical | Accurate and precise | Jargon-heavy | Explain terms first time | + +--- + +### Step 3: Write Examples + +For each voice attribute, write before/after examples: + +**Before (generic):** +"Our platform provides solutions for your business needs." + +**After (our voice - direct, technical, helpful):** +"Deploy your apps faster with built-in CI/CD and automatic scaling." + +--- + +### Step 4: Create Voice Guidelines + +Document: +- [ ] Core voice attributes (3-4) +- [ ] Do's and don'ts +- [ ] Example sentences +- [ ] Tone by context +- [ ] Word choice preferences +- [ ] Grammar rules (contractions, etc.) + +--- + +## Testing Your Voice + +### Voice Consistency Check + +1. **Remove branding** from 5 pieces of content +2. **Mix with competitors'** content +3. **Can people identify yours?** + +If yes → Voice is distinctive +If no → Need stronger voice + +--- + +### Reader Feedback + +Ask your audience: +- How would you describe our voice? +- Does it match your expectations? +- What do you like/dislike? + +--- + +## Maintaining Voice + +### Team Alignment + +**Onboarding:** +- Share voice guidelines +- Review examples +- Practice exercises + +**Review Process:** +- Check content against voice guidelines +- Provide specific feedback +- Create a voice champion + +**Documentation:** +- Voice guidelines in shared doc +- Examples library +- Regular updates + +--- + +### Voice Evolution + +**When to evolve:** +- Rebranding +- New audience +- Company maturity +- Market shift + +**How to evolve:** +- Document changes +- Transition gradually +- Update guidelines +- Train team + +**What to keep:** +- Core personality +- Brand values +- Recognition + +--- + +## Voice Guidelines Template + +```markdown +# [Brand] Voice & Tone Guide + +## Our Voice + +[Brand] sounds [attribute], [attribute], and [attribute]. + +### Core Attributes + +**1. [Attribute Name]** +- What it means: [Description] +- We are: [Example] +- We're not: [Counter-example] + +**2. [Attribute Name]** +[Repeat] + +**3. [Attribute Name]** +[Repeat] + +## Grammar & Mechanics + +- Contractions: [Yes/No] +- Exclamation points: [Use sparingly/Never/Frequently] +- Emojis: [Appropriate contexts] +- Person: [First/Second/Third] +- Active voice: [Always/Usually/Varies] + +## Tone by Context + +| Context | Tone | Example | +|---------|------|---------| +| Error | Apologetic | "Sorry about that..." | +| Success | Encouraging | "Nice work!" | +| Documentation | Clear | "Follow these steps:" | + +## Word Choices + +**Preferred:** +- [Word 1] over [Word 2] +- [Word 3] over [Word 4] + +**Avoid:** +- [Words/phrases to avoid] + +## Examples + +### Good Examples +[3-5 examples that nail the voice] + +### Before/After +**Before:** [Generic version] +**After:** [Our voice version] +``` + +--- + +**Remember:** Your voice should feel authentic, not forced. If it doesn't feel like "you," it won't resonate with your audience. diff --git a/skills/content-brief-generator/scripts/generate_brief.sh b/skills/content-brief-generator/scripts/generate_brief.sh new file mode 100755 index 0000000..235a9d5 --- /dev/null +++ b/skills/content-brief-generator/scripts/generate_brief.sh @@ -0,0 +1,568 @@ +#!/bin/bash + +# Content Brief Generation Script +# Interactive workflow for creating comprehensive content briefs + +set -e + +# Colors +GREEN='\033[0;32m' +BLUE='\033[0;34m' +YELLOW='\033[1;33m' +RED='\033[0;31m' +MAGENTA='\033[0;35m' +CYAN='\033[0;36m' +NC='\033[0m' + +# Header +echo -e "${BLUE}╔══════════════════════════════════════════════════╗${NC}" +echo -e "${BLUE}║ Content Brief Generator ║${NC}" +echo -e "${BLUE}╚══════════════════════════════════════════════════╝${NC}" +echo "" + +# Helper function for prompts +prompt_input() { + local prompt_text="$1" + local var_name="$2" + local required="$3" + + while true; do + echo -e "${CYAN}${prompt_text}${NC}" + read -r input + + if [ -n "$input" ]; then + eval "$var_name=\"$input\"" + break + elif [ "$required" != "true" ]; then + eval "$var_name=\"\"" + break + else + echo -e "${RED}This field is required.${NC}" + fi + done +} + +prompt_multiline() { + local prompt_text="$1" + local var_name="$2" + + echo -e "${CYAN}${prompt_text}${NC}" + echo -e "${YELLOW}(Type your response, press Enter twice when done)${NC}" + + local input="" + local line + local empty_count=0 + + while true; do + read -r line + if [ -z "$line" ]; then + ((empty_count++)) + if [ $empty_count -ge 2 ]; then + break + fi + input="${input}\n" + else + empty_count=0 + if [ -n "$input" ]; then + input="${input}\n${line}" + else + input="${line}" + fi + fi + done + + eval "$var_name=\"$input\"" +} + +# Step 1: Content Type and Basics +echo -e "${MAGENTA}━━━ Step 1: Content Basics ━━━${NC}" +echo "" + +echo "Select content type:" +echo "1) Blog Post / Article" +echo "2) Technical Documentation" +echo "3) Landing Page" +echo "4) Case Study" +echo "5) Social Media" +echo "6) Email Campaign" +echo "7) Video Script" +echo "8) Whitepaper / Report" +echo "9) Product Description" +echo "" + +prompt_input "Enter number (1-9):" CONTENT_TYPE_NUM true + +case $CONTENT_TYPE_NUM in + 1) CONTENT_TYPE="Blog Post / Article" ;; + 2) CONTENT_TYPE="Technical Documentation" ;; + 3) CONTENT_TYPE="Landing Page" ;; + 4) CONTENT_TYPE="Case Study" ;; + 5) CONTENT_TYPE="Social Media" ;; + 6) CONTENT_TYPE="Email Campaign" ;; + 7) CONTENT_TYPE="Video Script" ;; + 8) CONTENT_TYPE="Whitepaper / Report" ;; + 9) CONTENT_TYPE="Product Description" ;; + *) CONTENT_TYPE="Blog Post / Article" ;; +esac + +echo "" +prompt_input "Working title or topic:" TITLE true +prompt_input "Target word count (or duration for video):" WORD_COUNT false +prompt_input "Target publication date (YYYY-MM-DD):" PUB_DATE false + +# Step 2: Audience and Goals +echo "" +echo -e "${MAGENTA}━━━ Step 2: Audience & Goals ━━━${NC}" +echo "" + +prompt_input "Primary target audience (e.g., 'Junior developers', 'Marketing managers'):" AUDIENCE true +prompt_input "Reader's knowledge level (Beginner/Intermediate/Advanced):" KNOWLEDGE_LEVEL false +prompt_multiline "What problem or question does this content solve for them?" PROBLEM + +echo "" +echo "Primary content goal:" +echo "1) Educate / Inform" +echo "2) Convert / Generate leads" +echo "3) Entertain / Engage" +echo "4) Support / Help" +echo "5) Build authority / Thought leadership" +echo "" + +prompt_input "Enter number (1-5):" GOAL_NUM true + +case $GOAL_NUM in + 1) PRIMARY_GOAL="Educate / Inform" ;; + 2) PRIMARY_GOAL="Convert / Generate leads" ;; + 3) PRIMARY_GOAL="Entertain / Engage" ;; + 4) PRIMARY_GOAL="Support / Help" ;; + 5) PRIMARY_GOAL="Build authority / Thought leadership" ;; + *) PRIMARY_GOAL="Educate / Inform" ;; +esac + +prompt_input "Key takeaway (what should readers remember):" KEY_TAKEAWAY true + +# Step 3: SEO & Keywords +echo "" +echo -e "${MAGENTA}━━━ Step 3: SEO Strategy ━━━${NC}" +echo "" + +prompt_input "Primary keyword:" PRIMARY_KEYWORD true +prompt_input "Secondary keywords (comma-separated):" SECONDARY_KEYWORDS false +prompt_input "Search intent (Informational/Commercial/Transactional/Navigational):" SEARCH_INTENT false +prompt_input "Target search volume (if known):" SEARCH_VOLUME false + +# Step 4: Structure and Content +echo "" +echo -e "${MAGENTA}━━━ Step 4: Content Structure ━━━${NC}" +echo "" + +echo "Content structure framework:" +echo "1) AIDA (Attention, Interest, Desire, Action)" +echo "2) PAS (Problem, Agitate, Solve)" +echo "3) Inverted Pyramid (Most important first)" +echo "4) Storytelling Arc (Setup, Conflict, Resolution)" +echo "5) How-to / Tutorial" +echo "6) Listicle" +echo "7) Custom" +echo "" + +prompt_input "Enter number (1-7):" FRAMEWORK_NUM false + +case $FRAMEWORK_NUM in + 1) FRAMEWORK="AIDA (Attention, Interest, Desire, Action)" ;; + 2) FRAMEWORK="PAS (Problem, Agitate, Solve)" ;; + 3) FRAMEWORK="Inverted Pyramid" ;; + 4) FRAMEWORK="Storytelling Arc" ;; + 5) FRAMEWORK="How-to / Tutorial" ;; + 6) FRAMEWORK="Listicle" ;; + 7) FRAMEWORK="Custom" ;; + *) FRAMEWORK="Custom" ;; +esac + +prompt_multiline "Key sections or outline (one per line):" KEY_SECTIONS + +prompt_input "Number of examples/case studies to include:" NUM_EXAMPLES false +prompt_input "Data/statistics required (Yes/No):" NEEDS_DATA false +prompt_input "Code examples needed (Yes/No - for technical content):" NEEDS_CODE false + +# Step 5: Tone, Voice, and Style +echo "" +echo -e "${MAGENTA}━━━ Step 5: Tone & Voice ━━━${NC}" +echo "" + +echo "Tone:" +echo "1) Professional and formal" +echo "2) Professional but conversational" +echo "3) Casual and friendly" +echo "4) Technical and authoritative" +echo "5) Playful and creative" +echo "" + +prompt_input "Enter number (1-5):" TONE_NUM false + +case $TONE_NUM in + 1) TONE="Professional and formal" ;; + 2) TONE="Professional but conversational" ;; + 3) TONE="Casual and friendly" ;; + 4) TONE="Technical and authoritative" ;; + 5) TONE="Playful and creative" ;; + *) TONE="Professional but conversational" ;; +esac + +prompt_input "Point of view (1st person 'we', 2nd person 'you', 3rd person):" POV false +prompt_input "Specific style notes or voice attributes:" STYLE_NOTES false + +# Step 6: Media and Visuals +echo "" +echo -e "${MAGENTA}━━━ Step 6: Visuals & Media ━━━${NC}" +echo "" + +prompt_input "Number of images needed:" NUM_IMAGES false +prompt_input "Hero image requirements:" HERO_IMAGE false +prompt_input "Screenshots or diagrams needed (describe):" SCREENSHOTS false +prompt_input "Video or embedded media (describe):" VIDEO_NEEDS false + +# Step 7: CTAs and Conversion +echo "" +echo -e "${MAGENTA}━━━ Step 7: CTAs & Conversion ━━━${NC}" +echo "" + +prompt_input "Primary call-to-action:" PRIMARY_CTA false +prompt_input "Secondary CTA (if any):" SECONDARY_CTA false +prompt_input "Conversion goal (e.g., 'Sign up', 'Download', 'Contact sales'):" CONVERSION_GOAL false + +# Step 8: Research and References +echo "" +echo -e "${MAGENTA}━━━ Step 8: Research Requirements ━━━${NC}" +echo "" + +prompt_input "Competitor content to reference (URLs, comma-separated):" COMPETITOR_URLS false +prompt_input "SME interviews required (Yes/No):" NEEDS_SME false +prompt_input "Primary sources or research needed:" RESEARCH_SOURCES false + +# Step 9: Success Metrics +echo "" +echo -e "${MAGENTA}━━━ Step 9: Success Metrics ━━━${NC}" +echo "" + +prompt_input "Primary success metric (e.g., 'Organic traffic', 'Conversions'):" PRIMARY_METRIC true +prompt_input "Secondary metrics (comma-separated):" SECONDARY_METRICS false +prompt_input "Target goal for primary metric:" METRIC_TARGET false + +# Step 10: Additional Details +echo "" +echo -e "${MAGENTA}━━━ Step 10: Additional Details ━━━${NC}" +echo "" + +prompt_input "Internal links to include (comma-separated URLs/pages):" INTERNAL_LINKS false +prompt_input "External links to include:" EXTERNAL_LINKS false +prompt_input "Legal or compliance requirements:" COMPLIANCE false +prompt_multiline "Any other special requirements or notes:" SPECIAL_NOTES + +# Generate filename +FILENAME="${TITLE// /_}" +FILENAME="${FILENAME//[^a-zA-Z0-9_-]/}" +FILENAME="$(echo "$FILENAME" | tr '[:upper:]' '[:lower:]')" +FILENAME="content_brief_${FILENAME}.md" + +# Output directory +OUTPUT_DIR="." +if [ ! -z "$1" ]; then + OUTPUT_DIR="$1" +fi + +OUTPUT_FILE="$OUTPUT_DIR/$FILENAME" + +# Generate the brief +echo "" +echo -e "${BLUE}Generating content brief...${NC}" +echo "" + +cat > "$OUTPUT_FILE" << EOF +# Content Brief: ${TITLE} + +**Content Type:** ${CONTENT_TYPE} +**Target Word Count:** ${WORD_COUNT:-TBD} +**Target Publication Date:** ${PUB_DATE:-TBD} +**Status:** Draft +**Created:** $(date +%Y-%m-%d) + +--- + +## Overview + +### Key Information +- **Primary Goal:** ${PRIMARY_GOAL} +- **Target Audience:** ${AUDIENCE} +- **Knowledge Level:** ${KNOWLEDGE_LEVEL:-General} +- **Key Takeaway:** ${KEY_TAKEAWAY} + +### Problem Statement +${PROBLEM} + +--- + +## Audience + +### Primary Audience +${AUDIENCE} + +**Knowledge Level:** ${KNOWLEDGE_LEVEL:-General} + +**Pain Points:** +${PROBLEM} + +**What They Need:** +${KEY_TAKEAWAY} + +--- + +## SEO Strategy + +### Keywords +- **Primary Keyword:** ${PRIMARY_KEYWORD} +- **Secondary Keywords:** ${SECONDARY_KEYWORDS:-TBD} +- **Search Intent:** ${SEARCH_INTENT:-Informational} +- **Target Search Volume:** ${SEARCH_VOLUME:-TBD} + +### SEO Requirements +- [ ] Include primary keyword in title +- [ ] Use primary keyword in first 100 words +- [ ] Include keywords in headings (H2, H3) +- [ ] Write compelling meta description (150-160 chars) +- [ ] Add alt text to all images +- [ ] Internal linking strategy +- [ ] External authoritative links + +### Meta Description (Draft) +[Write a compelling 150-160 character description including primary keyword] + +--- + +## Content Structure + +### Framework +${FRAMEWORK} + +### Outline / Key Sections +${KEY_SECTIONS} + +### Content Requirements +- **Examples needed:** ${NUM_EXAMPLES:-TBD} +- **Data/statistics:** ${NEEDS_DATA:-No} +- **Code examples:** ${NEEDS_CODE:-No} + +--- + +## Tone & Voice + +### Writing Style +- **Tone:** ${TONE} +- **Point of View:** ${POV:-Second person (you/your)} +- **Style Notes:** ${STYLE_NOTES:-Follow brand voice guidelines} + +### Writing Guidelines +- Use active voice +- Short paragraphs (2-4 sentences) +- Bullet points for scanability +- Subheadings every 300-400 words +- Clear, concise language +- Avoid jargon (or explain when necessary) + +--- + +## Visual & Media Requirements + +### Images +- **Number of images:** ${NUM_IMAGES:-3-5} +- **Hero image:** ${HERO_IMAGE:-Featured image at top} +- **In-content images:** ${SCREENSHOTS:-Relevant screenshots or diagrams} + +### Other Media +${VIDEO_NEEDS} + +### Image Specifications +- Format: PNG or JPG +- Max file size: 500KB (optimize) +- Alt text for all images +- Relevant to content +- High quality (no stock photos if possible) + +--- + +## Research & Sources + +### Competitor Analysis +${COMPETITOR_URLS:-Research top-ranking content for target keyword} + +### Research Requirements +- **SME Interviews:** ${NEEDS_SME:-No} +- **Primary Sources:** ${RESEARCH_SOURCES:-TBD} +- **Citation Standards:** Link to original sources, use recent data (< 2 years) + +### Required Research +- [ ] Analyze top 5 ranking articles for primary keyword +- [ ] Gather relevant statistics and data +- [ ] Collect examples and case studies +- [ ] Interview SMEs (if required) +- [ ] Compile list of authoritative sources + +--- + +## Calls-to-Action + +### Primary CTA +${PRIMARY_CTA:-TBD} + +### Secondary CTA +${SECONDARY_CTA:-None} + +### Conversion Goal +${CONVERSION_GOAL:-TBD} + +### CTA Placement +- [ ] In introduction (soft CTA) +- [ ] Mid-content (contextual) +- [ ] End of article (primary CTA) +- [ ] Sidebar or floating (if applicable) + +--- + +## Links & References + +### Internal Links +${INTERNAL_LINKS:-Link to relevant internal content (3-5 links)} + +### External Links +${EXTERNAL_LINKS:-Link to authoritative external sources (2-3 links)} + +### Linking Strategy +- Link to relevant internal content (3-5 links) +- Link to authoritative external sources +- Use descriptive anchor text +- Open external links in new tabs + +--- + +## Success Metrics + +### Primary Metric +**${PRIMARY_METRIC}** - Target: ${METRIC_TARGET:-TBD} + +### Secondary Metrics +${SECONDARY_METRICS:-Time on page, scroll depth, social shares} + +### How We'll Measure Success +- Track metrics in Google Analytics / analytics tool +- Review performance after 30 days +- A/B test headlines/CTAs if needed +- Compare to existing similar content + +### Benchmarks +- [Add relevant benchmarks from similar content] + +--- + +## Legal & Compliance + +${COMPLIANCE:-No special requirements} + +### Checklist +- [ ] Copyright for all images +- [ ] Proper attribution for quotes +- [ ] Fact-checking completed +- [ ] Legal disclaimers (if needed) +- [ ] Privacy policy linked (if collecting data) + +--- + +## Special Requirements / Notes + +${SPECIAL_NOTES:-None} + +--- + +## Workflow & Timeline + +### Process +1. **Brief Review** - Writer reviews brief with stakeholders +2. **Research** - Gather sources, data, examples (est: ___ hours) +3. **Outline** - Create detailed outline for review (est: ___ hours) +4. **First Draft** - Write content following brief (est: ___ hours) +5. **Self-Edit** - Writer reviews and edits (est: ___ hours) +6. **Peer Review** - Editor reviews against brief (est: ___ hours) +7. **Revisions** - Incorporate feedback (est: ___ hours) +8. **SEO Review** - Optimize for search (est: ___ hours) +9. **Final Approval** - Stakeholder sign-off +10. **Publish** - Schedule and publish +11. **Promote** - Distribution across channels +12. **Track** - Monitor success metrics + +### Key Dates +- **Brief Finalized:** $(date +%Y-%m-%d) +- **First Draft Due:** ${PUB_DATE:-TBD} +- **Final Approval:** ${PUB_DATE:-TBD} +- **Publication Date:** ${PUB_DATE:-TBD} + +--- + +## Stakeholders + +### Content Team +- **Writer:** [Name] +- **Editor:** [Name] +- **SEO Specialist:** [Name] + +### Reviewers +- **Subject Matter Expert:** [Name] +- **Brand Review:** [Name] +- **Final Approver:** [Name] + +--- + +## References & Resources + +### Templates & Guidelines +- [Brand voice guide] +- [Style guide] +- [SEO guidelines] +- [Content templates] + +### Research Links +- [Link to research document] +- [Link to keyword research] +- [Link to competitor analysis] + +--- + +## Approval + +- [ ] Writer reviewed brief +- [ ] Stakeholders aligned +- [ ] Ready to begin writing + +**Approved by:** ___________ +**Date:** ___________ + +--- + +## Version History + +| Version | Date | Author | Changes | +|---------|------|--------|---------| +| 1.0 | $(date +%Y-%m-%d) | [Auto-generated] | Initial brief | + +EOF + +echo -e "${GREEN}✅ Content brief generated successfully!${NC}" +echo "" +echo -e "File location: ${BLUE}$OUTPUT_FILE${NC}" +echo "" +echo -e "${YELLOW}Next steps:${NC}" +echo "1. Review the brief with stakeholders" +echo "2. Conduct research and gather sources" +echo "3. Create detailed outline" +echo "4. Begin writing first draft" +echo "" +echo -e "${CYAN}Tip: Use validate_brief.sh to check completeness${NC}" +echo "" diff --git a/skills/content-brief-generator/scripts/validate_brief.sh b/skills/content-brief-generator/scripts/validate_brief.sh new file mode 100755 index 0000000..2b84d04 --- /dev/null +++ b/skills/content-brief-generator/scripts/validate_brief.sh @@ -0,0 +1,372 @@ +#!/bin/bash + +# Content Brief Validation Script +# Checks content brief completeness and quality + +set -e + +# Colors +GREEN='\033[0;32m' +BLUE='\033[0;34m' +YELLOW='\033[1;33m' +RED='\033[0;31m' +NC='\033[0m' + +# Check if file provided +if [ $# -lt 1 ]; then + echo "Usage: $0 " + exit 1 +fi + +BRIEF_FILE="$1" + +# Check if file exists +if [ ! -f "$BRIEF_FILE" ]; then + echo -e "${RED}✗ Error: File not found: $BRIEF_FILE${NC}" + exit 1 +fi + +echo -e "${BLUE}╔════════════════════════════════════════════════╗${NC}" +echo -e "${BLUE}║ Content Brief Validation Report ║${NC}" +echo -e "${BLUE}╚════════════════════════════════════════════════╝${NC}" +echo "" +echo -e "File: ${BLUE}$BRIEF_FILE${NC}" +echo "" + +# Counters +ISSUES_FOUND=0 +WARNINGS=0 +CHECKS_PASSED=0 + +# Function to check section exists +check_section() { + local section_name="$1" + local section_pattern="$2" + local required="$3" + + if grep -q "$section_pattern" "$BRIEF_FILE"; then + echo -e "${GREEN}✓${NC} $section_name section found" + ((CHECKS_PASSED++)) + return 0 + else + if [ "$required" = "true" ]; then + echo -e "${RED}✗${NC} $section_name section missing (REQUIRED)" + ((ISSUES_FOUND++)) + else + echo -e "${YELLOW}⚠${NC} $section_name section missing (recommended)" + ((WARNINGS++)) + fi + return 1 + fi +} + +echo -e "${BLUE}━━━ Required Sections ━━━${NC}" +echo "" + +# Check required sections +check_section "Overview" "##.*Overview" true +check_section "Audience" "##.*Audience" true +check_section "SEO Strategy" "##.*SEO.*Strategy\|##.*SEO\|##.*Keywords" true +check_section "Content Structure" "##.*Content Structure\|##.*Structure\|##.*Outline" true +check_section "Success Metrics" "##.*Success Metrics\|##.*Metrics" true + +echo "" +echo -e "${BLUE}━━━ Recommended Sections ━━━${NC}" +echo "" + +# Check recommended sections +check_section "Tone & Voice" "##.*Tone.*Voice\|##.*Voice\|##.*Writing Style" false +check_section "Visual & Media" "##.*Visual\|##.*Media\|##.*Images" false +check_section "Research & Sources" "##.*Research\|##.*Sources" false +check_section "CTAs" "##.*CTA\|##.*Call.*Action" false +check_section "Timeline" "##.*Timeline\|##.*Workflow" false + +echo "" +echo -e "${BLUE}━━━ Content Quality Checks ━━━${NC}" +echo "" + +# Check for placeholder text +if grep -q "\[.*\]\|TBD" "$BRIEF_FILE"; then + PLACEHOLDER_COUNT=$(grep -c "\[.*\]\|TBD" "$BRIEF_FILE") + echo -e "${YELLOW}⚠${NC} Contains $PLACEHOLDER_COUNT placeholder(s) - fill in all details" + ((WARNINGS++)) +else + echo -e "${GREEN}✓${NC} No placeholders remaining" + ((CHECKS_PASSED++)) +fi + +# Check for primary keyword +if grep -qi "Primary Keyword" "$BRIEF_FILE"; then + if grep -A 1 "Primary Keyword" "$BRIEF_FILE" | grep -qv "TBD\|^\s*$"; then + echo -e "${GREEN}✓${NC} Primary keyword specified" + ((CHECKS_PASSED++)) + else + echo -e "${RED}✗${NC} Primary keyword not specified" + ((ISSUES_FOUND++)) + fi +else + echo -e "${RED}✗${NC} Primary keyword section missing" + ((ISSUES_FOUND++)) +fi + +# Check for target audience +if grep -qi "Target Audience\|Primary Audience" "$BRIEF_FILE"; then + if grep -A 2 "Target Audience\|Primary Audience" "$BRIEF_FILE" | grep -qv "TBD\|^\s*$"; then + echo -e "${GREEN}✓${NC} Target audience defined" + ((CHECKS_PASSED++)) + else + echo -e "${RED}✗${NC} Target audience not defined" + ((ISSUES_FOUND++)) + fi +else + echo -e "${RED}✗${NC} Target audience section missing" + ((ISSUES_FOUND++)) +fi + +# Check for word count +if grep -qi "Word Count" "$BRIEF_FILE"; then + if grep "Word Count" "$BRIEF_FILE" | grep -qv "TBD"; then + echo -e "${GREEN}✓${NC} Word count specified" + ((CHECKS_PASSED++)) + else + echo -e "${YELLOW}⚠${NC} Word count not specified" + ((WARNINGS++)) + fi +else + echo -e "${YELLOW}⚠${NC} Word count not mentioned" + ((WARNINGS++)) +fi + +# Check for content structure/outline +if grep -qi "Outline\|Key Sections\|Structure" "$BRIEF_FILE"; then + echo -e "${GREEN}✓${NC} Content structure provided" + ((CHECKS_PASSED++)) +else + echo -e "${RED}✗${NC} Content structure/outline missing" + ((ISSUES_FOUND++)) +fi + +echo "" +echo -e "${BLUE}━━━ SEO Checks ━━━${NC}" +echo "" + +# Check for keyword strategy +KEYWORD_SCORE=0 + +if grep -qi "Primary Keyword" "$BRIEF_FILE"; then + if grep -A 1 "Primary Keyword" "$BRIEF_FILE" | grep -qv "TBD\|^\s*$"; then + ((KEYWORD_SCORE++)) + fi +fi + +if grep -qi "Secondary Keyword" "$BRIEF_FILE"; then + ((KEYWORD_SCORE++)) +fi + +if grep -qi "Search Intent" "$BRIEF_FILE"; then + ((KEYWORD_SCORE++)) +fi + +if [ $KEYWORD_SCORE -eq 3 ]; then + echo -e "${GREEN}✓${NC} Complete keyword strategy defined" + ((CHECKS_PASSED++)) +elif [ $KEYWORD_SCORE -eq 2 ]; then + echo -e "${YELLOW}⚠${NC} Partial keyword strategy (add more details)" + ((WARNINGS++)) +elif [ $KEYWORD_SCORE -eq 1 ]; then + echo -e "${YELLOW}⚠${NC} Minimal keyword strategy (needs expansion)" + ((WARNINGS++)) +else + echo -e "${RED}✗${NC} No keyword strategy defined" + ((ISSUES_FOUND++)) +fi + +# Check for meta description +if grep -qi "Meta Description" "$BRIEF_FILE"; then + echo -e "${GREEN}✓${NC} Meta description section included" + ((CHECKS_PASSED++)) +else + echo -e "${YELLOW}⚠${NC} Meta description not mentioned" + ((WARNINGS++)) +fi + +# Check for internal links +if grep -qi "Internal Link" "$BRIEF_FILE"; then + echo -e "${GREEN}✓${NC} Internal linking strategy mentioned" + ((CHECKS_PASSED++)) +else + echo -e "${YELLOW}⚠${NC} Internal linking not addressed" + ((WARNINGS++)) +fi + +echo "" +echo -e "${BLUE}━━━ Content-Specific Checks ━━━${NC}" +echo "" + +# Check for tone/voice +if grep -qi "Tone\|Voice\|Writing Style" "$BRIEF_FILE"; then + echo -e "${GREEN}✓${NC} Tone and voice specified" + ((CHECKS_PASSED++)) +else + echo -e "${YELLOW}⚠${NC} Tone and voice not specified" + ((WARNINGS++)) +fi + +# Check for CTAs +if grep -qi "CTA\|Call.*Action" "$BRIEF_FILE"; then + echo -e "${GREEN}✓${NC} Call-to-action defined" + ((CHECKS_PASSED++)) +else + echo -e "${YELLOW}⚠${NC} No call-to-action specified" + ((WARNINGS++)) +fi + +# Check for success metrics +if grep -qi "Success Metric\|Primary Metric" "$BRIEF_FILE"; then + if grep -A 3 "Success Metric\|Primary Metric" "$BRIEF_FILE" | grep -qv "TBD"; then + echo -e "${GREEN}✓${NC} Success metrics defined" + ((CHECKS_PASSED++)) + else + echo -e "${RED}✗${NC} Success metrics not defined" + ((ISSUES_FOUND++)) + fi +else + echo -e "${RED}✗${NC} Success metrics section missing" + ((ISSUES_FOUND++)) +fi + +# Check for target audience pain points/problem +if grep -qi "Problem\|Pain Point" "$BRIEF_FILE"; then + echo -e "${GREEN}✓${NC} Audience problem/pain points addressed" + ((CHECKS_PASSED++)) +else + echo -e "${YELLOW}⚠${NC} Audience problem/pain points not explicitly stated" + ((WARNINGS++)) +fi + +# Check for research requirements +if grep -qi "Research\|Source" "$BRIEF_FILE"; then + echo -e "${GREEN}✓${NC} Research requirements mentioned" + ((CHECKS_PASSED++)) +else + echo -e "${YELLOW}⚠${NC} Research requirements not specified" + ((WARNINGS++)) +fi + +# Check for visual/media requirements +if grep -qi "Image\|Visual\|Media\|Screenshot" "$BRIEF_FILE"; then + echo -e "${GREEN}✓${NC} Visual/media requirements included" + ((CHECKS_PASSED++)) +else + echo -e "${YELLOW}⚠${NC} Visual/media requirements not specified" + ((WARNINGS++)) +fi + +# Document quality +echo "" +echo -e "${BLUE}━━━ Document Quality ━━━${NC}" +echo "" + +# Check word count +WORD_COUNT=$(wc -w < "$BRIEF_FILE") +echo -e "Brief word count: $WORD_COUNT" + +if [ "$WORD_COUNT" -lt 200 ]; then + echo -e "${RED}✗${NC} Brief is too short (< 200 words) - needs more detail" + ((ISSUES_FOUND++)) +elif [ "$WORD_COUNT" -lt 400 ]; then + echo -e "${YELLOW}⚠${NC} Brief is short (< 400 words) - consider adding more detail" + ((WARNINGS++)) +elif [ "$WORD_COUNT" -gt 2000 ]; then + echo -e "${YELLOW}⚠${NC} Brief is very long (> 2000 words) - ensure it's scannable" + ((WARNINGS++)) +else + echo -e "${GREEN}✓${NC} Brief length appropriate" + ((CHECKS_PASSED++)) +fi + +# Check for proper heading structure +if grep -q "^#\s" "$BRIEF_FILE"; then + echo -e "${GREEN}✓${NC} Proper heading structure" + ((CHECKS_PASSED++)) +else + echo -e "${YELLOW}⚠${NC} Check heading hierarchy (should start with # not ##)" + ((WARNINGS++)) +fi + +# Check for content type +if grep -qi "Content Type" "$BRIEF_FILE"; then + echo -e "${GREEN}✓${NC} Content type specified" + ((CHECKS_PASSED++)) +else + echo -e "${YELLOW}⚠${NC} Content type not specified" + ((WARNINGS++)) +fi + +# Final Summary +echo "" +echo -e "${BLUE}╔════════════════════════════════════════════════╗${NC}" +echo -e "${BLUE}║ Validation Summary ║${NC}" +echo -e "${BLUE}╚════════════════════════════════════════════════╝${NC}" +echo "" +echo -e "Checks passed: ${GREEN}$CHECKS_PASSED${NC}" +echo -e "Warnings: ${YELLOW}$WARNINGS${NC}" +echo -e "Issues found: ${RED}$ISSUES_FOUND${NC}" +echo "" + +# Calculate completeness score +TOTAL_CHECKS=$((CHECKS_PASSED + WARNINGS + ISSUES_FOUND)) +if [ $TOTAL_CHECKS -gt 0 ]; then + COMPLETENESS=$((CHECKS_PASSED * 100 / TOTAL_CHECKS)) + echo -e "Completeness: ${BLUE}${COMPLETENESS}%${NC}" + echo "" +fi + +# Recommendations +echo -e "${BLUE}━━━ Key Recommendations ━━━${NC}" +echo "" +echo "1. Fill in all TBD placeholders with specific information" +echo "2. Ensure primary keyword and SEO strategy are complete" +echo "3. Define clear, measurable success metrics" +echo "4. Specify tone, voice, and writing style guidelines" +echo "5. Include research sources and competitor analysis" +echo "6. Add visual/media requirements with specifications" +echo "7. Define clear CTAs aligned with content goals" +echo "8. Review with stakeholders before writer begins" +echo "" + +# Priority issues +if [ "$ISSUES_FOUND" -gt 0 ]; then + echo -e "${RED}⚠ Critical Issues to Address:${NC}" + if ! grep -qi "Primary Keyword" "$BRIEF_FILE" || grep -A 1 "Primary Keyword" "$BRIEF_FILE" | grep -q "TBD"; then + echo " • Define primary keyword for SEO" + fi + if ! grep -qi "Target Audience\|Primary Audience" "$BRIEF_FILE" || grep -A 2 "Target Audience\|Primary Audience" "$BRIEF_FILE" | grep -q "TBD"; then + echo " • Specify target audience clearly" + fi + if ! grep -qi "Success Metric" "$BRIEF_FILE" || grep -A 3 "Success Metric" "$BRIEF_FILE" | grep -q "TBD"; then + echo " • Define success metrics and targets" + fi + if ! grep -qi "Outline\|Key Sections\|Structure" "$BRIEF_FILE"; then + echo " • Add content structure or outline" + fi + if [ "$WORD_COUNT" -lt 200 ]; then + echo " • Add more detail to brief (currently too short)" + fi + echo "" +fi + +# Exit code +if [ "$ISSUES_FOUND" -gt 0 ]; then + echo -e "${RED}❌ Content brief validation failed${NC}" + echo -e " Address $ISSUES_FOUND critical issue(s) before proceeding" + exit 1 +elif [ "$WARNINGS" -gt 3 ]; then + echo -e "${YELLOW}⚠ Content brief validation passed with warnings${NC}" + echo -e " Consider addressing $WARNINGS warning(s) to improve quality" + exit 0 +else + echo -e "${GREEN}✅ Content brief validation passed!${NC}" + echo -e " Brief looks ready for writer to begin" + exit 0 +fi