Competitor Finder

Identifies 3-5 competitors for a given brand using SerpAPI, DataForSEO, or OpenAI fallback, returning names, websites, and optional reasons for competition.

Security Scan

The skill's runtime instructions require multiple external API credentials and send brand data to third-party services, but the registry metadata does not declare these required environment variables—this mismatch and the potential for data sent to external APIs are concerning.

Purpose & Capability

The skill's stated purpose (finding competitors via SerpAPI/DataForSEO with an OpenAI fallback) matches the methods described in SKILL.md. However, the registry metadata lists no required environment variables while SKILL.md clearly depends on SERPAPI_KEY, DATAFORSEO_LOGIN, DATAFORSEO_PASSWORD, and OPENAI_API_KEY. That metadata omission is an incoherence: someone implementing this feature legitimately needs those credentials.

Instruction Scope

SKILL.md instructs the agent to call external APIs (SerpAPI, DataForSEO, and OpenAI) and to log brandName and domain on errors. Sending brand/domain to third-party APIs is expected for this task, but it is data exfiltration to external endpoints and should be explicitly declared in metadata and user documentation. The instructions do not request any unrelated local files or system credentials.

Install Mechanism

Instruction-only skill with no install spec and no code files — lowest-risk installation behaviour. Nothing is written to disk by the skill itself per the provided materials.

Credentials

The skill requires multiple service credentials (SERPAPI_KEY, DATAFORSEO_LOGIN/PASSWORD, OPENAI_API_KEY) which are proportionate to the described multi-backend approach, but the registry metadata declares no required env vars. The missing declarations are a security/privacy and transparency issue. Also note that logging brandName/domain could expose sensitive or proprietary brand queries in logs.

Persistence & Privilege

No elevated persistence requested: always is false, user-invocable and autonomous invocation are default. The skill does not request modifying other skills or system-wide config.

What to consider before installing

This skill appears to do what it says (use search APIs and an OpenAI fallback), but the registry metadata does not list the environment variables the instructions require. Before installing/providing secrets: (1) Confirm the registry metadata is updated to list SERPAPI_KEY, DATAFORSEO_LOGIN, DATAFORSEO_PASSWORD, and OPENAI_API_KEY so you know what will be sent to external services. (2) Decide whether you are comfortable sending brand names/domains to third-party APIs (these calls will transmit that data). (3) Be aware of costs/rate limits for SerpAPI/DataForSEO/OpenAI. (4) If you don't want model calls, ask the maintainer to remove or gate the OpenAI fallback. (5) Prefer providing a single trusted API credential (or scoped credentials) rather than multiple long-lived secrets. If the maintainer cannot explain the metadata omission, treat the package as untrusted until corrected.

Competitor Finder Skill

Purpose

Identifies 3-5 competitors for a given brand by searching the web via SerpAPI and, as a last resort, falling back to a minimal OpenAI call. Returns competitor names, websites, and optionally the reason they are considered competitors. This collector feeds into the Marketing Audit Pipeline to populate the Competitor Landscape section of the final report.

Input Schema

// Function signature
collectCompetitors(brandName: string, domain?: string): Promise<CompetitorData>

// brandName: The brand name to find competitors for (e.g. "Gymshark")
// domain: Optional domain for additional context (e.g. "gymshark.com").
// Helps refine competitor search and filter out the brand itself from results.

Output Schema

interface CompetitorData {
 competitors: CompetitorEntry[]; // 3-5 competitor entries
 error?: string; // Present only when collector fails
}

interface CompetitorEntry {
 name: string; // e.g. "Nike"
 website: string; // e.g. "nike.com"
 reason?: string; // e.g. "Direct competitor in activewear market"
}

API Dependencies

Primary: SerpAPI

• API Name: SerpAPI (Google Search)
• Endpoint: https://serpapi.com/search.json
• Auth: SERPAPI_KEY environment variable
• Cost estimate: ~$0.005 per search
• Rate limits: Depends on plan; free tier allows 100 searches/month

Secondary: DataForSEO

• API Name: DataForSEO Competitor Domain API
• Endpoint: https://api.dataforseo.com/v3/dataforseo_labs/google/competitors_domain/live
• Auth: DATAFORSEO_LOGIN + DATAFORSEO_PASSWORD environment variables
• Cost estimate: ~$0.01 per request
• Rate limits: Depends on plan; free tier allows 100 requests/month

Fallback: OpenAI (minimal call)

• API Name: OpenAI API
• Model: gpt-4.1-mini
• Auth: OPENAI_API_KEY environment variable
• Cost estimate: ~$0.001 per call (minimal prompt)
• Usage: Only used when both SerpAPI and DataForSEO fail or return no results

Implementation Pattern

Data Flow

1. Receive brandName and optional domain from the pipeline
2. Attempt Method 1: SerpAPI search
3. If Method 1 fails or returns insufficient results, attempt Method 2: DataForSEO
4. If both fail, attempt Method 3: OpenAI fallback (minimal prompt)
5. Deduplicate and filter results (remove the brand itself)
6. Return 3-5 competitors mapped to CompetitorData

