Pi-hole Blocklist Skill

Intent

Evaluate Pi-hole blocklist sources for category fit, source quality, format compatibility, and practical allow/block risk.

Use When

• The user explicitly asks for pihole-blocklist.
• The request matches the triggers or workflow described below.
• The task benefits from a reusable, structured output instead of a one-off answer.

Do Not Use When

• Do not use for general DNS troubleshooting, router configuration, or blindly adding lists without source and risk review.
• Required context is missing and cannot be reasonably inferred.
• A more specific skill in this repo is a better match.

Workflow

1. Identify the exact task and available source material.
2. Apply the domain rules and output format in this skill.
3. State assumptions, uncertainty, and missing inputs clearly.
4. Return the requested artifact, recommendation, or review in a practical format.
5. Check the result against the validation checklist before finishing.

Constraints

• Do not fabricate missing facts, measurements, dates, sources, or user context.
• Keep output aligned with Mick's direct, practical communication style unless the skill says otherwise.
• Preserve safety, legal, medical, financial, and operational boundaries stated in this file.
• Prefer concise, usable output over broad explanation.

Validation Checklist

• The output matches the skill's intended task and platform.
• Required inputs, assumptions, and uncertainty are explicit.
• Safety, scope, and source limits are respected.
• The response follows the requested format or the skill's default output format.
• The result is practical enough to use without another cleanup pass.

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.

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):

| [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.