Skill: kirkraman/kirk-marketing (version 1.0.0)

--- name: instagram-marketing description: Generate Instagram marketing content from product URLs. Extract product information and create engaging Instagram posts with image suggestions, captions, and hashtags optimized for engagement. Use when user provides a product URL from e-commerce sites like Amazon, Shopify, Taobao, etc. and wants Instagram marketing content such as Image/text post ideas, engaging captions with CTAs, hashtag strategy, or Story/reels content suggestions. requires.env: [SKILLBOSS_API_KEY] --- # Instagram Marketing Generator ## Overview Transform any product URL into scroll-stopping Instagram content. Extract product details via SkillBoss API Hub, analyze brand positioning, and generate platform-native marketing assets that drive engagement and conversions. ## Quick Start 1. **Input**: Provide product URL 2. **Extract**: Use `scripts/extract_product.py` to fetch product details via SkillBoss API Hub (requires `SKILLBOSS_API_KEY`) 3. **Generate**: Apply Instagram content frameworks from `references/` 4. **Deliver**: Output ready-to-post content package ## Content Frameworks ### Framework Selection Guide Choose based on product type and brand personality: | Product Type | Recommended Framework | Reference | |--------------|----------------------|-----------| | Fashion/Beauty | Aesthetic + Lifestyle | `FASHION.md` | | Tech/Gadgets | Feature-First + Demo | `TECH.md` | | Food/Beverage | Sensory + Lifestyle | `LIFESTYLE.md` | | Home/Decor | Transformation + Tips | `HOME.md` | | Services | Trust + Results | `SERVICE.md` | ### Core Content Elements Every Instagram post package includes: #### 1. Image/Video Brief ``` • Visual style (aesthetic direction) • Composition guidelines • Text overlay suggestions (optional) • Product angle recommendations • Background/props guidance ``` #### 2. Caption Structure ``` HOOK → [First line - stops the scroll] | ├── BODY → [Value proposition, benefits, story] | └── CTA → [Clear action: link, DM, save, share] ``` **Caption Length Guide:** - Feed posts: 138-150 characters (optimal engagement) - Carousel: 150-200 characters - Educational: Up to 300 characters #### 3. Hashtag Strategy (30 max) ``` • 3-5 branded/niche tags (high relevance) • 10-15 trend tags (moderate volume) • 5-10 broad tags (max reach) • Mix of: #branded #descriptive #trend #location #emotion ``` See `references/HASHTAG_STRATEGY.md` for detailed hashtag optimization. ## Product Information Extraction ### Script Usage ```bash SKILLBOSS_API_KEY=your_key python3 scripts/extract_product.py <url> ``` The script uses **SkillBoss API Hub** (`https://api.skillbossai.com/v1/pilot`) to: 1. Scrape the product page via the `scraping` capability 2. Extract structured product data via the `chat` capability (auto-routed LLM) **Extracted fields:** - Product name - Price/value proposition - Key features (3-5) - Target audience - Unique selling proposition - Platform (Amazon/Shopify/Taobao/JD/Generic) - Suggested content type ### Manual Extraction Fallback If script fails, extract manually: 1. Visit product URL 2. Identify: name, price, features, benefits 3. Note brand visual style 4. Capture 3-5 product angles ## Content Generation Workflow ### Step 1: Analyze Product & Audience ``` PRODUCT → [What is it? What problem does it solve?] | ├── TARGET AUDIENCE → [Who needs this? Why?] | ├── BRAND TONE → [Luxury? Playful? Minimal? Bold?] | └── PLATFORM FIT → [Feed post, Story, Reel, Carousel?] ``` **Key Questions:** - What emotion should the user feel? - What's the "scroll-stopping" moment? - What's the post-purchase transformation? ### Step 2: Choose Content Format #### Feed Post (Single Image) - **Best for**: Product showcases, announcements - **Visual**: High-quality product shot, clean background - **Caption**: Punchy hook + benefits + CTA #### Carousel (Swipe-able) - **Best for**: Features, tutorials, transformations - **Structure**: 5-10 slides 1. Hook slide 2-4. Feature/benefit slides 5. CTA slide #### Story (15-60 sec) - **Best for**: Flash sales, polls, Q&A, behind-scenes - **Elements**: Interactive stickers, tap-through links #### Reel (15-90 sec video) - **Best for**: Demos, unboxing, transformations - **Hook**: First 1 second critical - **Music**: Trending audio boost ### Step 3: Generate Content Package Output format (see `templates/OUTPUT_TEMPLATE.md`): ```markdown ## Instagram Content Package ### Post Type: [Feed/Carousel/Story/Reel] ### Image/Video Brief [Visual direction + composition] ### Caption [Hook + Body + CTA] ### Hashtags [30 optimized hashtags] ### Posting Strategy [Time, frequency, cross-post suggestions] ``` ## Instagram Style Guidelines ### Visual Principles 1. **Consistency First** - Cohesive color palette (3-5 colors max) - Consistent filter/preset - Recognizable brand aesthetic 2. **Quality Over Quantity** - High-resolution images (1080x1080 or 1080x1350) - Good lighting (natural preferred) - Clean composition (rule of thirds) 3. **Native Feel** - Avoid over-polished, stock-looking content - Embrace authenticity - Show real people/products ### Caption Best Practices ✅ DO: - Start with a hook (question, bold statement, emotion) - Write conversationally (like talking to a friend) - Use line breaks for readability - Include clear CTA - Add 3-5 relevant hashtags ❌ DON'T: - Write paragraphs longer than 3 lines - Use excessive emojis (1-3 max) - Overuse hashtags (30 max, quality > quantity) - Sound robotic or overly promotional - Include "link in bio" more than once ### Engagement Triggers Embed these in content: ``` • Questions: "Which color would you choose?" • Opinions: "Yes or No?" • Saves: "Save this for later" • Shares: "Tag someone who needs this" • CTAs: "Link in bio to shop" ``` ## Content Templates ### Template 1: Problem-Solution ``` Hook: Tired of [problem]? Body: Meet [product]. It [benefit 1], [benefit 2], and [benefit 3]. CTA: Shop now → link in bio ``` ### Template 2: Transformation ``` Hook: Before → After Body: How [product] transformed [situation]. CTA: See the difference → link in bio ``` ### Template 3: Social Proof ``` Hook: ⭐⭐⭐⭐⭐ "Review quote" Body: Join [number]+ happy customers. CTA: Try it risk-free → link in bio ``` ### Template 4: Educational ``` Hook: 5 things you didn't know about [product/category] Body: [Value-packed tips] CTA: Save this post + follow for more ``` ### Template 5: Limited Time ``` Hook: 🚨 Only [number] left! Body: [Product] at [price] for [timeframe]. CTA: Don't miss out → link in bio ``` ## Advanced: Multi-Post Series For product launches or campaigns, create 3-5 post series: ### Series Structure 1. **Teaser** (2-3 days before) - Build anticipation - "Something big coming" 2. **Launch** (Day 1) - Product reveal - Key features 3. **Deep Dive** (Day 2-3) - Benefits, use cases - Social proof 4. **Urgency** (Day 4-5) - Limited availability - Last chance See `references/CAMPAIGN_STRATEGY.md` for complete campaign planning. ## References ### Detailed Guides - `references/FASHION.md` - Fashion & beauty content - `references/TECH.md` - Tech & gadgets content - `references/HASHTAG_STRATEGY.md` - Hashtag optimization - `references/CAMPAIGN_STRATEGY.md` - Multi-post campaigns - `references/ENGAGEMENT_TACTICS.md` - Comment management & growth ### Templates - `templates/CAROUSEL_TEMPLATE.md` - Swipe-able post structure - `templates/STORY_TEMPLATE.md` - Interactive story framework - `templates/REEL_TEMPLATE.md` - Video script structure - `templates/OUTPUT_TEMPLATE.md` - Final content format ## Tips - Always match content to brand voice - Test different hook styles - Analyze competitor posts for inspiration - Repurpose content across formats (feed → story → reel) - Save high-performing posts as templates - Time posts for peak audience hours - Engage with comments within 1 hour - Use Instagram Insights to optimize

