Skip to content
Get packs

Guide · Agent skill

How to use the Knap Markdown Renderer agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The Knap Markdown Renderer is an agent skill that teaches an AI agent to use the Knap command-line tool. Knap fills Markdown templates with variables, filters and simple logic. This guide explains what the skill does, how to install it, how to ask for it in plain language, and what to watch for, so you can finish with a working setup and a first rendered note.

Knap Markdown Rendererkepano/obsidian-skills · MIT

Quick start

  1. 1Install Node.js 20 or later. Confirm that Node.js 20 or later is available on your machine before you set up Knap.
  2. 2Install the Knap CLI. Run npm install -g knap, or use npx knap to run it without a global install.
  3. 3Add the skill folder. Unzip the knap skill download into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings, Capabilities, Skills in the Claude apps.
  4. 4Validate a template. Run knap validate template.md to check syntax and filter names before using real data.
  5. 5Dry-run a batch. Run knap batch with --dry-run to list the output paths and confirm nothing will be overwritten unexpectedly.
  6. 6Render your data. Run the render or batch command with your JSON or CSV data and check the output.

What the Knap skill makes the agent do

An agent skill is a folder with instructions that an AI agent loads when a task matches them. The knap skill covers rendering Markdown from templates and structured data using the Knap CLI. Once it is installed, the agent can apply a Knap template, turn JSON or CSV data into notes, batch-generate many Markdown files, and format Defuddle output into a note.

The skill is defined by a single file, SKILL.md, and it is released under the MIT licence.

  • Render one template with JSON data into one note
  • Generate one file per CSV row, JSON object or JSON file in a folder
  • Check a template for errors before rendering
  • Turn web page content extracted by Defuddle into a templated note

Install the Knap skill and the Knap CLI

Download the ZIP of the knap skill from this page and unzip it. Place the resulting folder in ~/.claude/skills/ for all your projects, or in a project's .claude/skills/ folder for that project only. Alternatively, in the Claude apps, open Settings, then Capabilities, then Skills, and upload the skill there.

The skill drives the Knap CLI, which must be available on your machine. Knap requires Node.js 20 or later. Install it globally with npm, or skip the global install and run it through npx.

  • Requires Node.js 20 or later
  • Knap CLI: install with npm, or run with npx knap
  • Defuddle CLI: only needed if you use the web page pipeline
npm install -g knap

Trigger the skill with natural requests

You do not need to name commands. The skill is triggered when you ask for something it covers. Describe the outcome you want, mention your template or data file, and let the agent choose the Knap commands.

Good requests name the input and the output. For example, you can say that you want to apply a Knap template to a JSON file, turn a CSV of articles into one note per row, or format Defuddle output into a note. Requests that mention a specific folder or file name give the agent what it needs to avoid guessing.

  • Apply my Knap template to article.json and save the result as note.md
  • Turn articles.csv into one Markdown note per row in a notes folder
  • Batch-generate Markdown files from this JSON array, but dry-run first
  • Format this Defuddle output into a note using my template

Examples of rendering and batch output

A single render takes a template file and a JSON data file. The output goes to stdout unless you pass -o. Data must be a JSON object, and its properties become template variables. You can override a top-level value with --set.

For batch work, Knap creates one file per CSV row, per object in a JSON array, or per JSON file in a folder. Use --filename with the safe_name filter to build file names from your data. Use --dry-run first to list the output paths without writing anything.

  • Use --set to override a top-level key with a string
  • Use JSON, not --set, for nested objects, arrays, numbers and booleans
  • CSV headers become variable names, and values stay strings
  • Without --filename, Knap numbers outputs as 1.md, 2.md and so on
knap render template.md --data article.json -o note.md knap batch template.md --data articles.csv --output-dir notes --filename '{{ title | safe_name }}.md' knap validate template.md

Safety notes: scripts, network and overwrites

This skill runs scripts and uses the network. The Defuddle pipeline fetches a web page, so only point it at URLs you trust. Errors exit with status 1 and diagnostics go to stderr, so check stderr when something fails.

Be careful with overwrites. The -o option overwrites the destination after rendering succeeds. In batch runs, existing files require --overwrite, and --overwrite replaces files without a backup step. Run --dry-run first, and do not batch-overwrite notes you cannot afford to lose. Duplicate output names within a batch are errors even with --overwrite.

  • Use --dry-run before any batch run that writes files
  • Keep backups of important notes before using --overwrite
  • Validate templates before rendering with real data

Tips for reliable templates

Use the offline help to find names and syntax before writing a template. The CLI lists its syntax, filters and tags, and you can ask for help on a single filter or tag.

Use yaml_property for frontmatter properties so values are quoted and indented correctly. Remember that validation checks syntax, filter names and static filter arguments only. It does not check whether a variable exists or what runtime values will be, so render with real data to confirm behaviour. Filename templates must produce a single filename with its extension and no directories.

  • Run knap help syntax, knap help filters and knap help tags to discover names
  • Run knap help tag for to see parameters and examples for one tag
  • Use safe_name for any filename built from data
  • Knap does not supply Web Clipper browser variables, selectors, prompts or DOM-based filters
knap help syntax knap help filters knap help filter date knap help tags knap help tag for

What people use it for

  • Turn a CSV of book or article records into one Markdown note per row
  • Generate a set of notes from a JSON array exported from another tool
  • Save web page content extracted by Defuddle as a templated note
  • Keep a repeatable note format by rendering the same template with new data each time

Frequently asked questions

How do I install the Knap skill for Claude?

Download the knap skill ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project. In the Claude apps, you can instead upload it under Settings, then Capabilities, then Skills.

What do I need to run the Knap skill?

You need Node.js 20 or later and the Knap CLI, installed with npm install -g knap or run with npx knap. The Defuddle CLI is only needed if you want the web page pipeline.

Is the Knap skill free to use?

The skill is released under the MIT licence. Knap, Node.js and Defuddle are separate tools, and this page does not state their pricing, so check their own terms if that matters to you.

Can the agent write Markdown without Knap?

Yes. For simple one-off Markdown, the agent can write the file directly, and Knap adds setup without much benefit. Knap is most useful for templated output from JSON or CSV data, and for batch generation of many files.

Does Knap work as a Web Clipper replacement?

No. Knap does not supply Web Clipper browser variables, selectors, prompts or DOM-based filters. It can format content that Defuddle extracts, but it is not a browser clipping tool.

Why does my batch run fail or refuse to write files?

Existing files need --overwrite, and duplicate output names in one batch are errors even with --overwrite. Run --dry-run to list output paths first. Errors exit with status 1, and the diagnostics on stderr usually include relevant help commands.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose the Knap skill if you regularly turn JSON or CSV data into many Markdown notes, or want a repeatable template for web content extracted with Defuddle. Skip it for simple one-off notes, or if you need Web Clipper browser features, since the agent can write a single file directly and Knap does not handle browser capture.

Download the skill