@diottodev/runic 1.0.0 → 1.1.0

package/marketing/app-store-optimization/SKILL.md

@@ -0,0 +1,486 @@
+---
+name: "app-store-optimization"
+description: App Store Optimization (ASO) toolkit for researching keywords, analyzing competitor rankings, generating metadata suggestions, and improving app visibility on Apple App Store and Google Play Store. Use when the user asks about ASO, app store rankings, app metadata, app titles and descriptions, app store listings, app visibility, or mobile app marketing on iOS or Android. Supports keyword research and scoring, competitor keyword analysis, metadata optimization, A/B test planning, launch checklists, and tracking ranking changes.
+triggers:
+  - ASO
+  - app store optimization
+  - app store ranking
+  - app keywords
+  - app metadata
+  - play store optimization
+  - app store listing
+  - improve app rankings
+  - app visibility
+  - app store SEO
+  - mobile app marketing
+  - app conversion rate
+---
+
+# App Store Optimization (ASO)
+
+---
+
+## Keyword Research Workflow
+
+Discover and evaluate keywords that drive app store visibility.
+
+### Workflow: Conduct Keyword Research
+
+1. Define target audience and core app functions:
+   - Primary use case (what problem does the app solve)
+   - Target user demographics
+   - Competitive category
+2. Generate seed keywords from:
+   - App features and benefits
+   - User language (not developer terminology)
+   - App store autocomplete suggestions
+3. Expand keyword list using:
+   - Modifiers (free, best, simple)
+   - Actions (create, track, organize)
+   - Audiences (for students, for teams, for business)
+4. Evaluate each keyword:
+   - Search volume (estimated monthly searches)
+   - Competition (number and quality of ranking apps)
+   - Relevance (alignment with app function)
+5. Score and prioritize keywords:
+   - Primary: Title and keyword field (iOS)
+   - Secondary: Subtitle and short description
+   - Tertiary: Full description only
+6. Map keywords to metadata locations
+7. Document keyword strategy for tracking
+8. **Validation:** Keywords scored; placement mapped; no competitor brand names included; no plurals in iOS keyword field
+
+### Keyword Evaluation Criteria
+
+| Factor | Weight | High Score Indicators |
+|--------|--------|----------------------|
+| Relevance | 35% | Describes core app function |
+| Volume | 25% | 10,000+ monthly searches |
+| Competition | 25% | Top 10 apps have <4.5 avg rating |
+| Conversion | 15% | Transactional intent ("best X app") |
+
+### Keyword Placement Priority
+
+| Location | Search Weight |
+|----------|---------------|
+| App Title | Highest |
+| Subtitle (iOS) | High |
+| Keyword Field (iOS) | High |
+| Short Description (Android) | High |
+| Full Description | Medium |
+
+See: [references/keyword-research-guide.md](references/keyword-research-guide.md)
+
+---
+
+## Metadata Optimization Workflow
+
+Optimize app store listing elements for search ranking and conversion.
+
+### Workflow: Optimize App Metadata
+
+1. Audit current metadata against platform limits:
+   - Title character count and keyword presence
+   - Subtitle/short description usage
+   - Keyword field efficiency (iOS)
+   - Description keyword density
+2. Optimize title following formula:
+   ```
+   [Brand Name] - [Primary Keyword] [Secondary Keyword]
+   ```
+3. Write subtitle (iOS) or short description (Android):
+   - Focus on primary benefit
+   - Include secondary keyword
+   - Use action verbs
+4. Optimize keyword field (iOS only):
+   - Remove duplicates from title
+   - Remove plurals (Apple indexes both forms)
+   - No spaces after commas
+   - Prioritize by score
+5. Rewrite full description:
+   - Hook paragraph with value proposition
+   - Feature bullets with keywords
+   - Social proof section
+   - Call to action
+6. Validate character counts for each field
+7. Calculate keyword density (target 2-3% primary)
+8. **Validation:** All fields within character limits; primary keyword in title; no keyword stuffing (>5%); natural language preserved
+
+### Platform Character Limits
+
+| Field | Apple App Store | Google Play Store |
+|-------|-----------------|-------------------|
+| Title | 30 characters | 50 characters |
+| Subtitle | 30 characters | N/A |
+| Short Description | N/A | 80 characters |
+| Keywords | 100 characters | N/A |
+| Promotional Text | 170 characters | N/A |
+| Full Description | 4,000 characters | 4,000 characters |
+| What's New | 4,000 characters | 500 characters |
+
+### Description Structure
+
+```
+PARAGRAPH 1: Hook (50-100 words)
+├── Address user pain point
+├── State main value proposition
+└── Include primary keyword
+
+PARAGRAPH 2-3: Features (100-150 words)
+├── Top 5 features with benefits
+├── Bullet points for scanability
+└── Secondary keywords naturally integrated
+
+PARAGRAPH 4: Social Proof (50-75 words)
+├── Download count or rating
+├── Press mentions or awards
+└── Summary of user testimonials
+
+PARAGRAPH 5: Call to Action (25-50 words)
+├── Clear next step
+└── Reassurance (free trial, no signup)
+```
+
+See: [references/platform-requirements.md](references/platform-requirements.md)
+
+---
+
+## Competitor Analysis Workflow
+
+Analyze top competitors to identify keyword gaps and positioning opportunities.
+
+### Workflow: Analyze Competitor ASO Strategy
+
+1. Identify top 10 competitors:
+   - Direct competitors (same core function)
+   - Indirect competitors (overlapping audience)
+   - Category leaders (top downloads)
+2. Extract competitor keywords from:
+   - App titles and subtitles
+   - First 100 words of descriptions
+   - Visible metadata patterns
+3. Build competitor keyword matrix:
+   - Map which keywords each competitor targets
+   - Calculate coverage percentage per keyword
+4. Identify keyword gaps:
+   - Keywords with <40% competitor coverage
+   - High volume terms competitors miss
+   - Long-tail opportunities
+5. Analyze competitor visual assets:
+   - Icon design patterns
+   - Screenshot messaging and style
+   - Video presence and quality
+6. Compare ratings and review patterns:
+   - Average rating by competitor
+   - Common praise themes
+   - Common complaint themes
+7. Document positioning opportunities
+8. **Validation:** 10+ competitors analyzed; keyword matrix complete; gaps identified with volume estimates; visual audit documented
+
+### Competitor Analysis Matrix
+
+| Analysis Area | Data Points |
+|---------------|-------------|
+| Keywords | Title keywords, description frequency |
+| Metadata | Character utilization, keyword density |
+| Visuals | Icon style, screenshot count/style |
+| Ratings | Average rating, total count, velocity |
+| Reviews | Top praise, top complaints |
+
+### Gap Analysis Template
+
+| Opportunity Type | Example | Action |
+|------------------|---------|--------|
+| Keyword gap | "habit tracker" (40% coverage) | Add to keyword field |
+| Feature gap | Competitor lacks widget | Highlight in screenshots |
+| Visual gap | No videos in top 5 | Create app preview |
+| Messaging gap | None mention "free" | Test free positioning |
+
+---
+
+## App Launch Workflow
+
+Execute a structured launch for maximum initial visibility.
+
+### Workflow: Launch App to Stores
+
+1. Complete pre-launch preparation (4 weeks before):
+   - Finalize keywords and metadata
+   - Prepare all visual assets
+   - Set up analytics (Firebase, Mixpanel)
+   - Build press kit and media list
+2. Submit for review (2 weeks before):
+   - Complete all store requirements
+   - Verify compliance with guidelines
+   - Prepare launch communications
+3. Configure post-launch systems:
+   - Set up review monitoring
+   - Prepare response templates
+   - Configure rating prompt timing
+4. Execute launch day:
+   - Verify app is live in both stores
+   - Announce across all channels
+   - Begin review response cycle
+5. Monitor initial performance (days 1-7):
+   - Track download velocity hourly
+   - Monitor reviews and respond within 24 hours
+   - Document any issues for quick fixes
+6. Conduct 7-day retrospective:
+   - Compare performance to projections
+   - Identify quick optimization wins
+   - Plan first metadata update
+7. Schedule first update (2 weeks post-launch)
+8. **Validation:** App live in stores; analytics tracking; review responses within 24h; download velocity documented; first update scheduled
+
+### Pre-Launch Checklist
+
+| Category | Items |
+|----------|-------|
+| Metadata | Title, subtitle, description, keywords |
+| Visual Assets | Icon, screenshots (all sizes), video |
+| Compliance | Age rating, privacy policy, content rights |
+| Technical | App binary, signing certificates |
+| Analytics | SDK integration, event tracking |
+| Marketing | Press kit, social content, email ready |
+
+### Launch Timing Considerations
+
+| Factor | Recommendation |
+|--------|----------------|
+| Day of week | Tuesday-Wednesday (avoid weekends) |
+| Time of day | Morning in target market timezone |
+| Seasonal | Align with relevant category seasons |
+| Competition | Avoid major competitor launch dates |
+
+See: [references/aso-best-practices.md](references/aso-best-practices.md)
+
+---
+
+## A/B Testing Workflow
+
+Test metadata and visual elements to improve conversion rates.
+
+### Workflow: Run A/B Test
+
+1. Select test element (prioritize by impact):
+   - Icon (highest impact)
+   - Screenshot 1 (high impact)
+   - Title (high impact)
+   - Short description (medium impact)
+2. Form hypothesis:
+   ```
+   If we [change], then [metric] will [improve/increase] by [amount]
+   because [rationale].
+   ```
+3. Create variants:
+   - Control: Current version
+   - Treatment: Single variable change
+4. Calculate required sample size:
+   - Baseline conversion rate
+   - Minimum detectable effect (usually 5%)
+   - Statistical significance (95%)
+5. Launch test:
+   - Apple: Use Product Page Optimization
+   - Android: Use Store Listing Experiments
+6. Run test for minimum duration:
+   - At least 7 days
+   - Until statistical significance reached
+7. Analyze results:
+   - Compare conversion rates
+   - Check statistical significance
+   - Document learnings
+8. **Validation:** Single variable tested; sample size sufficient; significance reached (95%); results documented; winner implemented
+
+### A/B Test Prioritization
+
+| Element | Conversion Impact | Test Complexity |
+|---------|-------------------|-----------------|
+| App Icon | 10-25% lift possible | Medium (design needed) |
+| Screenshot 1 | 15-35% lift possible | Medium |
+| Title | 5-15% lift possible | Low |
+| Short Description | 5-10% lift possible | Low |
+| Video | 10-20% lift possible | High |
+
+### Sample Size Quick Reference
+
+| Baseline CVR | Impressions Needed (per variant) |
+|--------------|----------------------------------|
+| 1% | 31,000 |
+| 2% | 15,500 |
+| 5% | 6,200 |
+| 10% | 3,100 |
+
+### Test Documentation Template
+
+```
+TEST ID: ASO-2025-001
+ELEMENT: App Icon
+HYPOTHESIS: A bolder color icon will increase conversion by 10%
+START DATE: [Date]
+END DATE: [Date]
+
+RESULTS:
+├── Control CVR: 4.2%
+├── Treatment CVR: 4.8%
+├── Lift: +14.3%
+├── Significance: 97%
+└── Decision: Implement treatment
+
+LEARNINGS:
+- Bold colors outperform muted tones in this category
+- Apply to screenshot backgrounds for next test
+```
+
+---
+
+## Before/After Examples
+
+### Title Optimization
+
+**Productivity App:**
+
+| Version | Title | Analysis |
+|---------|-------|----------|
+| Before | "MyTasks" | No keywords, brand only (8 chars) |
+| After | "MyTasks - Todo List & Planner" | Primary + secondary keywords (29 chars) |
+
+**Fitness App:**
+
+| Version | Title | Analysis |
+|---------|-------|----------|
+| Before | "FitTrack Pro" | Generic modifier (12 chars) |
+| After | "FitTrack: Workout Log & Gym" | Category keywords (27 chars) |
+
+### Subtitle Optimization (iOS)
+
+| Version | Subtitle | Analysis |
+|---------|----------|----------|
+| Before | "Get Things Done" | Vague, no keywords |
+| After | "Daily Task Manager & Planner" | Two keywords, benefit clear |
+
+### Keyword Field Optimization (iOS)
+
+**Before (Inefficient - 89 chars, 8 keywords):**
+```
+task manager, todo list, productivity app, daily planner, reminder app
+```
+
+**After (Optimized - 97 chars, 14 keywords):**
+```
+task,todo,checklist,reminder,organize,daily,planner,schedule,deadline,goals,habit,widget,sync,team
+```
+
+**Improvements:**
+- Removed spaces after commas (+8 chars)
+- Removed duplicates (task manager → task)
+- Removed plurals (reminders → reminder)
+- Removed words in title
+- Added more relevant keywords
+
+### Description Opening
+
+**Before:**
+```
+MyTasks is a comprehensive task management solution designed
+to help busy professionals organize their daily activities
+and boost productivity.
+```
+
+**After:**
+```
+Forget missed deadlines. MyTasks keeps every task, reminder,
+and project in one place—so you focus on doing, not remembering.
+Trusted by 500,000+ professionals.
+```
+
+**Improvements:**
+- Leads with user pain point
+- Specific benefit (not generic "boost productivity")
+- Social proof included
+- Keywords natural, not stuffed
+
+### Screenshot Caption Evolution
+
+| Version | Caption | Issue |
+|---------|---------|-------|
+| Before | "Task List Feature" | Feature-focused, passive |
+| Better | "Create Task Lists" | Action verb, but still feature |
+| Best | "Never Miss a Deadline" | Benefit-focused, emotional |
+
+---
+
+## Tools and References
+
+### Scripts
+
+| Script | Purpose | Usage |
+|--------|---------|-------|
+| [keyword_analyzer.py](scripts/keyword_analyzer.py) | Analyze keywords for volume and competition | `python keyword_analyzer.py --keywords "todo,task,planner"` |
+| [metadata_optimizer.py](scripts/metadata_optimizer.py) | Validate metadata character limits and density | `python metadata_optimizer.py --platform ios --title "App Title"` |
+| [competitor_analyzer.py](scripts/competitor_analyzer.py) | Extract and compare competitor keywords | `python competitor_analyzer.py --competitors "App1,App2,App3"` |
+| [aso_scorer.py](scripts/aso_scorer.py) | Calculate overall ASO health score | `python aso_scorer.py --app-id com.example.app` |
+| [ab_test_planner.py](scripts/ab_test_planner.py) | Plan tests and calculate sample sizes | `python ab_test_planner.py --cvr 0.05 --lift 0.10` |
+| [review_analyzer.py](scripts/review_analyzer.py) | Analyze review sentiment and themes | `python review_analyzer.py --app-id com.example.app` |
+| [launch_checklist.py](scripts/launch_checklist.py) | Generate platform-specific launch checklists | `python launch_checklist.py --platform ios` |
+| [localization_helper.py](scripts/localization_helper.py) | Manage multi-language metadata | `python localization_helper.py --locales "en,es,de,ja"` |
+
+### References
+
+| Document | Content |
+|----------|---------|
+| [platform-requirements.md](references/platform-requirements.md) | iOS and Android metadata specs, visual asset requirements |
+| [aso-best-practices.md](references/aso-best-practices.md) | Optimization strategies, rating management, launch tactics |
+| [keyword-research-guide.md](references/keyword-research-guide.md) | Research methodology, evaluation framework, tracking |
+
+### Assets
+
+| Template | Purpose |
+|----------|---------|
+| [aso-audit-template.md](assets/aso-audit-template.md) | Structured audit checklist for app store listings |
+
+---
+
+## Platform Notes
+
+| Platform / Constraint | Behavior / Impact |
+|-----------------------|-------------------|
+| iOS keyword changes | Require app submission |
+| iOS promotional text | Editable without an app update |
+| Android metadata changes | Index in 1-2 hours |
+| Android keyword field | None — use description instead |
+| Keyword volume data | Estimates only; no official source |
+| Competitor data | Public listings only |
+
+**When not to use this skill:** web apps (use web SEO), enterprise/internal apps, TestFlight-only betas, or paid advertising strategy.
+
+---
+
+## Related Skills
+
+| Skill | Integration Point |
+|-------|-------------------|
+| [content-creator](../content-creator/) | App description copywriting |
+| [marketing-demand-acquisition](../marketing-demand-acquisition/) | Launch promotion campaigns |
+| [marketing-strategy-pmm](../marketing-strategy-pmm/) | Go-to-market planning |
+
+## Proactive Triggers
+
+- **No keyword optimization in title** → App title is the #1 ranking factor. Include top keyword.
+- **Screenshots don't show value** → Screenshots should tell a story, not show UI.
+- **No ratings strategy** → Below 4.0 stars kills conversion. Implement in-app rating prompts.
+- **Description keyword-stuffed** → Natural language with keywords beats keyword stuffing.
+
+## Output Artifacts
+
+| When you ask for... | You get... |
+|---------------------|------------|
+| "ASO audit" | Full app store listing audit with prioritized fixes |
+| "Keyword research" | Keyword list with search volume and difficulty scores |
+| "Optimize my listing" | Rewritten title, subtitle, description, keyword field |
+
+## Communication
+
+All output passes quality verification:
+- Self-verify: source attribution, assumption audit, confidence scoring
+- Output format: Bottom Line → What (with confidence) → Why → How to Act
+- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.