path: references/HASHTAG_STRATEGY.md
content: # Instagram Hashtag Strategy

## The 3-Tier Formula

### Tier 1: Niche/Branded Tags (3-5)
**Purpose**: High relevance, targeted audience
**Volume**: 10k-100k posts
**Examples**: #yourbrandname #specificproduct #nicheterm

### Tier 2: Trend/Category Tags (10-15)
**Purpose**: Moderate reach, active communities
**Volume**: 100k-1M posts
**Examples**: #fashionhacks #techdeals #homede cor

### Tier 3: Broad Tags (5-10)
**Purpose**: Maximum reach, discoverability
**Volume**: 1M+ posts
**Examples**: #fashion #tech #decor #instagood

## Research Framework

### Step 1: Competitor Analysis
```
1. Identify 5-10 successful accounts in your niche
2. Note their top-performing hashtags
3. Look for patterns in tag combinations
```

### Step 2: Hashtag Testing
```
Week 1: Test Set A (30 tags)
Week 2: Test Set B (30 tags)
Week 3: Mix top performers from A + B
```

### Step 3: Performance Tracking
Monitor these metrics:
- Reach from hashtags
- Follower growth rate
- Engagement rate
- Save counts

## Category-Specific Tag Libraries

### Fashion & Beauty
**Niche**: #ootdstyle #fashioninspo #beautyhacks #makeuptutorial #skincareroutine
**Trend**: #fashiondiaries #beautytips #styleinspiration #makeuplooks #glowingskin
**Broad**: #fashion #beauty #style #makeup #skincare #instafashion #beautyblogger

