Initial commit
This commit is contained in:
Zhongwei Li
496
skills/content-brief-generator/SKILL.md
Normal file
496
skills/content-brief-generator/SKILL.md
Normal file
@@ -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.
|
||||
707
skills/content-brief-generator/references/content_frameworks.md
Normal file
707
skills/content-brief-generator/references/content_frameworks.md
Normal file
@@ -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.
|
||||
730
skills/content-brief-generator/references/seo_guidelines.md
Normal file
730
skills/content-brief-generator/references/seo_guidelines.md
Normal file
@@ -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.
|
||||
690
skills/content-brief-generator/references/tone_voice_guide.md
Normal file
690
skills/content-brief-generator/references/tone_voice_guide.md
Normal file
@@ -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.
|
||||
568
skills/content-brief-generator/scripts/generate_brief.sh
Executable file
568
skills/content-brief-generator/scripts/generate_brief.sh
Executable file
@@ -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 ""
|
||||
372
skills/content-brief-generator/scripts/validate_brief.sh
Executable file
372
skills/content-brief-generator/scripts/validate_brief.sh
Executable file
@@ -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 <brief_file.md>"
|
||||
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
|
||||
Reference in New Issue
Block a user