# Competitor intel agent Human Guide

## What This Is For
Track competitor activity across multiple dimensions, detect meaningful changes, interpret the signals, and deliver actionable intelligence that builds historical context over time. It gives the agent a clearer input/output frame for competitive research: what context to ask for, what decisions to make, and what usable artifact to return.

Use this as a human-readable version of the Competitor intel agent agent skill. It is meant for marketers, operators, founders, and other non-coders who want the workflow without reading agent-specific implementation instructions.

## When To Use This
- Use this when you need a repeatable process for competitor intel agent.
- Use this when the task needs judgment, examples, constraints, or a clear output format rather than a one-off prompt.
- Use this when you want to hand an AI assistant enough context to produce a usable marketing artifact.

## When Not To Use This
- Do not use this when you only need a quick factual answer.
- Do not use this when the work depends on private data you cannot share with the assistant.
- Do not use this as a replacement for legal, compliance, financial, or medical review.

## What You Need Before Starting
- The goal or business outcome you want.
- The audience, customer segment, or market context.
- Any source material the assistant should respect, such as notes, briefs, examples, URLs, or brand guidance.
- Constraints such as tone, length, channel, deadline, region, or approval requirements.
- A clear definition of what a good final answer should look like.

## Step-By-Step Workflow
1. State the job clearly: "Use the Competitor intel agent guide to help me with..."
2. Add context: audience, goal, offer, channel, source material, and constraints.
3. Ask the assistant to identify missing inputs before producing the final output.
4. Have the assistant follow the skill-specific guidance below.
5. Review the result against the final checklist and ask for revisions where needed.

## Skill-Specific Guidance
- `references/directory-structure.md` -- tracking directory layout, `config.yaml`, and `usage-history.json` templates
- `references/monitoring-dimensions.md` -- the six monitoring dimensions with per-dimension analysis frameworks, detection protocols, and snapshot output formats
- `references/intel-report-format.md` -- the full intelligence report template
- `references/scoring-and-rules.md` -- change-detection scoring, trend protocol, data-quality rules, execution rules, quick commands
- Determine the operating mode on invocation:
- Monitoring run (tracking directory exists): proceed to steps 2-7.
- Report only (user wants a report without new monitoring): read existing snapshots and change logs, synthesize trends, and generate strategic recommendations using `references/intel-report-format.md`.
- Read `config.yaml` to load the competitor list and settings, then read the most recent snapshot for each competitor and dimension.
- Execute monitoring across all configured dimensions. Apply the detection protocol for each dimension in `references/monitoring-dimensions.md`.
- Compare new data against previous snapshots. Score every change for magnitude per `references/scoring-and-rules.md`; flag changes rated 4-5 as immediate alerts.
- Write dated snapshots in the per-dimension output formats and log detected changes under the competitor's `changes/` folder.
- Generate the intelligence report following `references/intel-report-format.md`. When 3 or more snapshots exist for a competitor, add longitudinal trend analysis.

## Decision Points And Nuance
The original skill emphasizes: Contents, Workflow, Guardrails, Supporting file: references/directory-structure.md, Directory layout, config.yaml template, usage-history.json template, Supporting file: references/intel-report-format.md, Executive Summary, Critical Alerts.

Use these questions to steer the work:
- What is the intended audience or buyer?
- What source material must be preserved?
- What should the assistant optimize for: clarity, persuasion, accuracy, speed, creativity, or conversion?
- What examples represent the desired quality bar?
- What should the assistant avoid?