### Tech & Gadgets
**Niche**: #techdeals #gadgetlover #techreview #unboxing #setup
**Trend**: #techtrends #gadgets #techlife #newtech #technews
**Broad**: #technology #gadgets #tech #innovation #smartphone #laptop #camera

### Food & Beverage
**Niche**: #foodphotography #recipeideas #healthyfood #instafood #foodlover
**Trend**: #foodstagram #foodblogger #homecooking #yummy #delicious
**Broad**: #food #foodie #instagood #yummy #delicious #homemade #cooking

### Home & Decor
**Niche**: #homedecor #interiordesign #roommakeover #homedesign #decor
**Trend**: #homedesign #interiors #apartmenttherapy #homestyling #hacks
**Broad**: #home #decor #design #interior #architecture #house #livingroom

### Lifestyle & Travel
**Niche**: #travelgram #lifestyleblogger #dailyvlog #lifehacks #wanderlust
**Trend**: #travelphotography #lifestyle #instatravel #vacationmode #adventure
**Broad**: #travel #lifestyle #photooftheday #instagood #explore #wanderlust

## Avoid These Hashtag Mistakes

### ❌ DON'T:
- Use banned hashtags (check regulary)
- Overuse generic tags like #follow #like4like
- Mix irrelevant hashtags for reach
- Use the exact same 30 tags every post
- Include hashtags in the middle of captions

### ✅ DO:
- Rotate hashtag sets regularly
- Mix hashtag sizes (small + medium + large)
- Research trending hashtags weekly
- Create branded hashtags for your business
- Monitor hashtag performance

## Branded Hashtag Creation

### Rules for Good Branded Hashtags
1. **Keep it short** (under 15 characters)
2. **Make it memorable** (easy to spell/remember)
3. **Keep it relevant** (connects to brand/product)
4. **Check availability** (not overused)

### Examples
- Nike: #justdoit #nikerun
- Lululemon: #thesweatlife
- GoPro: #goprohero
- Airbnb: #airbnbexperience

## Seasonal & Trending Hashtags

### Monthly Calendar
- January: #newyearnewme #winter #january
- February: #valentines #love #february
- March: #springishere #internationalwomensday
- April: #spring #april #earthday
- May: #mothersday #may #memorialday
- June: #summer #fathersday #pridemonth
- July: #july4th #summer #independenceday
- August: #backtoschool #summervibes
- September: #fallfashion #laborday #autumn
- October: #halloween #october #spookyseason
- November: #thanksgiving #grateful #november
- December: #christmas #holidays #december

### Trend Monitoring
Check these sources weekly:
- Instagram Explore page hashtags
- Influencer posts in your niche
- Twitter trending topics (for crossover)
- Google Trends for related searches


path: scripts/extract_product.py
content: #!/usr/bin/env python3
"""
Instagram Marketing Product Extractor

Extracts product information from e-commerce URLs for Instagram content generation.
Supports: Amazon, Shopify, Taobao, JD, and generic e-commerce sites.

Uses SkillBoss API Hub (https://api.skillbossai.com/v1/pilot) for web scraping
and AI-powered structured data extraction.

Usage:
    python extract_product.py <url>

Environment:
    SKILLBOSS_API_KEY  — SkillBoss API Hub key

Output:
    JSON object with product details for content generation
"""

import sys
import json
import os
import requests
from typing import Dict