Method 1: SerpAPI Search

// Query: "top competitors of {brandName}"
{
 api_key: process.env.SERPAPI_KEY,
 engine: "google",
 q: `top competitors of ${brandName}`,
 num: 10
}

• Parse organic results to extract competitor brand names and domains
• Look for listicle-style results ("Top 10 Gymshark competitors...")
• Extract domain names from result URLs
• Filter out non-competitor results (news articles, the brand's own site)

Method 2: DataForSEO Competitor Domain

[{
 target: domain, // e.g. "gymshark.com"
 language_code: "en",
 location_code: 2840, // United States
 limit: 5
}]

• Returns domains that compete for the same keywords
• More accurate than SERP search but requires the domain parameter

Method 3: OpenAI Fallback (Minimal)

// ONLY used when Methods 1 and 2 both fail
// This is a MINIMAL prompt -- keep token usage as low as possible
const response = await openai.chat.completions.create({
 model: 'gpt-4.1-mini',
 max_tokens: 200,
 temperature: 0.3,
 messages: [
 {
 role: 'system',
 content: 'You are a marketing analyst. Return only a JSON array of competitor objects.'
 },
 {
 role: 'user',
 content: `List 5 direct competitors of "${brandName}"${domain ? ` (${domain})` : ''}. Return JSON: [{"name":"...","website":"...","reason":"..."}]`
 }
 ]
});

• Parse the JSON response
• This call costs ~$0.001 and should only happen when SERP/DataForSEO APIs are unavailable
• Log a warning when this fallback is used so it can be monitored

Result Filtering

• Remove entries where the name or website matches the input brand
• Deduplicate by website domain (normalize: strip www, trailing slashes)
• Ensure each entry has both name and website populated
• Limit to 5 results maximum; aim for at least 3

Error Handling

• Entire function wrapped in try/catch
• On failure of all three methods, return EMPTY_COMPETITOR_DATA with error field set:

return { ...EMPTY_COMPETITOR_DATA, error: 'Competitor data unavailable: <reason>' };

• Never throw -- always return a valid CompetitorData object
• Log errors with Winston logger including brandName and method that failed:

logger.error('Competitor collector failed', { brandName, domain, method, err });

• Log warnings when falling back to secondary/tertiary methods:

logger.warn('Competitor finder: SerpAPI failed, falling back to DataForSEO', { brandName });
logger.warn('Competitor finder: DataForSEO failed, falling back to OpenAI', { brandName });

• Common failure scenarios:
• SerpAPI key invalid or quota exhausted
• DataForSEO credentials invalid or out of credits
• OpenAI API key invalid
• No competitors found for niche or unknown brand
• Network timeout on any API

Example Usage

import { collectCompetitors } from '../collectors/competitorCollector';

// Successful collection (via SerpAPI)
const data = await collectCompetitors('Gymshark', 'gymshark.com');
// Returns:
// {
// competitors: [
// { name: "Nike", website: "nike.com", reason: "Global leader in athletic apparel" },
// { name: "Lululemon", website: "lululemon.com", reason: "Premium activewear competitor" },
// { name: "Under Armour", website: "underarmour.com", reason: "Direct competitor in gym wear" },
// { name: "Alphalete", website: "alphalete.com", reason: "DTC fitness apparel brand" },
// { name: "Fabletics", website: "fabletics.com", reason: "Subscription-based activewear" },
// ],
// }

// Partial result (only OpenAI fallback worked)
const partial = await collectCompetitors('ObscureBrand');
// Returns:
// {
// competitors: [
// { name: "CompetitorA", website: "competitora.com", reason: "Similar product category" },
// { name: "CompetitorB", website: "competitorb.com", reason: "Same target market" },
// { name: "CompetitorC", website: "competitorc.com" },
// ],
// }

// Failed collection (graceful degradation)
const failedData = await collectCompetitors('UnknownBrand');
// Returns:
// {
// competitors: [],
// error: "Competitor data unavailable: All methods failed"
// }

Notes

• This collector uses a three-tier fallback strategy to maximize data availability. SerpAPI is preferred because it provides real SERP data. DataForSEO provides keyword-overlap-based competitors. OpenAI is a last resort.
• The OpenAI fallback is the ONLY place outside of reportGenerator.ts where an AI model call is permitted. It must be minimal (max 200 tokens) and should be logged as a warning for cost monitoring.
• When the input type is 'instagram' (no domain available), skip Method 2 (DataForSEO requires a domain) and rely on Methods 1 and 3.
• The EMPTY_COMPETITOR_DATA constant is defined in src/types/audit.types.ts and should be imported for fallback returns.
• Competitor data is inherently subjective. The report generator (GPT-4.1-mini) will contextualize the raw competitor list into strategic analysis.
• This collector must never block the pipeline. Even a complete failure returns valid typed data with an error flag.