From a33c69835bd127fe80fdbd1413f84702e9aa93e4 Mon Sep 17 00:00:00 2001 From: admin Date: Wed, 4 Feb 2026 17:14:10 +0000 Subject: [PATCH] Update skills --- deepwiki/.clawdhub/origin.json | 7 + deepwiki/SKILL.md | 46 ++ deepwiki/scripts/deepwiki.js | 135 +++++ marketing-mode/.clawdhub/origin.json | 7 + marketing-mode/README.md | 49 ++ marketing-mode/SKILL.md | 693 +++++++++++++++++++++++ marketing-mode/mode-prompt.md | 39 ++ marketing-mode/skill.json | 51 ++ skillshare/.skillshare-meta.json | 4 +- skillshare/SKILL.md | 130 ++--- skillshare/references/TROUBLESHOOTING.md | 171 ++---- skillshare/references/backup.md | 24 +- skillshare/references/init.md | 83 +-- skillshare/references/install.md | 81 ++- skillshare/references/status.md | 46 +- skillshare/references/sync.md | 56 +- skillshare/references/targets.md | 27 +- skillshare/scripts/run.sh | 2 +- tavily/.clawdhub/origin.json | 7 + tavily/SKILL.md | 414 ++++++++++++++ tavily/references/api-reference.md | 187 ++++++ tavily/scripts/tavily_search.py | 247 ++++++++ 22 files changed, 2158 insertions(+), 348 deletions(-) create mode 100644 deepwiki/.clawdhub/origin.json create mode 100644 deepwiki/SKILL.md create mode 100644 deepwiki/scripts/deepwiki.js create mode 100644 marketing-mode/.clawdhub/origin.json create mode 100644 marketing-mode/README.md create mode 100644 marketing-mode/SKILL.md create mode 100644 marketing-mode/mode-prompt.md create mode 100644 marketing-mode/skill.json create mode 100644 tavily/.clawdhub/origin.json create mode 100644 tavily/SKILL.md create mode 100644 tavily/references/api-reference.md create mode 100644 tavily/scripts/tavily_search.py diff --git a/deepwiki/.clawdhub/origin.json b/deepwiki/.clawdhub/origin.json new file mode 100644 index 0000000..b75e7f8 --- /dev/null +++ b/deepwiki/.clawdhub/origin.json @@ -0,0 +1,7 @@ +{ + "version": 1, + "registry": "https://clawhub.ai", + "slug": "deepwiki", + "installedVersion": "1.0.0", + "installedAt": 1769916339615 +} diff --git a/deepwiki/SKILL.md b/deepwiki/SKILL.md new file mode 100644 index 0000000..2955b78 --- /dev/null +++ b/deepwiki/SKILL.md @@ -0,0 +1,46 @@ +--- +name: deepwiki +description: Query the DeepWiki MCP server for GitHub repository documentation, wiki structure, and AI-powered questions. +homepage: https://docs.devin.ai/work-with-devin/deepwiki-mcp +--- + +# DeepWiki + +Use this skill to access documentation for public GitHub repositories via the DeepWiki MCP server. You can search repository wikis, get structure, and ask complex questions grounded in the repository's documentation. + +## Commands + +### Ask Question +Ask any question about a GitHub repository and get an AI-powered, context-grounded response. +```bash +node ./scripts/deepwiki.js ask "your question" +``` + +### Read Wiki Structure +Get a list of documentation topics for a GitHub repository. +```bash +node ./scripts/deepwiki.js structure +``` + +### Read Wiki Contents +View documentation about a specific path in a GitHub repository's wiki. +```bash +node ./scripts/deepwiki.js contents +``` + +## Examples + +**Ask about Devin's MCP usage:** +```bash +node ./scripts/deepwiki.js ask cognitionlabs/devin "How do I use MCP?" +``` + +**Get the structure for the React docs:** +```bash +node ./scripts/deepwiki.js structure facebook/react +``` + +## Notes +- Base Server: `https://mcp.deepwiki.com/mcp` +- Works for public repositories only. +- No authentication required. diff --git a/deepwiki/scripts/deepwiki.js b/deepwiki/scripts/deepwiki.js new file mode 100644 index 0000000..2c5c718 --- /dev/null +++ b/deepwiki/scripts/deepwiki.js @@ -0,0 +1,135 @@ +#!/usr/bin/env node +const http = require('https'); + +const args = process.argv.slice(2); +const command = args[0]; +const repo = args[1]; +const extra = args[2]; + +if (!command || !repo) { + console.log('Usage: deepwiki.js [args]'); + console.log('Commands: ask, structure, contents'); + process.exit(0); +} + +const SSE_URL = 'https://mcp.deepwiki.com/sse'; + +async function run() { + let sessionId = null; + let messageUrl = null; + + // 1. Establish SSE connection + const sseReq = http.get(SSE_URL, (res) => { + let buffer = ''; + res.on('data', (chunk) => { + buffer += chunk.toString(); + + // Parse SSE events + const lines = buffer.split('\n'); + buffer = lines.pop(); // Keep incomplete line + + let currentEvent = null; + for (const line of lines) { + if (line.startsWith('event: ')) { + currentEvent = line.substring(7).trim(); + } else if (line.startsWith('data: ')) { + const data = line.substring(6).trim(); + + if (currentEvent === 'endpoint') { + messageUrl = 'https://mcp.deepwiki.com' + data; + const url = new URL(messageUrl); + sessionId = url.searchParams.get('sessionId'); + + // Now that we have the session, send the tool call + sendToolCall(messageUrl); + } else if (currentEvent === 'message') { + try { + const msg = JSON.parse(data); + // Check if this is the response to our request (id: 1) + if (msg.id === 1) { + if (msg.error) { + console.error('Error:', msg.error.message); + } else { + handleResult(msg.result); + } + sseReq.destroy(); + process.exit(0); + } + } catch (e) { + // Ignore non-JSON or other messages + } + } + } else if (line === '') { + currentEvent = null; + } + } + }); + }); + + sseReq.on('error', (err) => { + console.error('SSE Error:', err.message); + process.exit(1); + }); + + // Timeout after 30s + setTimeout(() => { + console.error('Request timed out'); + sseReq.destroy(); + process.exit(1); + }, 30000); +} + +function sendToolCall(url) { + let name, params; + if (command === 'ask') { + name = 'ask_question'; + params = { repoName: repo, question: extra }; + } else if (command === 'structure') { + name = 'read_wiki_structure'; + params = { repoName: repo }; + } else if (command === 'contents') { + name = 'read_wiki_contents'; + params = { repoName: repo, path: extra }; + } + + const body = JSON.stringify({ + jsonrpc: '2.0', + id: 1, + method: 'tools/call', + params: { + name, + arguments: params + } + }); + + const req = http.request(url, { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + 'Content-Length': body.length + } + }, (res) => { + if (res.statusCode !== 200 && res.statusCode !== 202) { + console.error(`Post failed: ${res.statusCode}`); + process.exit(1); + } + }); + + req.on('error', (err) => { + console.error('Post Error:', err.message); + process.exit(1); + }); + + req.write(body); + req.end(); +} + +function handleResult(result) { + if (result && result.content) { + console.log(result.content.map(c => c.text).join('\n')); + } else { + console.log(JSON.stringify(result, null, 2)); + } +} + +run(); diff --git a/marketing-mode/.clawdhub/origin.json b/marketing-mode/.clawdhub/origin.json new file mode 100644 index 0000000..00efc79 --- /dev/null +++ b/marketing-mode/.clawdhub/origin.json @@ -0,0 +1,7 @@ +{ + "version": 1, + "registry": "https://clawhub.ai", + "slug": "marketing-mode", + "installedVersion": "1.0.0", + "installedAt": 1769908617464 +} diff --git a/marketing-mode/README.md b/marketing-mode/README.md new file mode 100644 index 0000000..aec80be --- /dev/null +++ b/marketing-mode/README.md @@ -0,0 +1,49 @@ +# Marketing Mode + +πŸ“ˆ **Mark the Marketer** - Growth-obsessed marketing strategist + +## Activation + +```bash +clawdhub install marketing-mode +``` + +Then tell Clawdbot to switch modes. + +## Who is Mark? + +Mark is a growth-obsessed marketing strategist who lives for the next conversion. He speaks in marketing frameworks, funnels, and metrics. + +## Marketing Frameworks + +### AIDA (Attention β†’ Interest β†’ Desire β†’ Action) +The classic marketing funnel. Use to structure messaging and content. + +### PAS (Problem β†’ Agitation β†’ Solution) +Identify the problem, agitate it (make it hurt), then provide the solution. + +### Hook Model (Trigger β†’ Action β†’ Variable Reward β†’ Investment) +Build habit-forming products by designing compelling hooks. + +### Value Proposition Canvas +Match what customers need with what you offer. + +### Positioning Framework +Answer: Who is this for? What does it do? Why is it different? + +## Usage Examples + +Mark helps with: +- Writing better CTAs and hooks +- Positioning products and services +- Funnel optimization +- Messaging strategy +- A/B testing ideas +- Channel selection +- Conversion optimization + +## Catchphrases +- "What's the CTA?" +- "What's the hook?" +- "Who is this for?" +- "Make it specific. Make it memorable." diff --git a/marketing-mode/SKILL.md b/marketing-mode/SKILL.md new file mode 100644 index 0000000..34a340c --- /dev/null +++ b/marketing-mode/SKILL.md @@ -0,0 +1,693 @@ +--- +name: marketing-mode +description: "Marketing Mode combines 23 comprehensive marketing skills covering strategy, psychology, content, SEO, conversion optimization, and paid growth. Use when users need marketing strategy, copywriting, SEO help, conversion optimization, paid advertising, or any marketing tactic." +metadata: + version: 1.0.0 + tags: ["marketing", "growth", "seo", "copywriting", "cro", "paid-ads", "strategy", "psychology", "launch", "pricing", "email", "social"] + clawdbot: + mode: + name: "Mark the Marketer" + role: "Growth & Marketing Strategist" + emoji: "πŸ“ˆ" + personality: | + Mark is a growth-obsessed marketing strategist who lives for the next conversion. He speaks in marketing frameworks, funnels, and metrics. He's constantly analyzing messaging, positioning, and channels for maximum impact. Mark doesn't just "post content" - he builds systems that convert. + requires: + bins: ["node"] + npm: true + install: + - id: "skill-install" + kind: "skill" + source: "clawdhub" + slug: "marketing-mode" + label: "Activate Marketing Mode" +--- + +# Marketing Mode - Complete Marketing Knowledge Base + +You are a marketing strategist with expertise across 23 comprehensive marketing disciplines. Your goal is to help users find the right strategies, tactics, and frameworks for their specific situation, stage, and resources. + +## Mode Activation + +When users need marketing help, activate this mode. Ask clarifying questions about their product, audience, stage, budget, and goals. Then recommend specific skills and tactics from this knowledge base. + +--- + +# PART 1: MARKETING STRATEGY & FRAMEWORKS + +## Marketing Ideas (140+ Proven Approaches) + +### Content & SEO +- Easy Keyword Ranking +- SEO Audit +- Glossary Marketing +- Programmatic SEO +- Content Repurposing +- Proprietary Data Content +- Internal Linking +- Content Refreshing +- Knowledge Base SEO +- Parasite SEO + +### Competitor & Comparison +- Competitor Comparison Pages +- Marketing Jiu-Jitsu +- Competitive Ad Research + +### Free Tools & Engineering +- Side Projects as Marketing +- Engineering as Marketing +- Importers as Marketing +- Quiz Marketing +- Calculator Marketing +- Chrome Extensions +- Microsites +- Scanners +- Public APIs + +### Paid Advertising +- Podcast Advertising +- Pre-targeting Ads +- Facebook Ads +- Instagram Ads +- Twitter/X Ads +- LinkedIn Ads +- Reddit Ads +- Quora Ads +- Google Ads +- YouTube Ads +- Cross-Platform Retargeting +- Click-to-Messenger Ads + +### Social Media & Community +- Community Marketing +- Quora Marketing +- Reddit Keyword Research +- Reddit Marketing +- LinkedIn Audience +- Instagram Audience +- X Audience +- Short Form Video +- Engagement Pods +- Comment Marketing + +### Email Marketing +- Mistake Email Marketing +- Reactivation Emails +- Founder Welcome Email +- Dynamic Email Capture +- Monthly Newsletters +- Inbox Placement +- Onboarding Emails +- Win-back Emails +- Trial Reactivation + +### Partnerships & Programs +- Affiliate Discovery Through Backlinks +- Influencer Whitelisting +- Reseller Programs +- Expert Networks +- Newsletter Swaps +- Article Quotes +- Pixel Sharing +- Shared Slack Channels +- Affiliate Program +- Integration Marketing +- Community Sponsorship + +### Events & Speaking +- Live Webinars +- Virtual Summits +- Roadshows +- Local Meetups +- Meetup Sponsorship +- Conference Speaking +- Conferences +- Conference Sponsorship + +### PR & Media +- Media Acquisitions as Marketing +- Press Coverage +- Fundraising PR +- Documentaries + +### Launches & Promotions +- Black Friday Promotions +- Product Hunt Launch +- Early-Access Referrals +- New Year Promotions +- Early Access Pricing +- Product Hunt Alternatives +- Twitter Giveaways +- Giveaways +- Vacation Giveaways +- Lifetime Deals + +### Product-Led Growth +- Powered By Marketing +- Free Migrations +- Contract Buyouts +- One-Click Registration +- In-App Upsells +- Newsletter Referrals +- Viral Loops +- Offboarding Flows +- Concierge Setup +- Onboarding Optimization + +### Unconventional & Creative +- Awards as Marketing +- Challenges as Marketing +- Reality TV Marketing +- Controversy as Marketing +- Moneyball Marketing +- Curation as Marketing +- Grants as Marketing +- Product Competitions +- Cameo Marketing +- OOH Advertising +- Marketing Stunts +- Guerrilla Marketing +- Humor Marketing + +### Platforms & Marketplaces +- Open Source as Marketing +- App Store Optimization +- App Marketplaces +- YouTube Reviews +- YouTube Channel +- Source Platforms +- Review Sites +- Live Audio +- International Expansion +- Price Localization + +### Developer & Technical +- Investor Marketing +- Certifications +- Support as Marketing +- Developer Relations + +### Audience-Specific +- Two-Sided Referrals +- Podcast Tours +- Customer Language + +--- + +## Launch Strategy (5-Phase Framework) + +### Phase 1: Internal (Pre-Launch) +- Use product internally first +- Find bugs in real use cases +- Build initial case studies +- Create launch content +- Set up analytics and tracking + +### Phase 2: Alpha (Private Beta) +- Invite existing customers and warm leads +- Get feedback and testimonials +- Refine positioning based on response +- Build waitlist + +### Phase 3: Beta (Public Preview) +- Broader access with invite codes +- Collect more testimonials +- Refine pricing and packaging +- Build SEO content + +### Phase 4: Early Access (Launch Prep) +- Public waitlist opening +- Special launch pricing +- Affiliate/partner outreach +- Press and analyst outreach + +### Phase 5: Full Launch +- General availability +- Full promotional push +- Customer success stories +- Ongoing optimization + +--- + +## Pricing Strategy + +### Research Methods +- Competitor pricing analysis +- Value-based pricing models +- Willingness-to-pay surveys +- A/B testing for optimization + +### Tier Structure +- Free tier (awareness) +- Pro tier (core value) +- Enterprise tier (scale + support) + +### Value Metrics +- Per-seat pricing +- Usage-based pricing +- Feature-based tiers +- Outcome-based pricing + +### Monetization Optimization +- Annual vs. monthly discounts +- Upgrade paths +- Churn prevention pricing +- Revenue recovery + +--- + +# PART 2: PSYCHOLOGY & MENTAL MODELS + +## Foundational Thinking Models + +### First Principles +Break problems down to basic truths. Don't copy competitorsβ€”ask "why" repeatedly to find root causes. + +**Marketing application**: Don't do content marketing because competitors do. Ask why, what problem it solves, if there's a better solution. + +### Jobs to Be Done (JTBD) +People "hire" products to get a job done. Focus on outcomes, not features. + +**Marketing application**: A drill buyer wants a hole, not a drill. Frame around the job accomplished. + +### Circle of Competence +Know what you're good at and stay within it. Double down on genuine expertise. + +**Marketing application**: Don't chase every channel. Focus on where you have real competitive advantage. + +### Inversion +Ask what would guarantee failure, then avoid those things. + +**Marketing application**: List everything that would make a campaign fail, then systematically prevent each. + +### Occam's Razor +Simpler explanations are usually correct. Avoid overcomplicating strategies. + +**Marketing application**: If conversions dropped, check obvious first (broken form, slow page) before complex attribution. + +### Pareto Principle (80/20) +80% of results come from 20% of efforts. Find and focus on the vital few. + +**Marketing application**: Find channels driving most results. Cut or reduce the rest. + +### Hick's Law +Decision time increases with options. More choices = more abandonment. + +**Marketing application**: One clear CTA beats three. Fewer form fields = higher conversion. + +### AIDA Funnel +Attention β†’ Interest β†’ Desire β†’ Action + +**Marketing application**: Structure pages to move through each stage. Capture attention before building desire. + +### Law of Diminishing Returns +After a point, additional investment yields progressively smaller gains. + +**Marketing application**: The 10th blog post won't have the same impact as the first. Diversify channels. + +### Commitment & Consistency +Once people commit to something, they want to stay consistent. + +**Marketing application**: Small commitments first (email signup) lead to larger ones (paid subscription). + +### Reciprocity Principle +Give first. People feel obligated to return favors. + +**Marketing application**: Free content, tools, and freemium models create reciprocal obligation. + +### Scarcity & Urgency +Limited availability increases perceived value. + +**Marketing application**: Limited-time offers, low-stock warnings. Only use when genuine. + +### Loss Aversion +Losses feel twice as painful as equivalent gains feel good. + +**Marketing application**: "Don't miss out" beats "You could gain." Frame in terms of what they'll lose. + +### Anchoring Effect +First number heavily influences subsequent judgments. + +**Marketing application**: Show higher price first (original, competitor, enterprise) to anchor expectations. + +### Paradox of Choice +Too many options overwhelm. Fewer choices lead to more decisions. + +**Marketing application**: Three pricing tiers. Recommend a single "best for most" option. + +### Endowment Effect +People value things more once they own them. + +**Marketing application**: Free trials, samples, freemium models let customers "own" the product. + +### IKEA Effect +People value things they put effort into creating. + +**Marketing application**: Let customers customize, configure, build. Their investment increases commitment. + +### Mere Exposure Effect +Familiarity breeds liking. Consistent presence builds preference. + +**Marketing application**: Repetition across channels creates comfort and trust. + +### Social Proof / Bandwagon Effect +People follow what others are doing. Popularity signals quality. + +**Marketing application**: Show customer counts, testimonials, "trending" indicators. + +### Prospect Theory / Loss Aversion +People avoid actions that might cause regret. + +**Marketing application**: Money-back guarantees, free trials reduce regret fear. Address concerns directly. + +### Zeigarnik Effect +Unfinished tasks occupy the mind. Open loops create tension. + +**Marketing application**: "You're 80% done" creates pull to finish. Incomplete profiles, abandoned carts. + +### Status-Quo Bias +People prefer current state. Change feels risky. + +**Marketing application**: Reduce friction. Make transition feel safe. "Import in one click." + +### Default Effect +People accept pre-selected options. Defaults are powerful. + +**Marketing application**: Pre-select the plan you want customers to choose. Opt-out beats opt-in. + +### Peak-End Rule +People judge experiences by the peak (best/worst) and end, not average. + +**Marketing application**: Design memorable peaks and strong endings. Thank you pages matter. + +--- + +# PART 3: SEO & CONTENT + +## SEO Audit Framework + +### Priority Order +1. **Crawlability & Indexation** - Can Google find and index pages? +2. **Technical Foundations** - Is the site fast and functional? +3. **On-Page Optimization** - Is content optimized? +4. **Content Quality** - Does it deserve to rank? +5. **Authority & Links** - Does it have credibility? + +### Technical SEO Checklist + +**Crawlability** +- Robots.txt not blocking important pages +- XML sitemap accessible and updated +- Site architecture within 3 clicks of homepage +- No orphan pages + +**Indexation** +- No accidental noindex on important pages +- Proper canonical tags (self-referencing) +- No redirect chains +- No soft 404s + +**Core Web Vitals** +- LCP < 2.5s +- INP < 200ms +- CLS < 0.1 +- Server response time optimized +- Images optimized + +**On-Page** +- Title tags optimized (60 chars, keyword placement) +- Meta descriptions compelling (155 chars) +- Header hierarchy (H1 β†’ H2 β†’ H3) +- Internal linking to priority pages + +**E-E-A-T** +- Author expertise demonstrated +- Clear sourcing and citations +- Regular content updates +- Accurate, comprehensive information + +--- + +## Programmatic SEO (12 Playbooks) + +1. **Location Pages** - City + keyword targeting +2. **Comparison Pages** - Product + alternative/competitor +3. **Integration Pages** - Tool + integration targets +4. **Use Case Pages** - Solution + use case +5. **Problem Pages** - Pain point + solution +6. **Industry Pages** - Industry + keyword targets +7. **Review/Alternatives Pages** - Competitor alternatives +8. **Calculator/Generator Pages** - Tools with keyword targets +9. **Template Pages** - Document templates for keywords +10. **Glossary Pages** - Industry terms explained +11. **Checklist Pages** - How-to guides as checklists +12. **Quiz/Assessment Pages** - Interactive tools + +--- + +## Schema Markup + +- Organization schema +- Product/Service schema +- FAQPage schema +- HowTo schema +- Review/BreadcrumbList schema +- LocalBusiness schema + +--- + +## Copywriting Frameworks + +### AIDA +Attention β†’ Interest β†’ Desire β†’ Action + +### PAS +Problem β†’ Agitation β†’ Solution + +### Before/After/Bridge +Current state β†’ Problem β†’ Your solution β†’ Transformation + +### ACCA +Awareness β†’ Comprehension β†’ Conviction β†’ Action + +### Hero's Journey +Customer as hero on a journey with your product as guide + +--- + +## Copy Editing (7 Sweeps) + +1. **Clarity Sweep** +2. **Voice Sweep** +3. **Proof Sweep** +4. **Impact Sweep** +5. **Emotion Sweep** +6. **Format Sweep** +7. **Authenticity Sweep** + +--- + +## Social Content Strategy + +### Hook Templates +- Question hooks +- Number hooks +- Story hooks +- Contrast hooks +- Controversy hooks + +### Platform Optimization +- LinkedIn: Professional, thought leadership +- X/Twitter: Bite-sized, threads +- Instagram: Visual + captions +- TikTok/Reels: Entertainment + education +- YouTube: Long-form + shorts + +--- + +# PART 4: CONVERSION OPTIMIZATION (CRO) + +## Page CRO Elements + +1. **Value Proposition** + - Clear headline (8-12 words) + - Subhead explaining transformation + - Visual proof (screenshot/video) + +2. **Trust Signals** + - Logos of customers/press + - Testimonials + - Security badges + - Social proof numbers + +3. **CTA Optimization** + - Action-oriented (not "Submit") + - Contrast with page + - Above fold placement + +4. **Friction Analysis** + - Remove unnecessary form fields + - Auto-fill where possible + - Clear error messages + +--- + +## Funnel Optimization + +### Signup Flow +- Minimize fields (email only first) +- Social auth options +- Progress indicators +- Clear value proposition + +### Form CRO +- Progressive profiling +- Inline validation +- Smart defaults +- Auto-save drafts + +### Onboarding +- Aha moment identification +- Progress tracking +- Feature discovery +- Milestone celebrations + +### A/B Test Setup +- Hypothesis framework +- Sample size calculations +- Statistical significance (95%+ confidence) +- Test one variable at a time + +--- + +# PART 5: PAID ADVERTISING & GROWTH + +## Channel Strategy + +### Google Ads +- Brand terms protection +- Competitor targeting +- Solution keywords +- Remarketing lists + +### Meta/Facebook Ads +- Detailed targeting +- Creative testing +- Lookalike audiences +- Retargeting + +### LinkedIn Ads +- Job titles/functions +- Company size targeting +- Industry filters +- B2B intent + +### Analytics & Tracking +- UTM parameters (consistent naming) +- GA4 events for goals +- GTM container setup +- Conversion tracking pixels + +--- + +## Referral Program Design + +### Viral Mechanics +- Two-sided rewards +- Milestone celebrations +- Fraud detection rules +- Nurture sequences for referred users + +--- + +## Free Tool Strategy + +### Tool Categories +- Calculators +- Analyzers +- Generators +- Checklists +- Templates + +### SEO Value +- Keyword targeting +- Backlink attraction +- Shareable results + +--- + +# PART 6: EMAIL MARKETING + +## Sequence Types + +1. **Welcome Series** - First 7 days +2. **Nurture Sequence** - Build interest over 2-3 weeks +3. **Onboarding Sequence** - Product education +4. **Win-Back/Reactivation** - Churned users +5. **Re-engagement** - Dormant subscribers + +--- + +# QUICK REFERENCE + +## Marketing Challenges β†’ Relevant Frameworks + +| Challenge | Start Here | +|-----------|------------| +| Low conversions | AIDA, Hick's Law, BJ Fogg | +| Pricing objections | Anchoring, Mental Accounting, Loss Aversion | +| SEO issues | Technical SEO audit, Programmatic SEO | +| Copy not converting | PAS, Copy editing sweeps, A/B tests | +| Email performance | Welcome series, Segmentation, Send time optimization | +| No traffic | SEO audit, Content strategy, Programmatic SEO | +| High churn | Onboarding CRO, Win-back sequences | +| Low engagement | Social proof, Reciprocity, Consistency | +| Unclear messaging | Value proposition, Positioning, Differentiation | + +--- + +## Questions to Ask (Marketing Discovery) + +**About Product & Audience** +- What's your product and who's the target customer? +- What's your current stage (pre-launch β†’ scale)? +- What are your main marketing goals? +- What's your budget and team size? + +**About Current State** +- What have you tried that worked or didn't? +- What are your competitors doing well? +- Where are you losing customers in the funnel? + +**About Goals** +- What metrics matter most (traffic, leads, revenue)? +- What's your timeline? +- What's your competitive advantage? + +--- + +## Related Skills + +- **marketing-ideas**: 140+ tactical marketing ideas +- **marketing-psychology**: 70+ mental models for persuasion +- **launch-strategy**: 5-phase launch framework +- **pricing-strategy**: Research and optimization methods +- **seo-audit**: Technical and on-page SEO diagnosis +- **programmatic-seo**: Building pages at scale +- **schema-markup**: Structured data implementation +- **competitor-alternatives**: Comparison page strategy +- **copywriting**: Framework-driven copy +- **copy-editing**: 7-sweep improvement process +- **social-content**: Platform-specific strategies +- **email-sequence**: Campaign types and templates +- **page-cro**: Landing page optimization +- **signup-flow-cro**: Form and signup optimization +- **form-cro**: Lead capture and conversion +- **onboarding-cro**: Activation and retention +- **paywall-cro**: Premium content strategy +- **popup-cro**: Trigger-based conversion +- **ab-test-setup**: Statistical rigor in testing +- **paid-ads**: Channel-specific strategies +- **analytics-tracking**: Measurement infrastructure +- **referral-program**: Viral loop design +- **free-tool-strategy**: Lead generation through tools diff --git a/marketing-mode/mode-prompt.md b/marketing-mode/mode-prompt.md new file mode 100644 index 0000000..5a392fd --- /dev/null +++ b/marketing-mode/mode-prompt.md @@ -0,0 +1,39 @@ +# Mark the Marketer - Mode Prompt + +You are Mark the Marketer, a growth-obsessed marketing strategist. + +## Your Core Identity +- You live for the next conversion, the better hook, the tighter positioning +- You think in funnels: Awareness β†’ Interest β†’ Desire β†’ Action +- You analyze everything through a marketing lens: "What's the CTA?", "Is this positioned right?", "Does this hook?" +- You use frameworks like AIDA (Attention, Interest, Desire, Action), PAS (Problem, Agitation, Solution), and the Hook Model +- You're energetic, data-driven, and always asking: "What's the metric that matters?" + +## Marketing Frameworks You Use +- **AIDA**: Attention β†’ Interest β†’ Desire β†’ Action +- **PAS**: Problem β†’ Agitation β†’ Solution +- **Hook Model**: Trigger β†’ Action β†’ Variable Reward β†’ Investment +- **Value Proposition Canvas**: Customer Jobs β†’ Pains β†’ Gains β†’ Value Prop +- **Positioning**: Who it's for, what it does, why it's different + +## How You Communicate +- Use marketing terminology naturally (CTAs, conversion, positioning, hook, etc.) +- Ask about metrics and results +- Suggest frameworks for solving problems +- Be energetic and growth-focused +- Challenge vague messaging: "What does it actually do for the customer?" + +## Your Catchphrases +- "What's the CTA?" +- "What's the hook?" +- "Who is this for?" +- "What's the one thing they should remember?" +- "Make it specific. Make it memorable." + +## Mode Activation +When users want marketing help, switch to this mode. Ask clarifying questions about: +- Target audience +- Desired action/conversion +- Current messaging/positioning +- Channels being used +- Metrics being tracked diff --git a/marketing-mode/skill.json b/marketing-mode/skill.json new file mode 100644 index 0000000..d667d06 --- /dev/null +++ b/marketing-mode/skill.json @@ -0,0 +1,51 @@ +{ + "name": "marketing-mode", + "description": "Marketing and growth strategies for founders. Focuses on messaging, positioning, funnel optimization, and growth tactics.", + "version": "1.0.0", + "tags": ["marketing", "growth", "founder", "positioning", "messaging", "funnel"], + "author": "Seth Rose", + "license": "MIT", + "repository": "https://github.com/TheSethRose/clawdbot-skills", + "documentation": "SKILL.md", + "keywords": [ + "marketing", + "growth", + "founder", + "positioning", + "messaging", + "funnel", + "conversion", + "cta", + "hooks" + ], + "engines": { + "node": ">=18.0.0" + }, + "install": { + "npm": "npm install -g @thesethrose/marketing-mode" + }, + "usage": { + "cli": "clawdhub install marketing-mode" + }, + "clawdbot": { + "requires": { + "node": true, + "npm": true + }, + "mode": { + "name": "Mark the Marketer", + "role": "Marketing Strategist", + "emoji": "πŸ“ˆ", + "personality": "Growth-obsessed marketing strategist focused on funnels, positioning, and conversion.", + "system_prompt_path": "mode-prompt.md" + }, + "install": [ + { + "id": "npm-pkg", + "kind": "npm", + "package": "@thesethrose/marketing-mode", + "label": "Install Marketing Mode (npm)" + } + ] + } +} diff --git a/skillshare/.skillshare-meta.json b/skillshare/.skillshare-meta.json index fc40520..cf52641 100644 --- a/skillshare/.skillshare-meta.json +++ b/skillshare/.skillshare-meta.json @@ -1,8 +1,8 @@ { "source": "github.com/runkids/skillshare/skills/skillshare", "type": "github-subdir", - "installed_at": "2026-01-29T15:54:54.355308942Z", + "installed_at": "2026-02-03T23:38:45.924722073Z", "repo_url": "https://github.com/runkids/skillshare.git", "subdir": "skills/skillshare", - "version": "0134ec0" + "version": "1bbfb66" } \ No newline at end of file diff --git a/skillshare/SKILL.md b/skillshare/SKILL.md index 01f29ae..5cb9347 100644 --- a/skillshare/SKILL.md +++ b/skillshare/SKILL.md @@ -1,108 +1,90 @@ --- name: skillshare -version: 0.6.4 -description: Syncs skills across AI CLI tools from a single source of truth. Use when asked to "sync skills", "pull skills", "show status", "list skills", "install skill", "initialize skillshare", or manage skill targets. +version: 0.8.2 +description: | + Syncs skills across AI CLI tools (Claude, Cursor, Windsurf, etc.) from a single source of truth. + Use when: "sync skills", "install skill", "search skills", "list skills", "show skill status", + "backup skills", "restore skills", "update skills", "new skill", "collect skills", + "push/pull skills", "add/remove target", "find a skill for X", "is there a skill that can...", + "how do I do X with skills", "skillshare init", "skillshare upgrade", "skill not syncing", + "diagnose skillshare", "doctor", or any skill/target management across AI tools. argument-hint: "[command] [target] [--dry-run]" --- # Skillshare CLI ``` -Source: ~/.config/skillshare/skills ← Edit here (single source of truth) - ↓ sync -Targets: ~/.claude/skills, ~/.cursor/skills, ... ← Symlinked from source +Source: ~/.config/skillshare/skills ← Single source of truth + ↓ sync (symlinks) +Targets: ~/.claude/skills, ~/.cursor/skills, ... ``` -## Quick Reference +## Quick Start ```bash -skillshare status # Always run first -skillshare sync # Push to all targets -skillshare sync --dry-run # Preview changes -skillshare pull claude # Import from target β†’ source -skillshare list # Show skills and tracked repos +skillshare status # Check state +skillshare sync --dry-run # Preview +skillshare sync # Execute ``` -## Command Patterns +## Commands -| Intent | Command | -|--------|---------| -| Sync skills | `skillshare sync` | -| Preview first | `skillshare sync --dry-run` then `sync` | -| Create new skill | `skillshare new ` then `sync` | -| Pull from target | `skillshare pull ` then `sync` | -| Install skill | `skillshare install ` then `sync` | -| Install from repo (browse) | `skillshare install owner/repo` (discovery mode) | -| Install team repo | `skillshare install --track` then `sync` | -| Update skill/repo | `skillshare update ` then `sync` | -| Update all tracked | `skillshare update --all` then `sync` | -| Remove skill | `skillshare uninstall ` then `sync` | -| List skills | `skillshare list` or `list --verbose` | -| Cross-machine push | `skillshare push -m "message"` | -| Cross-machine pull | `skillshare pull --remote` | -| Backup/restore | `skillshare backup --list`, `restore ` | -| Add custom target | `skillshare target add ` | -| Change sync mode | `skillshare target --mode merge\|symlink` | -| Upgrade CLI/skill | `skillshare upgrade` | -| Diagnose issues | `skillshare doctor` | +| Category | Commands | +|----------|----------| +| **Inspect** | `status`, `diff`, `list`, `doctor` | +| **Sync** | `sync`, `collect`, `push`, `pull` | +| **Skills** | `new`, `install`, `uninstall`, `update`, `search` | +| **Targets** | `target add/remove/list`, `backup`, `restore` | +| **Upgrade** | `upgrade [--cli\|--skill]` | -## Init (Non-Interactive) +**Workflow:** Most commands require `sync` afterward to distribute changes. -**CRITICAL:** Use flags β€” AI cannot respond to CLI prompts. +## AI Usage Notes -**Source path:** Always use default `~/.config/skillshare/skills`. Only use `--source` if user explicitly requests a different location. +### Non-Interactive Mode + +AI cannot respond to CLI prompts. Always use flags: -**Step 1:** Check existing skills ```bash +# Init - check existing skills first ls ~/.claude/skills ~/.cursor/skills 2>/dev/null | head -10 + +# Then run with appropriate flags +skillshare init --copy-from claude --all-targets --git # If skills exist +skillshare init --no-copy --all-targets --git # Fresh start + +# Add new agents later +skillshare init --discover --select "windsurf,kilocode" ``` -**Step 2:** Run init based on findings +### Safety -| Found | Command | -|-------|---------| -| Skills in one target | `skillshare init --copy-from --all-targets --git` | -| Skills in multiple | Ask user which to import | -| No existing skills | `skillshare init --no-copy --all-targets --git` | +**NEVER** `rm -rf` symlinked skills β€” deletes source. Always use: +- `skillshare uninstall ` to remove skills +- `skillshare target remove ` to unlink targets -**Step 3:** `skillshare status` +### Finding Skills -**Adding new agents later (AI must use --select):** -```bash -skillshare init --discover --select "windsurf,kilocode" # Non-interactive (AI use this) -# skillshare init --discover # Interactive only (NOT for AI) -``` - -See [init.md](references/init.md) for all flags. - -## Team Edition +When users ask "how do I do X" or "find a skill for...": ```bash -skillshare install github.com/team/skills --track # Install as tracked repo -skillshare update _team-skills # Update later +skillshare search # Interactive install +skillshare search --list # List only +skillshare search --json # JSON output ``` -Tracked repos: `_` prefix, nested paths use `__` (e.g., `_team__frontend__ui`). +**Query examples:** `react performance`, `pr review`, `commit`, `changelog` -**Naming convention:** Use `{team}:{name}` in SKILL.md to avoid collisions. - -## Safety - -- **NEVER** `rm -rf` on symlinked skills β€” deletes source -- Use `skillshare uninstall ` to safely remove - -## Zero-Install - -```bash -curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/skills/skillshare/scripts/run.sh | sh -s -- status -``` +**No results?** Try different keywords, or offer to help directly. ## References -- [init.md](references/init.md) - Init flags -- [sync.md](references/sync.md) - Sync, pull, push -- [install.md](references/install.md) - Install, update, uninstall -- [status.md](references/status.md) - Status, diff, list, doctor -- [targets.md](references/targets.md) - Target management -- [backup.md](references/backup.md) - Backup, restore -- [TROUBLESHOOTING.md](references/TROUBLESHOOTING.md) - Recovery +| Topic | File | +|-------|------| +| Init flags | [init.md](references/init.md) | +| Sync/collect/push/pull | [sync.md](references/sync.md) | +| Install/update/new | [install.md](references/install.md) | +| Status/diff/list/search | [status.md](references/status.md) | +| Target management | [targets.md](references/targets.md) | +| Backup/restore | [backup.md](references/backup.md) | +| Troubleshooting | [TROUBLESHOOTING.md](references/TROUBLESHOOTING.md) | diff --git a/skillshare/references/TROUBLESHOOTING.md b/skillshare/references/TROUBLESHOOTING.md index 620fce4..d28a5d1 100644 --- a/skillshare/references/TROUBLESHOOTING.md +++ b/skillshare/references/TROUBLESHOOTING.md @@ -1,143 +1,68 @@ -# Skillshare Troubleshooting +# Troubleshooting -Common issues, solutions, and tips for AI assistants. +## Quick Fixes -## Common Issues +| Problem | Solution | +|---------|----------| +| "config not found" | `skillshare init` | +| Target shows differences | `skillshare sync` | +| Lost source files | `cd ~/.config/skillshare/skills && git checkout -- .` | +| Skill not appearing | `skillshare sync` after install | +| Git push fails | Check remote: `git -C ~/.config/skillshare/skills remote -v` | -| Problem | Diagnosis | Solution | -|---------|-----------|----------| -| "config not found" | Config missing | Run `skillshare init` | -| Target shows differences | Files out of sync | Run `skillshare sync` | -| Lost source files | Deleted via symlink | `cd ~/.config/skillshare/skills && git checkout -- /` | -| Target has local skills | Need to preserve | Ensure `merge` mode, then `skillshare pull` before sync | -| Skill not appearing | Not synced yet | Run `skillshare sync` after install | -| Can't find installed skills | Wrong directory | Check `skillshare status` for source path | -| "permission denied" | Symlink issues | Check file ownership and permissions | -| Git remote not set | Push fails | Run `git remote add origin ` in source | - -## Recovery Workflow - -When something goes wrong: +## Diagnostic Commands ```bash -skillshare doctor # 1. Diagnose issues -skillshare backup # 2. Create safety backup -skillshare sync --dry-run # 3. Preview fix -skillshare sync # 4. Apply fix +skillshare doctor # Check environment +skillshare status # Overview +skillshare diff # Show differences +ls -la ~/.claude/skills # Check symlinks +``` + +## Recovery + +```bash +skillshare backup # Safety backup first +skillshare sync --dry-run # Preview changes +skillshare sync # Apply fix ``` ## Git Recovery -If source files were accidentally deleted: - ```bash cd ~/.config/skillshare/skills -git status # See what's missing -git checkout -- / # Restore specific skill -git checkout -- . # Restore all deleted files +git status # Check state +git checkout -- / # Restore specific skill +git checkout -- . # Restore all skills ``` -If you need to restore from backup: +## AI Assistant Notes + +### Symlink Safety + +- **merge mode** (default): Per-skill symlinks. Edit anywhere = edit source. +- **symlink mode**: Entire directory symlinked. + +**Safe commands:** `skillshare uninstall`, `skillshare target remove` + +**DANGEROUS:** `rm -rf` on symlinked skills deletes source! + +### Non-Interactive Usage + +AI cannot respond to CLI prompts. Always use flags: ```bash -skillshare backup --list # List available backups -skillshare restore claude --from +# Good (non-interactive) +skillshare init --copy-from claude --all-targets --git +skillshare uninstall my-skill --force + +# Bad (requires user input) +skillshare init +skillshare uninstall my-skill ``` -## Tips for AI Assistants - -### Symlink Behavior - -Understanding symlinks is critical: - -1. **merge mode** (default): Each skill in target is a symlink to source - - Editing `~/.claude/skills/my-skill/SKILL.md` edits the source - - Changes are immediate and affect all targets - - Safe: `skillshare uninstall my-skill` - - **DANGEROUS**: `rm -rf ~/.claude/skills/my-skill` - deletes source! - -2. **symlink mode**: Entire target directory is a symlink - - `~/.claude/skills` β†’ `~/.config/skillshare/skills` - - All targets are identical - - No local skills possible - ### When to Use --dry-run -Always use `--dry-run` in these situations: - -- User is cautious or new to skillshare -- Before `sync` on first use -- Before `pull --all` to see what will be imported +- First-time operations +- Before `sync`, `collect --all`, `restore` - Before `install` from unknown sources -- Before `restore` to preview what will change -- Before `target remove` to understand impact - -### Safe vs Dangerous Operations - -**Safe operations:** -```bash -skillshare target remove # Removes symlinks, keeps source -skillshare uninstall # Removes skill properly -skillshare sync # Creates/updates symlinks -``` - -**NEVER do this:** -```bash -rm -rf ~/.claude/skills/my-skill # Deletes source via symlink! -rm -rf ~/.claude/skills # May delete entire source! -``` - -### Creating New Skills - -Guide users to create skills in source: - -1. Create directory: `~/.config/skillshare/skills//` -2. Create `SKILL.md` with required frontmatter: - ```yaml - --- - name: skill-name - description: What this skill does - --- - ``` -3. Run `skillshare sync` to distribute - -### Git Workflow Reminders - -After any skill changes, remind user to push: - -```bash -skillshare push # Simple: commit + push -skillshare push -m "Add new skill" # With custom message -``` - -### Handling Init Prompts - -AI cannot respond to CLI prompts. When user asks to initialize: - -1. Ask clarifying questions in chat -2. Build the command with appropriate flags -3. Run non-interactively - -Example conversation: -- AI: "Do you have existing skills to copy from Claude or another tool?" -- User: "Yes, from Claude" -- AI: "Which CLI tools should I set up as targets?" -- User: "Claude and Cursor" -- AI: "Should I initialize git for version control?" -- User: "Yes" -- AI runs: `skillshare init --copy-from claude --targets "claude,cursor" --git` - -### Debugging Sync Issues - -If sync seems stuck or wrong: - -```bash -skillshare status # Check current state -skillshare diff # See actual differences -ls -la ~/.claude/skills # Check symlink targets -``` - -Look for: -- Broken symlinks (pointing to non-existent files) -- Regular files instead of symlinks -- Wrong symlink targets diff --git a/skillshare/references/backup.md b/skillshare/references/backup.md index f14250d..8b0af1d 100644 --- a/skillshare/references/backup.md +++ b/skillshare/references/backup.md @@ -1,23 +1,29 @@ -# Backup & Restore Commands +# Backup & Restore ## backup -Creates backup of target skills. +Create backups of target skill directories. ```bash -skillshare backup # Backup all targets -skillshare backup claude # Backup specific target -skillshare backup --list # List available backups +skillshare backup # All targets +skillshare backup claude # Specific target +skillshare backup --list # List existing backups skillshare backup --cleanup # Remove old backups ``` -Backups stored in: `~/.config/skillshare/backups//` +**Location:** `~/.config/skillshare/backups//` ## restore -Restores skills from backup. +Restore target from backup. ```bash -skillshare restore claude # From latest backup -skillshare restore claude --from 2026-01-14_21-22-18 # From specific backup +skillshare restore claude # Latest backup +skillshare restore claude --from 2026-01-14_21-22 # Specific backup ``` + +## Best Practices + +- Run `backup` before major changes +- Use `--dry-run` with restore to preview +- Keep backups with `--cleanup` to save disk space diff --git a/skillshare/references/init.md b/skillshare/references/init.md index b9e9283..9e231ac 100644 --- a/skillshare/references/init.md +++ b/skillshare/references/init.md @@ -1,71 +1,44 @@ # Init Command -Initializes skillshare configuration. +Initialize skillshare configuration. -## Key Concept +**Source:** Always `~/.config/skillshare/skills` (use `--source` only if user explicitly requests). -**Source is always `~/.config/skillshare/skills`** β€” never a CLI directory like `.claude/skills`. - -- `--copy-from claude` = import skills FROM claude INTO source -- `--copy-from` does NOT change where source is located - -## Copy Source Flags (mutually exclusive) +## Flags | Flag | Description | |------|-------------| -| `--copy-from ` | Copy skills from target name or directory path | +| `--copy-from ` | Import skills from target/path | | `--no-copy` | Start with empty source | - -## Target Flags (mutually exclusive) - -| Flag | Description | -|------|-------------| -| `--targets ` | Comma-separated targets: `"claude,cursor,codex"` | -| `--all-targets` | Add all detected CLI targets | +| `--targets "claude,cursor"` | Specific targets | +| `--all-targets` | All detected targets | | `--no-targets` | Skip target setup | +| `--git` | Initialize git repo | +| `--no-git` | Skip git init | +| `--discover` | Discover new AI tools (interactive) | +| `--discover --select "a,b"` | Non-interactive discovery | +| `--source ` | Custom source path | +| `--remote ` | Set git remote | +| `--dry-run` | Preview changes | -## Git Flags (mutually exclusive) - -| Flag | Description | -|------|-------------| -| `--git` | Initialize git in source (recommended) | -| `--no-git` | Skip git initialization | - -## Discover Flags (for adding new agents to existing config) - -| Flag | Description | -|------|-------------| -| `--discover` | Detect and add new agents to existing config (interactive) | -| `--select ` | Comma-separated agents to add (non-interactive, requires `--discover`) | - -## Other Flags - -| Flag | Description | -|------|-------------| -| `--source ` | Custom source directory (**only if user explicitly requests**) | -| `--remote ` | Set git remote (implies `--git`) | -| `--dry-run` | Preview without making changes | - -**AI Note:** Never use `--source` unless the user explicitly asks to change the source location. - -## Examples +## AI Usage (Non-Interactive) ```bash -# Fresh start with all targets and git +# Step 1: Check for existing skills +ls ~/.claude/skills ~/.cursor/skills 2>/dev/null | head -10 + +# Step 2a: Fresh start skillshare init --no-copy --all-targets --git -# Copy from Claude, specific targets -skillshare init --copy-from claude --targets "claude,cursor" --git +# Step 2b: Import existing skills +skillshare init --copy-from claude --all-targets --git -# Minimal setup -skillshare init --no-copy --no-targets --no-git - -# Custom source with remote -skillshare init --source ~/my-skills --remote git@github.com:user/skills.git - -# Add new agents to existing config (non-interactive) -skillshare init --discover --select "windsurf,kilocode" - -# Add new agents (interactive) -skillshare init --discover +# Step 3: Verify +skillshare status +``` + +## Adding New Targets Later + +```bash +skillshare init --discover --select "windsurf,kilocode" ``` diff --git a/skillshare/references/install.md b/skillshare/references/install.md index 380317b..35e9767 100644 --- a/skillshare/references/install.md +++ b/skillshare/references/install.md @@ -1,62 +1,87 @@ -# Install, Update & Uninstall +# Install, Update, Uninstall & New ## install -Adds a skill from various sources. +Install skills from local path or git repository. + +### Source Formats ```bash -# GitHub shorthand (auto-expands to github.com/...) -skillshare install owner/repo # Discovery mode -skillshare install owner/repo/path/to/skill # Direct path +# GitHub shorthand +user/repo # Browse repo for skills +user/repo/path/to/skill # Direct path # Full URLs -skillshare install github.com/user/repo # Discovery mode -skillshare install github.com/user/repo/skill # Direct path -skillshare install git@github.com:user/repo.git # SSH +github.com/user/repo # Discovers skills in repo +github.com/user/repo/path # Direct subdirectory +https://github.com/... # HTTPS URL +git@github.com:... # SSH URL # Local -skillshare install ~/Downloads/my-skill - -# Team repo (preserves .git for updates) -skillshare install github.com/team/skills --track +~/path/to/skill # Local directory ``` -**Flags:** +### Examples + +```bash +skillshare install anthropics/skills # Browse official skills +skillshare install anthropics/skills/skills/pdf # Direct install +skillshare install ~/Downloads/my-skill # Local +skillshare install github.com/team/repo --track # Team repo +``` + +### Flags | Flag | Description | |------|-------------| -| `--name ` | Custom skill name | +| `--name ` | Override skill name | | `--force, -f` | Overwrite existing | -| `--update, -u` | Update existing (git pull or reinstall) | -| `--track, -t` | Install as tracked repo (Team Edition) | -| `--dry-run, -n` | Preview without installing | +| `--update, -u` | Update if exists | +| `--track, -t` | Track for updates (preserves .git) | +| `--dry-run, -n` | Preview | -After install: `skillshare sync` +**Tracked repos:** Prefixed with `_`, nested with `__` (e.g., `_team__frontend__ui`). + +**After install:** `skillshare sync` ## update -Updates skills or tracked repos. +Update installed skills or tracked repositories. + +- **Tracked repos (`_repo-name`):** Runs `git pull` +- **Regular skills:** Reinstalls from stored source metadata ```bash skillshare update my-skill # Update from stored source -skillshare update _team-repo # Git pull tracked repo -skillshare update --all # Update all tracked repos -skillshare update _repo --force # Discard local changes and update +skillshare update _team-skills # Git pull tracked repo +skillshare update team-skills # _ prefix is optional +skillshare update --all # All tracked repos + skills +skillshare update --all -n # Preview updates +skillshare update _repo --force # Discard local changes ``` -Safety: Repos with uncommitted changes are blocked by default. -Use `--force` to discard local changes and pull latest. +**Safety:** Tracked repos with uncommitted changes are skipped. Use `--force` to override. -After update: `skillshare sync` +**After update:** `skillshare sync` ## uninstall -Removes a skill from source. +Remove a skill from source. ```bash skillshare uninstall my-skill # With confirmation skillshare uninstall my-skill --force # Skip confirmation -skillshare uninstall my-skill --dry-run ``` -After uninstall: `skillshare sync` +**After uninstall:** `skillshare sync` + +## new + +Create a new skill template. + +```bash +skillshare new # Create SKILL.md template +skillshare new --dry-run # Preview +``` + +**After create:** Edit SKILL.md β†’ `skillshare sync` diff --git a/skillshare/references/status.md b/skillshare/references/status.md index a1a5e07..bff11d5 100644 --- a/skillshare/references/status.md +++ b/skillshare/references/status.md @@ -2,28 +2,15 @@ ## status -Shows source location, targets, and sync state. +Overview of source, targets, and sync state. ```bash skillshare status ``` -**Expected output:** -``` -Source: ~/.config/skillshare/skills (4 skills) -Targets: - claude βœ“ synced ~/.claude/skills - codex βœ“ synced ~/.codex/skills - cursor ⚠ 1 diff ~/.cursor/skills - -Version: - βœ“ CLI: 0.6.4 - βœ“ Skill: 0.6.4 (up to date) -``` - ## diff -Shows differences between source and targets. +Show differences between source and targets. ```bash skillshare diff # All targets @@ -32,16 +19,35 @@ skillshare diff claude # Specific target ## list -Lists installed skills. +List installed skills. ```bash skillshare list # Basic list -skillshare list --verbose # With source and install info +skillshare list --verbose # With source info ``` +## search + +Search GitHub for skills (repos containing SKILL.md). + +```bash +skillshare search # Interactive (select to install) +skillshare search --list # List only +skillshare search --json # JSON output +skillshare search -n 10 # Limit results (default: 20) +``` + +**Requires:** GitHub auth (`gh` CLI or `GITHUB_TOKEN` env var). + +**Query examples:** +- `react performance` - Performance optimization +- `pr review` - Code review skills +- `commit` - Git commit helpers +- `changelog` - Changelog generation + ## doctor -Checks configuration health and diagnoses issues. +Diagnose configuration and environment issues. ```bash skillshare doctor @@ -49,7 +55,7 @@ skillshare doctor ## upgrade -Upgrades CLI binary and/or built-in skillshare skill. +Upgrade CLI binary and/or built-in skillshare skill. ```bash skillshare upgrade # Both CLI + skill @@ -59,4 +65,4 @@ skillshare upgrade --force # Skip confirmation skillshare upgrade --dry-run # Preview ``` -After upgrading skill: `skillshare sync` +**After upgrading skill:** `skillshare sync` diff --git a/skillshare/references/sync.md b/skillshare/references/sync.md index c8c6f22..f926b5a 100644 --- a/skillshare/references/sync.md +++ b/skillshare/references/sync.md @@ -1,41 +1,55 @@ -# Sync, Pull & Push Commands +# Sync, Collect, Push & Pull + +| Command | Direction | Description | +|---------|-----------|-------------| +| `sync` | Source β†’ Targets | Distribute skills to all targets | +| `collect` | Targets β†’ Source | Import skills from target(s) | +| `push` | Source β†’ Remote | Git commit and push | +| `pull` | Remote β†’ Source β†’ Targets | Git pull and sync | ## sync -Pushes skills from source to all targets. +Distribute skills from source to all targets via symlinks. ```bash -skillshare sync # Execute sync -skillshare sync --dry-run # Preview only +skillshare sync # Execute +skillshare sync --dry-run # Preview +skillshare sync --force # Override conflicts ``` -## pull +## collect -Brings skills from target(s) to source. +Import skills from target(s) to source. ```bash -skillshare pull claude # Pull from specific target -skillshare pull --all # Pull from all targets -skillshare pull --remote # Pull from git remote + sync all +skillshare collect claude # From specific target +skillshare collect --all # From all targets +skillshare collect --dry-run # Preview ``` ## push -Commits and pushes source to git remote. +Git commit and push source to remote. ```bash -skillshare push # Default commit message -skillshare push -m "message" # Custom commit message -skillshare push --dry-run # Preview only +skillshare push # Default message +skillshare push -m "message" # Custom message +skillshare push --dry-run # Preview ``` -## Workflows +## pull -**Local workflow:** -1. Create skill in any target (e.g., `~/.claude/skills/my-skill/`) -2. `skillshare pull claude` - bring to source -3. `skillshare sync` - distribute to all targets +Git pull from remote and sync to all targets. -**Cross-machine workflow:** -1. Machine A: `skillshare push` - commit and push to remote -2. Machine B: `skillshare pull --remote` - pull from remote + sync +```bash +skillshare pull # Pull + sync +skillshare pull --dry-run # Preview +``` + +## Common Workflows + +**Local editing:** Edit skill anywhere β†’ `sync` (symlinks update source automatically) + +**Import local changes:** `collect ` β†’ `sync` + +**Cross-machine sync:** Machine A: `push` β†’ Machine B: `pull` diff --git a/skillshare/references/targets.md b/skillshare/references/targets.md index 661ea83..f757edc 100644 --- a/skillshare/references/targets.md +++ b/skillshare/references/targets.md @@ -1,33 +1,30 @@ # Target Management -## target +Manage AI CLI tool targets (Claude, Cursor, Windsurf, etc.). -Manages sync targets. +## Commands ```bash skillshare target list # List all targets skillshare target claude # Show target info skillshare target add myapp ~/.myapp/skills # Add custom target -skillshare target remove myapp # Remove target +skillshare target remove myapp # Remove target (safe) ``` ## Sync Modes ```bash -skillshare target claude --mode merge # Individual skill symlinks (default) -skillshare target claude --mode symlink # Entire directory symlinked +skillshare target claude --mode merge # Per-skill symlinks (default) +skillshare target claude --mode symlink # Entire dir symlinked ``` -**Mode comparison:** +| Mode | Description | Local Skills | +|------|-------------|--------------| +| `merge` | Individual symlinks per skill | Preserved | +| `symlink` | Single symlink for entire dir | Not possible | -| Mode | Behavior | Local Skills | -|------|----------|--------------| -| `merge` | Creates individual symlinks for each skill | Preserved | -| `symlink` | Entire target directory is a symlink | Not possible | +## Safety -## Safe Target Removal +**Always use** `target remove` to unlink targets. -```bash -skillshare target remove # Safe: only removes link -# NOT: rm -rf ~/.target/skills # Dangerous: may delete source -``` +**NEVER** `rm -rf` on symlinked targets β€” this deletes the source! diff --git a/skillshare/scripts/run.sh b/skillshare/scripts/run.sh index dc918e8..e0c8e58 100755 --- a/skillshare/scripts/run.sh +++ b/skillshare/scripts/run.sh @@ -29,7 +29,7 @@ detect_os() { case "$OS" in darwin) OS="darwin" ;; linux) OS="linux" ;; - mingw*|msys*|cygwin*) error "Windows is not supported via this script. Please download from GitHub releases." ;; + mingw*|msys*|cygwin*) error "Use PowerShell: irm https://raw.githubusercontent.com/runkids/skillshare/main/install.ps1 | iex" ;; *) error "Unsupported OS: $OS" ;; esac } diff --git a/tavily/.clawdhub/origin.json b/tavily/.clawdhub/origin.json new file mode 100644 index 0000000..9feb4be --- /dev/null +++ b/tavily/.clawdhub/origin.json @@ -0,0 +1,7 @@ +{ + "version": 1, + "registry": "https://clawhub.ai", + "slug": "tavily", + "installedVersion": "1.0.0", + "installedAt": 1769908674515 +} diff --git a/tavily/SKILL.md b/tavily/SKILL.md new file mode 100644 index 0000000..a07cd60 --- /dev/null +++ b/tavily/SKILL.md @@ -0,0 +1,414 @@ +--- +name: tavily +description: AI-optimized web search using Tavily Search API. Use when you need comprehensive web research, current events lookup, domain-specific search, or AI-generated answer summaries. Tavily is optimized for LLM consumption with clean structured results, answer generation, and raw content extraction. Best for research tasks, news queries, fact-checking, and gathering authoritative sources. +--- + +# Tavily AI Search + +## Overview + +Tavily is a search engine specifically optimized for Large Language Models and AI applications. Unlike traditional search APIs, Tavily provides AI-ready results with optional answer generation, clean content extraction, and domain filtering capabilities. + +**Key capabilities:** +- AI-generated answer summaries from search results +- Clean, structured results optimized for LLM processing +- Fast (`basic`) and comprehensive (`advanced`) search modes +- Domain filtering (include/exclude specific sources) +- News-focused search for current events +- Image search with relevant visual content +- Raw content extraction for deeper analysis + +## Architecture + +```mermaid +graph TB + A[User Query] --> B{Search Mode} + B -->|basic| C[Fast Search
1-2s response] + B -->|advanced| D[Comprehensive Search
5-10s response] + + C --> E[Tavily API] + D --> E + + E --> F{Topic Filter} + F -->|general| G[Broad Web Search] + F -->|news| H[News Sources
Last 7 days] + + G --> I[Domain Filtering] + H --> I + + I --> J{Include Domains?} + J -->|yes| K[Filter to Specific Domains] + J -->|no| L{Exclude Domains?} + K --> M[Search Results] + L -->|yes| N[Remove Unwanted Domains] + L -->|no| M + N --> M + + M --> O{Response Options} + O --> P[AI Answer
Summary] + O --> Q[Structured Results
Title, URL, Content, Score] + O --> R[Images
if requested] + O --> S[Raw HTML Content
if requested] + + P --> T[Return to Agent] + Q --> T + R --> T + S --> T + + style E fill:#4A90E2 + style P fill:#7ED321 + style Q fill:#7ED321 + style R fill:#F5A623 + style S fill:#F5A623 +``` + +## Quick Start + +### Basic Search + +```bash +# Simple query with AI answer +scripts/tavily_search.py "What is quantum computing?" + +# Multiple results +scripts/tavily_search.py "Python best practices" --max-results 10 +``` + +### Advanced Search + +```bash +# Comprehensive research mode +scripts/tavily_search.py "Climate change solutions" --depth advanced + +# News-focused search +scripts/tavily_search.py "AI developments 2026" --topic news +``` + +### Domain Filtering + +```bash +# Search only trusted domains +scripts/tavily_search.py "Python tutorials" \ + --include-domains python.org docs.python.org realpython.com + +# Exclude low-quality sources +scripts/tavily_search.py "How to code" \ + --exclude-domains w3schools.com geeksforgeeks.org +``` + +### With Images + +```bash +# Include relevant images +scripts/tavily_search.py "Eiffel Tower architecture" --images +``` + +## Search Modes + +### Basic vs Advanced + +| Mode | Speed | Coverage | Use Case | +|------|-------|----------|----------| +| **basic** | 1-2s | Good | Quick facts, simple queries | +| **advanced** | 5-10s | Excellent | Research, complex topics, comprehensive analysis | + +**Decision tree:** +1. Need a quick fact or definition? β†’ Use `basic` +2. Researching a complex topic? β†’ Use `advanced` +3. Need multiple perspectives? β†’ Use `advanced` +4. Time-sensitive query? β†’ Use `basic` + +### General vs News + +| Topic | Time Range | Sources | Use Case | +|-------|------------|---------|----------| +| **general** | All time | Broad web | Evergreen content, tutorials, documentation | +| **news** | Last 7 days | News sites | Current events, recent developments, breaking news | + +**Decision tree:** +1. Query contains "latest", "recent", "current", "today"? β†’ Use `news` +2. Looking for historical or evergreen content? β†’ Use `general` +3. Need up-to-date information? β†’ Use `news` + +## API Key Setup + +### Option 1: Clawdbot Config (Recommended) + +Add to your Clawdbot config: + +```json +{ + "skills": { + "entries": { + "tavily": { + "enabled": true, + "apiKey": "tvly-YOUR_API_KEY_HERE" + } + } + } +} +``` + +Access in scripts via Clawdbot's config system. + +### Option 2: Environment Variable + +```bash +export TAVILY_API_KEY="tvly-YOUR_API_KEY_HERE" +``` + +Add to `~/.clawdbot/.env` or your shell profile. + +### Getting an API Key + +1. Visit https://tavily.com +2. Sign up for an account +3. Navigate to your dashboard +4. Generate an API key (starts with `tvly-`) +5. Note your plan's rate limits and credit allocation + +## Common Use Cases + +### 1. Research & Fact-Finding + +```bash +# Comprehensive research with answer +scripts/tavily_search.py "Explain quantum entanglement" --depth advanced + +# Multiple authoritative sources +scripts/tavily_search.py "Best practices for REST API design" \ + --max-results 10 \ + --include-domains github.com microsoft.com google.com +``` + +### 2. Current Events + +```bash +# Latest news +scripts/tavily_search.py "AI policy updates" --topic news + +# Recent developments in a field +scripts/tavily_search.py "quantum computing breakthroughs" \ + --topic news \ + --depth advanced +``` + +### 3. Domain-Specific Research + +```bash +# Academic sources only +scripts/tavily_search.py "machine learning algorithms" \ + --include-domains arxiv.org scholar.google.com ieee.org + +# Technical documentation +scripts/tavily_search.py "React hooks guide" \ + --include-domains react.dev +``` + +### 4. Visual Research + +```bash +# Gather visual references +scripts/tavily_search.py "modern web design trends" \ + --images \ + --max-results 10 +``` + +### 5. Content Extraction + +```bash +# Get raw HTML content for deeper analysis +scripts/tavily_search.py "Python async/await" \ + --raw-content \ + --max-results 5 +``` + +## Response Handling + +### AI Answer + +The AI-generated answer provides a concise summary synthesized from search results: + +```python +{ + "answer": "Quantum computing is a type of computing that uses quantum-mechanical phenomena..." +} +``` + +**Use when:** +- Need a quick summary +- Want synthesized information from multiple sources +- Looking for a direct answer to a question + +**Skip when** (`--no-answer`): +- Only need source URLs +- Want to form your own synthesis +- Conserving API credits + +### Structured Results + +Each result includes: +- `title`: Page title +- `url`: Source URL +- `content`: Extracted text snippet +- `score`: Relevance score (0-1) +- `raw_content`: Full HTML (if `--raw-content` enabled) + +### Images + +When `--images` is enabled, returns URLs of relevant images found during search. + +## Best Practices + +### 1. Choose the Right Search Depth + +- Start with `basic` for most queries (faster, cheaper) +- Escalate to `advanced` only when: + - Initial results are insufficient + - Topic is complex or nuanced + - Need comprehensive coverage + +### 2. Use Domain Filtering Strategically + +**Include domains for:** +- Academic research (`.edu` domains) +- Official documentation (official project sites) +- Trusted news sources +- Known authoritative sources + +**Exclude domains for:** +- Known low-quality content farms +- Irrelevant content types (Pinterest for non-visual queries) +- Sites with paywalls or access restrictions + +### 3. Optimize for Cost + +- Use `basic` depth as default +- Limit `max_results` to what you'll actually use +- Disable `include_raw_content` unless needed +- Cache results locally for repeated queries + +### 4. Handle Errors Gracefully + +The script provides helpful error messages: + +```bash +# Missing API key +Error: Tavily API key required +Setup: Set TAVILY_API_KEY environment variable or pass --api-key + +# Package not installed +Error: tavily-python package not installed +To install: pip install tavily-python +``` + +## Integration Patterns + +### Programmatic Usage + +```python +from tavily_search import search + +result = search( + query="What is machine learning?", + api_key="tvly-...", + search_depth="advanced", + max_results=10 +) + +if result.get("success"): + print(result["answer"]) + for item in result["results"]: + print(f"{item['title']}: {item['url']}") +``` + +### JSON Output for Parsing + +```bash +scripts/tavily_search.py "Python tutorials" --json > results.json +``` + +### Chaining with Other Tools + +```bash +# Search and extract content +scripts/tavily_search.py "React documentation" --json | \ + jq -r '.results[].url' | \ + xargs -I {} curl -s {} +``` + +## Comparison with Other Search APIs + +**vs Brave Search:** +- βœ… AI answer generation +- βœ… Raw content extraction +- βœ… Better domain filtering +- ❌ Slower than Brave +- ❌ Costs credits + +**vs Perplexity:** +- βœ… More control over sources +- βœ… Raw content available +- βœ… Dedicated news mode +- β‰ˆ Similar answer quality +- β‰ˆ Similar speed + +**vs Google Custom Search:** +- βœ… LLM-optimized results +- βœ… Answer generation +- βœ… Simpler API +- ❌ Smaller index +- β‰ˆ Similar cost structure + +## Troubleshooting + +### Script Won't Run + +```bash +# Make executable +chmod +x scripts/tavily_search.py + +# Check Python version (requires 3.6+) +python3 --version + +# Install dependencies +pip install tavily-python +``` + +### API Key Issues + +```bash +# Verify API key format (should start with tvly-) +echo $TAVILY_API_KEY + +# Test with explicit key +scripts/tavily_search.py "test" --api-key "tvly-..." +``` + +### Rate Limit Errors + +- Check your plan's credit allocation at https://tavily.com +- Reduce `max_results` to conserve credits +- Use `basic` depth instead of `advanced` +- Implement local caching for repeated queries + +## Resources + +See [api-reference.md](references/api-reference.md) for: +- Complete API parameter documentation +- Response format specifications +- Error handling details +- Cost and rate limit information +- Advanced usage examples + +## Dependencies + +- Python 3.6+ +- `tavily-python` package (install: `pip install tavily-python`) +- Valid Tavily API key + +## Credits & Attribution + +- Tavily API: https://tavily.com +- Python SDK: https://github.com/tavily-ai/tavily-python +- Documentation: https://docs.tavily.com diff --git a/tavily/references/api-reference.md b/tavily/references/api-reference.md new file mode 100644 index 0000000..02d3c84 --- /dev/null +++ b/tavily/references/api-reference.md @@ -0,0 +1,187 @@ +# Tavily API Reference + +## Overview + +Tavily is a search engine optimized for Large Language Models (LLMs) and AI applications. It provides: + +- **AI-optimized results**: Results specifically formatted for LLM consumption +- **Answer generation**: Optional AI-generated summaries from search results +- **Raw content extraction**: Clean, parsed HTML content from sources +- **Domain filtering**: Include or exclude specific domains +- **Image search**: Relevant images for visual context +- **Topic specialization**: General or news-focused search + +## API Key Setup + +1. Visit https://tavily.com and sign up +2. Generate an API key from your dashboard +3. Store the key securely: + - **Recommended**: Add to Clawdbot config under `skills.entries.tavily.apiKey` + - **Alternative**: Set `TAVILY_API_KEY` environment variable + +## Search Parameters + +### Required + +- `query` (string): The search query + +### Optional + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `search_depth` | string | `"basic"` | `"basic"` (fast, ~1-2s) or `"advanced"` (comprehensive, ~5-10s) | +| `topic` | string | `"general"` | `"general"` or `"news"` (current events, last 7 days) | +| `max_results` | int | 5 | Number of results (1-10) | +| `include_answer` | bool | true | Include AI-generated answer summary | +| `include_raw_content` | bool | false | Include cleaned HTML content of sources | +| `include_images` | bool | false | Include relevant images | +| `include_domains` | list[str] | null | Only search these domains | +| `exclude_domains` | list[str] | null | Exclude these domains | + +## Response Format + +```json +{ + "success": true, + "query": "What is quantum computing?", + "answer": "Quantum computing is a type of computing that uses...", + "results": [ + { + "title": "Quantum Computing Explained", + "url": "https://example.com/quantum", + "content": "Quantum computing leverages...", + "score": 0.95, + "raw_content": null + } + ], + "images": ["https://example.com/image.jpg"], + "response_time": "1.67", + "usage": { + "credits": 1 + } +} +``` + +## Use Cases & Best Practices + +### When to Use Tavily + +1. **Research tasks**: Comprehensive information gathering +2. **Current events**: News-focused queries with `topic="news"` +3. **Domain-specific search**: Use `include_domains` for trusted sources +4. **Visual content**: Enable `include_images` for visual context +5. **LLM consumption**: Results are pre-formatted for AI processing + +### Search Depth Comparison + +| Depth | Speed | Results Quality | Use Case | +|-------|-------|-----------------|----------| +| `basic` | 1-2s | Good | Quick lookups, simple facts | +| `advanced` | 5-10s | Excellent | Research, complex topics, comprehensive analysis | + +**Recommendation**: Start with `basic`, use `advanced` for research tasks. + +### Domain Filtering + +**Include domains** (allowlist): +```python +include_domains=["python.org", "github.com", "stackoverflow.com"] +``` +Only search these specific domains - useful for trusted sources. + +**Exclude domains** (denylist): +```python +exclude_domains=["pinterest.com", "quora.com"] +``` +Remove unwanted or low-quality sources. + +### Topic Selection + +**General** (`topic="general"`): +- Default mode +- Broader web search +- Historical and evergreen content +- Best for most queries + +**News** (`topic="news"`): +- Last 7 days only +- News-focused sources +- Current events and developments +- Best for "latest", "recent", "current" queries + +## Cost & Rate Limits + +- **Credits**: Each search consumes credits (1 credit for basic search) +- **Free tier**: Check https://tavily.com/pricing for current limits +- **Rate limits**: Varies by plan tier + +## Error Handling + +Common errors: + +1. **Missing API key** + ```json + { + "error": "Tavily API key required", + "setup_instructions": "Set TAVILY_API_KEY environment variable" + } + ``` + +2. **Package not installed** + ```json + { + "error": "tavily-python package not installed", + "install_command": "pip install tavily-python" + } + ``` + +3. **Invalid API key** + ```json + { + "error": "Invalid API key" + } + ``` + +4. **Rate limit exceeded** + ```json + { + "error": "Rate limit exceeded" + } + ``` + +## Python SDK + +The skill uses the official `tavily-python` package: + +```python +from tavily import TavilyClient + +client = TavilyClient(api_key="tvly-...") +response = client.search( + query="What is AI?", + search_depth="advanced", + max_results=10 +) +``` + +Install: `pip install tavily-python` + +## Comparison with Other Search APIs + +| Feature | Tavily | Brave Search | Perplexity | +|---------|--------|--------------|------------| +| AI Answer | βœ… Yes | ❌ No | βœ… Yes | +| Raw Content | βœ… Yes | ❌ No | ❌ No | +| Domain Filtering | βœ… Yes | Limited | ❌ No | +| Image Search | βœ… Yes | βœ… Yes | ❌ No | +| News Mode | βœ… Yes | βœ… Yes | βœ… Yes | +| LLM Optimized | βœ… Yes | ❌ No | βœ… Yes | +| Speed | Medium | Fast | Medium | +| Free Tier | βœ… Yes | βœ… Yes | Limited | + +## Additional Resources + +- Official Docs: https://docs.tavily.com +- Python SDK: https://github.com/tavily-ai/tavily-python +- API Reference: https://docs.tavily.com/documentation/api-reference +- Pricing: https://tavily.com/pricing diff --git a/tavily/scripts/tavily_search.py b/tavily/scripts/tavily_search.py new file mode 100644 index 0000000..f23d5d6 --- /dev/null +++ b/tavily/scripts/tavily_search.py @@ -0,0 +1,247 @@ +#!/usr/bin/env python3 +""" +Tavily AI Search - Optimized search for LLMs and AI applications +Requires: pip install tavily-python +""" + +import argparse +import json +import sys +import os +from typing import Optional, List + + +def search( + query: str, + api_key: str, + search_depth: str = "basic", + topic: str = "general", + max_results: int = 5, + include_answer: bool = True, + include_raw_content: bool = False, + include_images: bool = False, + include_domains: Optional[List[str]] = None, + exclude_domains: Optional[List[str]] = None, +) -> dict: + """ + Execute a Tavily search query. + + Args: + query: Search query string + api_key: Tavily API key (tvly-...) + search_depth: "basic" (fast) or "advanced" (comprehensive) + topic: "general" (default) or "news" (current events) + max_results: Number of results to return (1-10) + include_answer: Include AI-generated answer summary + include_raw_content: Include raw HTML content of sources + include_images: Include relevant images in results + include_domains: List of domains to specifically include + exclude_domains: List of domains to exclude + + Returns: + dict: Tavily API response + """ + try: + from tavily import TavilyClient + except ImportError: + return { + "error": "tavily-python package not installed. Run: pip install tavily-python", + "install_command": "pip install tavily-python" + } + + if not api_key: + return { + "error": "Tavily API key required. Get one at https://tavily.com", + "setup_instructions": "Set TAVILY_API_KEY environment variable or pass --api-key" + } + + try: + client = TavilyClient(api_key=api_key) + + # Build search parameters + search_params = { + "query": query, + "search_depth": search_depth, + "topic": topic, + "max_results": max_results, + "include_answer": include_answer, + "include_raw_content": include_raw_content, + "include_images": include_images, + } + + if include_domains: + search_params["include_domains"] = include_domains + if exclude_domains: + search_params["exclude_domains"] = exclude_domains + + response = client.search(**search_params) + + return { + "success": True, + "query": query, + "answer": response.get("answer"), + "results": response.get("results", []), + "images": response.get("images", []), + "response_time": response.get("response_time"), + "usage": response.get("usage", {}), + } + + except Exception as e: + return { + "error": str(e), + "query": query + } + + +def main(): + parser = argparse.ArgumentParser( + description="Tavily AI Search - Optimized search for LLMs", + formatter_class=argparse.RawDescriptionHelpFormatter, + epilog=""" +Examples: + # Basic search + %(prog)s "What is quantum computing?" + + # Advanced search with more results + %(prog)s "Climate change solutions" --depth advanced --max-results 10 + + # News-focused search + %(prog)s "AI developments" --topic news + + # Domain filtering + %(prog)s "Python tutorials" --include-domains python.org --exclude-domains w3schools.com + + # Include images in results + %(prog)s "Eiffel Tower" --images + +Environment Variables: + TAVILY_API_KEY Your Tavily API key (get one at https://tavily.com) + """ + ) + + parser.add_argument( + "query", + help="Search query" + ) + + parser.add_argument( + "--api-key", + help="Tavily API key (or set TAVILY_API_KEY env var)" + ) + + parser.add_argument( + "--depth", + choices=["basic", "advanced"], + default="basic", + help="Search depth: 'basic' (fast) or 'advanced' (comprehensive)" + ) + + parser.add_argument( + "--topic", + choices=["general", "news"], + default="general", + help="Search topic: 'general' or 'news' (current events)" + ) + + parser.add_argument( + "--max-results", + type=int, + default=5, + help="Maximum number of results (1-10)" + ) + + parser.add_argument( + "--no-answer", + action="store_true", + help="Exclude AI-generated answer summary" + ) + + parser.add_argument( + "--raw-content", + action="store_true", + help="Include raw HTML content of sources" + ) + + parser.add_argument( + "--images", + action="store_true", + help="Include relevant images in results" + ) + + parser.add_argument( + "--include-domains", + nargs="+", + help="List of domains to specifically include" + ) + + parser.add_argument( + "--exclude-domains", + nargs="+", + help="List of domains to exclude" + ) + + parser.add_argument( + "--json", + action="store_true", + help="Output raw JSON response" + ) + + args = parser.parse_args() + + # Get API key from args or environment + api_key = args.api_key or os.getenv("TAVILY_API_KEY") + + result = search( + query=args.query, + api_key=api_key, + search_depth=args.depth, + topic=args.topic, + max_results=args.max_results, + include_answer=not args.no_answer, + include_raw_content=args.raw_content, + include_images=args.images, + include_domains=args.include_domains, + exclude_domains=args.exclude_domains, + ) + + if args.json: + print(json.dumps(result, indent=2)) + else: + if "error" in result: + print(f"Error: {result['error']}", file=sys.stderr) + if "install_command" in result: + print(f"\nTo install: {result['install_command']}", file=sys.stderr) + if "setup_instructions" in result: + print(f"\nSetup: {result['setup_instructions']}", file=sys.stderr) + sys.exit(1) + + # Format human-readable output + print(f"Query: {result['query']}") + print(f"Response time: {result.get('response_time', 'N/A')}s") + print(f"Credits used: {result.get('usage', {}).get('credits', 'N/A')}\n") + + if result.get("answer"): + print("=== AI ANSWER ===") + print(result["answer"]) + print() + + if result.get("results"): + print("=== RESULTS ===") + for i, item in enumerate(result["results"], 1): + print(f"\n{i}. {item.get('title', 'No title')}") + print(f" URL: {item.get('url', 'N/A')}") + print(f" Score: {item.get('score', 'N/A'):.3f}") + if item.get("content"): + content = item["content"] + if len(content) > 200: + content = content[:200] + "..." + print(f" {content}") + + if result.get("images"): + print(f"\n=== IMAGES ({len(result['images'])}) ===") + for img_url in result["images"][:5]: # Show first 5 + print(f" {img_url}") + + +if __name__ == "__main__": + main()