SKILLBOSS_API_KEY = os.environ["SKILLBOSS_API_KEY"]
API_BASE = "https://api.skillbossai.com/v1"


def pilot(body: dict) -> dict:
    r = requests.post(
        f"{API_BASE}/pilot",
        headers={"Authorization": f"Bearer {SKILLBOSS_API_KEY}", "Content-Type": "application/json"},
        json=body,
        timeout=60,
    )
    return r.json()


class ProductExtractor:
    """Extract product information from e-commerce URLs via SkillBoss API Hub."""

    def __init__(self, url: str):
        self.url = url

    def extract(self) -> Dict:
        """Extract product info using SkillBoss scraping + chat."""
        try:
            # Step 1: Scrape the product page via SkillBoss API Hub
            scrape_result = pilot({
                "type": "scraper",
                "inputs": {"url": self.url},
                "prefer": "balanced"
            })
            page_content = scrape_result["result"]["data"]["markdown"]

            # Step 2: Use SkillBoss LLM to extract structured product data
            extraction_prompt = f"""Extract product information from this page content and return a JSON object with exactly these fields:
- name: product name (string)
- price: product price (string)
- description: brief product description, max 200 characters (string)
- features: list of up to 5 key product features (array of strings)
- target_audience: who this product is for, e.g. Men/Women/Kids/Gamers/Fitness Enthusiasts/Homeowners/General Consumers (string)
- usp: unique selling proposition in one sentence (string)
- platform: e-commerce platform name, one of Amazon/Shopify/Taobao/JD/Generic (string)

Page URL: {self.url}
Page Content:
{page_content[:3000]}

Return ONLY valid JSON with no markdown fences."""

            chat_result = pilot({
                "type": "chat",
                "inputs": {
                    "messages": [{"role": "user", "content": extraction_prompt}]
                },
                "prefer": "balanced"
            })
            text = chat_result["result"]["choices"][0]["message"]["content"]

            product_data = json.loads(text)
            product_data["url"] = self.url
            product_data["content_type"] = self._suggest_content_type(product_data)
            return product_data

        except Exception as e:
            return {
                "error": f"Extraction failed: {str(e)}",
                "manual_extraction_needed": True,
                "url": self.url,
                "extraction_guide": {
                    "product_name": "Copy from page title or h1",
                    "price": "Find price display on page",
                    "features": "Look for bullet points or product highlights (3-5 items)",
                    "description": "Copy product description (first paragraph)",
                    "target_audience": "Who would buy this? (Men/Women/Kids/etc)",
                    "brand_tone": "Is it luxury, playful, minimal, or bold?",
                    "existing_images": "Note if there are product photos to reference"
                }
            }

    def _suggest_content_type(self, data: Dict) -> str:
        """Suggest best Instagram content format."""
        name = data.get("name", "").lower()
        features = data.get("features", [])

        if any(w in name for w in ["fashion", "clothing", "shoe"]):
            return "Carousel (Lifestyle + Details + Fit)"
        elif any(w in name for w in ["video", "camera", "audio", "speaker"]):
            return "Reel (Demo + Usage Scenes)"
        elif len(features) >= 3:
            return "Carousel (Feature-by-feature breakdown)"
        else:
            return "Feed Post (High-quality product shot)"


def main():
    if len(sys.argv) < 2:
        print(json.dumps({
            "error": "Usage: python extract_product.py <url>",
            "example": "python extract_product.py https://www.amazon.com/dp/B08N5WRWNW"
        }, indent=2))
        sys.exit(1)

    url = sys.argv[1]
    extractor = ProductExtractor(url)
    result = extractor.extract()

    print(json.dumps(result, indent=2, ensure_ascii=False))


if __name__ == "__main__":
    main()


path: templates/OUTPUT_TEMPLATE.md
content: # Instagram Content Package Output Template

## Content Structure

Copy this template for each Instagram content package you generate:

---

## Instagram Content Package

### 📦 Product Overview

**Product Name**: [Insert product name]
**Price**: [Insert price]
**Platform**: [Amazon/Shopify/etc]
**Target Audience**: [Demographic]

---

### 🎨 Content Format: [Feed Post / Carousel / Story / Reel]

**Rationale**: [Why this format works for this product]

---

### 📸 Image/Video Brief

#### Visual Style
- **Aesthetic**: [Minimalist / Bold / Luxury / Playful / Warm / Cool / etc]
- **Color Palette**: [3-5 colors that match product/brand]
- **Mood**: [Calm / Energetic / Sophisticated / Friendly / etc]

