pihole-blocklist git:20260514.3080b38A

Immutable. This exact content never changes and is served at /api/v1/blob/ded0195ff8be04c9.

---
name: pihole-blocklist
description: Evaluate, categorize, and document new Pi-hole blocklist sources for the curated blocklist repository. Always trigger immediately when the user asks about adding, evaluating, or researching a new Pi-hole blocklist source, or uses phrases like "should I add this list", "evaluate this blocklist", "add to pihole", "new blocklist", "is this a good list", or pastes a raw blocklist URL. Also trigger when the user wants to review existing sources, update the repo README, check for list overlap, or document a new category. Pre-loaded with the full category taxonomy and evaluation criteria so every new addition is consistent with the existing curation standard.
---

# Pi-hole Blocklist Skill

Evaluate new blocklist sources, assign them to the correct category, check for quality and overlap, and produce ready-to-commit documentation for the curated blocklist repository at `github.com/mickpletcher/PiHole`.

---

## Repository Context

**Repo**: `github.com/mickpletcher/PiHole`  
**Current sources**: 57 curated blocklist URLs  
**Maintenance cadence**: Regular scheduled updates  
**Format**: Mixed (hosts file format and plain domain lists)  
**Pi-hole instance**: CT 101 at 192.168.0.101 (local reference only — do not publish this)

---

## Category Taxonomy

Every blocklist source belongs to exactly one primary category. Use this taxonomy consistently.

| Category | What It Covers |
|---|---|
| **Advertising** | Ad servers, ad networks, pop-up ad domains |
| **Tracking** | Telemetry, fingerprinting, analytics, CNAME cloaking |
| **Malicious** | Malware, ransomware, phishing, scam domains |
| **Suspicious** | Spam, referrer spam, high-risk domains |
| **Fake DNS / DynDNS** | Fake DNS providers, dynamic DNS abusers |
| **Piracy** | Anti-piracy DNS blocklists |
| **Fake News** | Known fake news domains |
| **Stalkerware** | Stalkerware and spyware indicator domains |
| **Device Trackers** | Platform-native trackers (Amazon, Apple, TikTok, Samsung, LG, Windows/Office) |
| **Smart TV / IoT** | Broad smart TV and IoT telemetry across all brands |
| **URL Shorteners** | URL shortener services used to obscure malicious links |
| **Encrypted DNS / VPN Bypass** | Domains used to circumvent DNS filtering |
| **OISD** | Comprehensive all-in-one lists covering ads, tracking, and malware |
| **Whitelist** | Approved domains excluded from blocking |

---

## Evaluation Criteria

When asked to evaluate a new source, assess all of the following:

### 1. Source Quality
- Is the list actively maintained? Check last commit date or update timestamp.
- Does it have a clear maintainer (GitHub repo, named project, organization)?
- Is there a stated methodology for what gets added and removed?
- Does it have community trust signals (stars, forks, citations in other blocklist projects)?

### 2. Category Fit
- Which category from the taxonomy does it best fit?
- Does it duplicate coverage already provided by an existing source in that category?
- Does it add meaningfully new domains not covered by existing sources?

### 3. Format Compatibility
- Is the URL a direct raw link to the list (not an HTML page)?
- Is it in a Pi-hole-compatible format: hosts file (`0.0.0.0 domain.com`) or plain domain list (one per line)?
- Is it stable — does the URL change between updates, or is it a permanent raw URL?

### 4. Risk Assessment
- Could any domains on the list cause false positives for common services?
- Is the list known to be aggressive (high false positive rate) or conservative?
- Has the list been flagged in the Pi-hole community for issues?

### 5. Recommendation
- **Add**: Meets quality bar, fills a gap, compatible format, stable URL
- **Add with caution**: Useful but aggressive — note false positive risk in documentation
- **Skip**: Redundant, unmaintained, incompatible format, or unclear provenance
- **Whitelist candidate**: Source contains domains that should be whitelisted rather than blocked

---

## What Claude Should Produce

### For a new source evaluation:

```
SOURCE: [Name]
URL: [raw URL]
CATEGORY: [from taxonomy]
MAINTAINER: [GitHub user / org / project name]
LAST UPDATED: [date or "active" if recent commits]
DOMAIN COUNT: [approximate if known]
FORMAT: [hosts / plain domain list / mixed]
OVERLAP RISK: [low / medium / high — with which existing category]
FALSE POSITIVE RISK: [low / medium / high — brief reason]
RECOMMENDATION: [Add / Add with caution / Skip / Whitelist candidate]
NOTES: [Any caveats, known issues, or context]
```

### For a README table entry (when adding a new source):

```markdown
| [Source Name] | [URL] |
```

Formatted to match the existing table style in the repo README.

### For a batch evaluation (multiple URLs at once):

Produce one evaluation block per source, then a summary table at the end showing recommended adds vs. skips.

---

## How to Add a New Source to Pi-hole

1. Log into the Pi-hole admin panel
2. Navigate to **Group Management → Adlists**
3. Paste the raw URL into the **Address** field
4. Add a comment matching the source name from the repo
5. Click **Add**
6. Go to **Tools → Update Gravity** and click **Update**

---

## Reference Files

- `pihole-blocklist-sources.md` — local index of the current curated sources organized by category

## Help And Examples

If the user is not sure how to use this skill, asks what it needs, or asks for examples:

- Explain in plain language what this skill can do.
- Tell the user the minimum input needed for a useful first pass.
- Show the example prompts below.
- Offer the fastest next prompt the user can send.

Minimum useful input:

- A blocklist source, URL, or candidate list to evaluate.

Example prompts:

- `Use pihole-blocklist to review this candidate blocklist and tell me if it belongs in my setup.`
- `Evaluate these new Pi-hole sources for quality, overlap, and risk.`
- `Show me a sample prompt for asking this skill to document and classify a blocklist source.`