package/marketing/brand-guidelines/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: "brand-guidelines"
+description: "When the user wants to apply, document, or enforce brand guidelines for any product or company. Also use when the user mentions 'brand guidelines,' 'brand colors,' 'typography,' 'logo usage,' 'brand voice,' 'visual identity,' 'tone of voice,' 'brand standards,' 'style guide,' 'brand consistency,' or 'company design standards.' Covers color systems, typography, logo rules, imagery guidelines, and tone matrix for any brand — including Anthropic's official identity."
+license: MIT
+metadata:
+  version: 1.0.0
+  author: Alireza Rezvani
+  category: marketing
+  updated: 2026-03-06
+---
+
+# Brand Guidelines
+
+You are an expert in brand identity and visual design standards. Your goal is to help teams apply brand guidelines consistently across all marketing materials, products, and communications — whether working with an established brand system or building one from scratch.
+
+## How to Use This Skill
+
+**Check for product marketing context first:**
+If `.claude/product-marketing-context.md` exists, read it before applying brand standards. Use that context to tailor recommendations to the specific brand.
+
+When helping users:
+1. Identify whether they need to *apply* existing guidelines or *create* new ones
+2. For Anthropic artifacts, use the Anthropic identity system below
+3. For other brands, use the framework sections to assess and document their system
+4. Always check for consistency before creativity
+
+---
+
+## Anthropic Brand Identity
+→ See references/brand-identity-and-framework.md for details
+
+## Quick Audit Checklist
+
+Use this to rapidly assess brand consistency across any asset:
+
+- [ ] Colors match approved palette (no off-brand variations)
+- [ ] Fonts are correct typeface and weight
+- [ ] Logo has proper clear space and is an approved variation
+- [ ] Body text meets minimum size and contrast requirements
+- [ ] Imagery style matches brand guidelines
+- [ ] Tone matches brand voice attributes
+- [ ] No prohibited uses present (gradients on logo, wrong accent color, etc.)
+- [ ] Co-branding (if any) follows partner logo rules
+
+---
+
+## Task-Specific Questions
+
+1. Are you applying existing guidelines or creating new ones?
+2. What's the output format? (Digital, print, presentation, social)
+3. Do you have existing brand assets? (Logo files, color codes, fonts)
+4. Is there a brand foundation document? (Mission, values, positioning)
+5. What's the specific inconsistency or gap you're trying to fix?
+
+---
+
+## Proactive Triggers
+
+Proactively apply brand guidelines when:
+
+1. **Any visual asset requested** — Before creating any poster, slide, email, or social graphic, check if brand guidelines exist; if not, offer to establish a minimal system first.
+2. **Copy review touches tone** — When reviewing copy, cross-check against voice attributes and tone matrix, not just grammar.
+3. **New channel launch** — When a new marketing channel (TikTok, newsletter, podcast) is being set up, offer to apply the brand guidelines to that channel's specific format requirements.
+4. **Design feedback session** — When a user shares a design for feedback, run through the quick audit checklist before giving subjective opinions.
+5. **Partner or co-branded material** — Any co-branding situation should immediately trigger a review of logo clear space, sizing ratios, and color dominance rules.
+
+---
+
+## Output Artifacts
+
+| Artifact | Format | Description |
+|----------|--------|-------------|
+| Brand Audit Report | Markdown doc | Asset-by-asset compliance check against all brand dimensions |
+| Color System Reference | Table | Full palette with hex, RGB, CMYK, Pantone, and usage rules |
+| Tone Matrix | Table | Voice attributes × context combinations with example phrases |
+| Typography Scale | Table | All type roles with font, size, weight, and line-height specifications |
+| Brand Guidelines Mini-Doc | Markdown doc | Condensed brand guide covering all 7 dimensions, ready to share with contractors |
+
+---
+
+## Communication
+
+Brand consistency is not a design preference — it's a trust signal. Every deviation from guidelines erodes recognition. When auditing or creating brand materials, be specific: name the exact color code, font weight, and pixel measurement rather than giving subjective feedback. Reference `marketing-context` to ensure brand voice recommendations align with the ICP and product positioning. Quality bar: brand outputs should be specific enough that a contractor who has never worked with the brand could produce on-brand work from the artifact alone.
+
+---
+
+## Related Skills
+
+- **marketing-context** — USE as the brand foundation layer; brand voice and visual decisions must align with ICP, positioning, and messaging; always load first.
+- **copywriting** — USE when brand voice guidelines need to be applied to specific page or campaign copy; NOT as a substitute for defining voice attributes.
+- **content-humanizer** — USE when existing content needs to be rewritten to match brand tone without losing information; NOT for structural content work.
+- **social-content** — USE when applying brand guidelines to social-specific formats and platform constraints; NOT for cross-channel brand system design.
+- **canvas-design** — USE when brand guidelines need to be applied to visual design artifacts (posters, PDFs, graphics); NOT for copy-only brand work.