## Common Mistakes
- Never fabricate competitor data. If a fetch fails or a dimension has no data, state the gap.
- [3-5 bullet points capturing the most important findings across all competitors.
- Staleness warnings: flag data older than 30 days as potentially stale.
- No fabrication: if data for a dimension cannot be found, say so. Never make up competitor data.
- Be thorough but efficient. Do not fetch pages that have not changed (use snapshot comparison). Focus monitoring time on high-value dimensions.
- Separate fact from analysis. Snapshots contain raw data; analysis lives in the intel deliverable. Never mix them.
- Protect against hallucination. If WebFetch fails or returns incomplete data, note the gap. Do not fill in data from memory or assumption.
- Respect rate limits. Space out web requests. Do not hammer competitor websites.

## Copy-And-Paste Prompt
```text
Use the Competitor intel agent human guide.

My goal:
[Describe the business outcome]

Audience:
[Describe who this is for]

Context and source material:
[Paste notes, examples, links, or existing copy]

Constraints:
[Tone, length, channel, timeline, must-include items, must-avoid items]

Before producing the final output, ask me for any missing information that would materially improve the result.
```

## Final Checklist
- [ ] The output matches the original goal.
- [ ] The audience and context are reflected in the answer.
- [ ] Important constraints and source material were preserved.
- [ ] The assistant made the relevant decisions explicit.
- [ ] The final artifact is ready to use, review, or hand to the next person.

## Source
This guide was generated from the onewave-ai/claude-skills skill entry for `competitor-intel-agent`.

## Source Skill Notes
These notes preserve the nuance from the original skill. Use them as supporting reference when the workflow above feels too generic.

# Competitor Intelligence Agent

Track competitor activity across multiple dimensions, detect meaningful changes, interpret the signals, and deliver actionable intelligence that builds historical context over time. Act as an analyst that connects dots, not a raw scraper.

## Contents

- `references/directory-structure.md` -- tracking directory layout, `config.yaml`, and `usage-history.json` templates
- `references/monitoring-dimensions.md` -- the six monitoring dimensions with per-dimension analysis frameworks, detection protocols, and snapshot output formats
- `references/intel-report-format.md` -- the full intelligence report template
- `references/scoring-and-rules.md` -- change-detection scoring, trend protocol, data-quality rules, execution rules, quick commands

## Workflow

1. Determine the operating mode on invocation:
   - Setup (no tracking directory exists): collect the user's company name and description, competitor URLs/domains, priority monitoring dimensions, and output directory (default `./competitor-intel/`). Create the directory structure and `config.yaml`. See `references/directory-structure.md`.
   - Monitoring run (tracking directory exists): proceed to steps 2-7.
   - Report only (user wants a report without new monitoring): read existing snapshots and change logs, synthesize trends, and generate strategic recommendations using `references/intel-report-format.md`.
2. Read `config.yaml` to load the competitor list and settings, then read the most recent snapshot for each competitor and dimension.
3. Execute monitoring across all configured dimensions. Apply the detection protocol for each dimension in `references/monitoring-dimensions.md`.
4. Compare new data against previous snapshots. Score every change for magnitude per `references/scoring-and-rules.md`; flag changes rated 4-5 as immediate alerts.
5. Write dated snapshots in the per-dimension output formats and log detected changes under the competitor's `changes/` folder.
6. Generate the intelligence report following `references/intel-report-format.md`. When 3 or more snapshots exist for a competitor, add longitudinal trend analysis.
7. Update `usage-history.json` with the run metadata.

## Guardrails

- Never fabricate competitor data. If a fetch fails or a dimension has no data, state the gap.
- Separate raw data (snapshots) from interpretation (reports).
- Tag every data point with source, timestamp, and confidence; flag data older than 30 days as stale.
- Recommend only legal, ethical competitive responses. Collect only publicly available professional information.

Apply the detailed change-detection, trend, data-quality, and execution rules in `references/scoring-and-rules.md` throughout.

---

## Supporting file: references/directory-structure.md

# Tracking Directory Structure and Config

## Directory layout

Create this structure under the chosen output directory (default `./competitor-intel/`):

```
competitor-intel/
  config.yaml                    # Monitoring configuration
  competitors/
    {competitor-slug}/
      profile.yaml               # Company profile and metadata
      snapshots/
        {date}-pricing.md        # Historical pricing snapshots
        {date}-features.md       # Historical feature snapshots
        {date}-content.md        # Historical content snapshots
        {date}-jobs.md           # Historical job posting snapshots
      changes/
        {date}-changes.md        # Detected changes log
  reports/
    {date}-intel-report.md       # Generated intelligence reports
    {date}-alert.md              # Urgent change alerts
  trends/
    pricing-trends.md            # Longitudinal pricing analysis
    feature-trends.md            # Feature evolution tracking
    content-trends.md            # Content strategy analysis
    hiring-trends.md             # Hiring pattern analysis
  usage-history.json             # Run history and tracking metadata
```

## config.yaml template

```yaml
version: "1.0"
created: "2026-06-05"
company:
  name: ""
  description: ""
  website: ""

competitors:
  - slug: ""
    name: ""