#### Composition Guidelines
- **Primary Shot**: [Product angle - flat lay, lifestyle, detail, etc]
- **Background**: [Clean / Lifestyle setting / Gradient / Texture]
- **Props**: [Items that enhance context without distracting]
- **Lighting**: [Natural / Studio / Side-lit / Backlit]
- **Text Overlay** (optional): [Key benefit or price if relevant]

#### Image Specifications
- **Dimensions**: [1080x1080 for feed / 1080x1350 for portrait / 1080x1920 for story]
- **Format**: [JPG for photos / PNG for graphics / MP4 for video]
- **File Size**: [Under 2MB for optimal upload]

---

### ✍️ Caption

#### Hook (First Line)
```
[Scroll-stopping opening line - question, bold statement, or emotional trigger]
```

#### Body
```
[2-3 sentence value proposition]
- [Key benefit 1]
- [Key benefit 2]
- [Key benefit 3 if applicable]
```

#### CTA (Call to Action)
```
[Clear action - link in bio, DM, save, share, tag]
```

#### Full Caption
```
[Hook]

[Body text with line breaks for readability]

[CTA]

[Hashtags - see section below]
```

**Caption Character Count**: [150 / 300 / etc]
**First Line Preview**: [Test how hook appears in feed]

---

### #️⃣ Hashtag Strategy (30 total)

#### Branded/Niche Tags (3-5)
```
#[yourbrand]
#[specificproduct]
#[nicheterm1]
#[nicheterm2]
#[nicheterm3]
```

#### Trend/Category Tags (10-15)
```
#[category1]
#[category2]
#[trendingtag1]
#[trendingtag2]
...
```

#### Broad Tags (5-10)
```
#fashion
#instagood
#photooftheday
#style
#love
```

**Full Hashtag Set**:
```
[All 30 hashtags in one block for easy copy-paste]
```

---

### ⏰ Posting Strategy

#### Best Times to Post
- **Weekdays**: [Time - e.g., 9-10am or 7-8pm]
- **Weekends**: [Time - e.g., 10-11am or 6-7pm]
- **Timezone**: [Specify timezone]

#### Frequency
- **Feed Posts**: [X times per week]
- **Stories**: [X times per day/week]
- **Reels**: [X times per week]

#### Cross-Post Suggestions
- [Facebook: Yes/No + timing]
- [TikTok: Yes/No + format adjustments]
- [Pinterest: Yes/No + board selection]

---

### 💬 Engagement Preparation

#### Comment Responses to Prepare
1. **For "How much?" questions**: [Price + CTA]
2. **For "Where to buy?" questions**: [Link in bio direction]
3. **For "Is it worth it?" questions**: [Value proposition]

#### Story Interactions
- **Poll Questions**: [Option A vs Option B]
- **Question Sticker**: [Open-ended question]
- **Quiz**: [Trivia about product/benefits]
- **Countdown Sticker**: [For limited-time offers]

---

### 📊 Success Metrics

Track these after posting:
- **Reach**: [Expected range]
- **Engagement Rate**: [Target - e.g., 2-5%]
- **Saves**: [Target - indicates valuable content]
- **Shares**: [Target - indicates shareability]
- **Profile Visits**: [Target - indicates interest]
- **Link Clicks**: [For shoppable posts]

---

### 🔄 Content Repurposing Ideas

Extend this content across formats:
1. **Feed Post** → **Story**: [Turn into 3-4 story frames]
2. **Carousel** → **Reel**: [Animate slides into video]
3. **Caption Highlights** → **Text Post**: [Quote the hook]
4. **Product Details** → **Guide**: [Educational carousel]

---

### 📝 Notes for Creator

- [Special instructions for photographer/designer]
- [Brand voice guidelines]
- [Things to avoid]
- [Compliance notes (if applicable)]

---

## Checklist Before Publishing

- [ ] Image/video meets quality standards
- [ ] Caption hook is strong
- [ ] CTA is clear
- [ ] Hashtags are relevant and researched
- [ ] Link in bio is updated (if applicable)
- [ ] Post scheduled for optimal time
- [ ] Story highlights organized (if applicable)
- [ ] Engaged with comments within 1 hour after posting

---

**Generated by Instagram Marketing Skill**
**Date**: [Generation date]


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)