How to use the Defuddle Web Capture Planner agent skill

What is an agent skill and what does defuddle do?

An agent skill is a folder with a SKILL.md file that tells an AI agent how to handle a particular kind of task. The agent reads the instructions when your request matches the skill's description.

The defuddle skill covers two things. For a web address (HTTPS URL), it produces an inert plan that records the normalized host, required network egress, redirect policy, optional dependency, and execute: false. It does not fetch the page. For a local HTML or Markdown file, it retains the file as bytes in a create-only .raw/captured/ folder inside your vault, without rendering the file or running its scripts.

• Web addresses: planning only, no network request is made.
• Local HTML or Markdown: reviewed capture into raw storage, with an operation ID and exact changed paths reported.
• Cleaning, raw capture, and wiki ingestion are treated as separate operations.

Install the defuddle skill

Download the ZIP from the skill's page on this directory, then choose one of the following options.

For Claude Code, unzip the package into your personal skills folder at ~/.claude/skills/, or into a project's .claude/skills/ folder to limit it to one project.

In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Set up the product root and vault

The skill expects an installed claude-obsidian product root that contains a scripts directory with claude-obsidian.py. The skill resolves this root from its own location, not from your selected vault or current working directory.

You also need an Obsidian-style vault with an inbox folder. Local files you want to retain should be placed in the vault's inbox/ first.

• Python 3 is required to run the bundled core script.
• The core script is scripts/claude-obsidian.py inside the product root.
• The vault needs an inbox/ folder.

How to trigger the skill with natural requests

The skill's description lists the phrases that should trigger it. You can phrase requests naturally, using words like defuddle, clean this URL, strip page clutter, or readable Markdown from a web page. Mention the file or link explicitly so the agent knows which source to handle.

Be clear about intent. If you only want to read a file, say so; the skill reads or analyzes files transiently when retention was not requested. If you want to keep it, say you want it retained or captured.

• "Use defuddle to plan a readable Markdown version of this URL: https://example.com/article"
• "Retain inbox/source.md in my vault as a raw source."
• "Clean this URL and strip page clutter for my wiki."

Example: retaining a local file

The workflow first previews the capture plan, then applies it with a pinned timestamp and operation ID. The agent reviews the dry run and passes back the reviewed approved_plan_sha256 value before the apply step writes anything.

The result preserves source bytes in create-only .raw/captured/ storage. It does not clean HTML or verify metadata. The agent reports the operation ID and the exact changed paths. A repeated identical payload is a no-op, and existing raw state is never overwritten.

• Preview first with capture plan.
• Review approved_plan_sha256 from the dry run.
• Apply with --approved-plan-sha256 and --apply.
• Expect a report of the operation ID and changed paths.

Safety notes: scripts and network

The skill runs scripts: it calls the bundled claude-obsidian.py core script. It does not use the network. The upstream Defuddle CLI is not bundled and is never run automatically. Running it against a URL or local HTML could follow redirects, enable asynchronous extraction, or request third-party fallbacks, so the skill does not do this.

URLs are accepted only over HTTPS. The skill rejects credentials, fragments, control characters, sensitive query parameters, and non-public hosts or IP addresses. URLs are never placed into shell strings.

• Network extraction is unavailable until an enforcing adapter is verified.
• Each destination requires consent, even with an enforcing adapter.
• An executable found on your system is reported as configured, not verified, and is not run automatically.

Tips for getting good results

Keep source files in the vault's inbox/ before asking for retention, so the path is explicit. Record any known extractor, version, or locator if you supply already cleaned text, and do not expect the agent to invent missing details.

If you need higher-quality extraction or token savings, plan for a separate tool. This skill does not claim either benefit.

• Use the inbox/ folder for every file you plan to retain.
• Read the dry-run output before approving the apply step.
• Treat URL plans as records, not downloads.