Skip to content
Obsidian Bases

Obsidian Bases Skill

Official Obsidian skill for creating and editing Bases (.base files): database-like table, cards, list, kanban and map views of notes with filters, formulas, summaries and sorting, plus YAML quoting rules and fixes for common errors.

GitHub Docs

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from obsidianmd/obsidian-skills.

$ npx skills add obsidianmd/obsidian-skills --skill obsidian-bases

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/obsidian-bases/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/obsidianmd/obsidian-skills.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/plugins/obsidian/skills/obsidian-bases ~/.claude/skills/obsidian-bases

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/obsidian-bases/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • Writes valid .base YAML for Obsidian's core Bases plugin
  • Table, cards, list, kanban and map views with ordering and sorting
  • Nested and/or/not filters, formula properties and summary formulas
  • Complete examples: task tracker, reading list, daily notes index
  • YAML quoting rules and troubleshooting for common formula errors

Obsidian Bases is part of the obsidian-skills collection published by Obsidian (obsidianmd, originally created by Obsidian CEO Steph Ango). It teaches an agent to write .base files, the YAML format behind Obsidian's core Bases plugin, which turns notes in a vault into database-like views. The agent uses it when working with .base files or when the user mentions Bases, table or card views, kanban boards, filters or formulas in Obsidian.

The skill gives a six-step workflow (create the file, scope it with filters, add formulas, configure views, validate the YAML, open it in Obsidian) and documents the full schema: global and per-view filters with and, or and not nesting and their operators; the three kinds of properties (note, file and formula) and the file property reference; the this keyword; formula syntax and key functions, including the Duration type and date arithmetic; the five view types (table, cards, list, kanban and map); sorting; and default summary formulas.

It includes complete examples for a task tracker, a reading list and a daily notes index, shows how to embed a base in a note or inline in a code block, and ends with YAML quoting rules and a troubleshooting section built from wrong-and-correct pairs, such as dividing a Duration, crashing on an empty date, or a displayName that is ignored without the note. prefix. Requires Obsidian with the Bases core plugin enabled. MIT licensed.

SKILL.md

The instructions your agent loads, as published by Obsidian.

SKILL.md
name
obsidian-bases
description
Create and edit Obsidian Bases (.base files) with views, filters, formulas, and summaries. Use when working with .base files, creating database-like views of notes, or when the user mentions Bases, table views, card views, kanban boards, filters, or formulas in Obsidian.

Obsidian Bases Skill

Workflow
  1. Create the file: Create a .base file in the vault with valid YAML content
  2. Define scope: Add filters to select which notes appear (by tag, folder, property, or date)
  3. Add formulas (optional): Define computed properties in the formulas section
  4. Configure views: Add one or more views (table, cards, list, map, or kanban) with order specifying which properties to display
  5. Validate: Verify the file is valid YAML with no syntax errors. Check that all referenced properties and formulas exist. Common issues: unquoted strings containing special YAML characters, mismatched quotes in formula expressions, referencing formula.X without defining X in formulas
  6. Test in Obsidian: Open the .base file in Obsidian to confirm the view renders correctly. If it shows a YAML error, check quoting rules below. If it doesn't open as a base at all, check that Bases is turned on in Settings → Core plugins
Schema

Base files use the .base extension and contain valid YAML.

# Global filters apply to ALL views in the base
filters:
  # Can be a single filter string
  # OR a recursive filter object with exactly ONE key: and, or, or not
  and:
    - 'status == "active"'
    - not:
        - 'file.hasTag("archived")'

# Define formula properties that can be used across all views
formulas:
  formula_name: 'expression'

# Configure display names and settings for properties.
# Note properties need the `note.` prefix here, or the setting is ignored.
properties:
  note.property_name:
    displayName: "Display Name"
  formula.formula_name:
    displayName: "Formula Display Name"
  file.ext:
    displayName: "Extension"

# Define custom summary formulas
summaries:
  custom_summary_name: 'values.mean().round(3)'

# Define one or more views
views:
  - type: table | cards | list | map | kanban
    name: "View Name"
    limit: 10                    # Optional: limit results
    groupBy:                     # Optional: group results
      property: property_name
      direction: ASC | DESC
    groupOrder:                  # Optional: only these groups, in this order
      - value_one
      - null                     # Files with no value for the groupBy property
    sort:                        # Optional: sort results (supports multiple properties)
      - property: property_name
        direction: ASC | DESC
    filters:                     # View-specific filters follow the same rules
      and:
        - 'status == "active"'
    order:                       # Properties to display in order
      - file.name
      - property_name
      - formula.formula_name
    summaries:                   # Map properties to summary formulas
      property_name: Average
Filter Syntax

Filters narrow down results. They can be applied globally or per-view.

Filter Structure
# Single filter
filters: 'status == "done"'

# AND - all conditions must be true
filters:
  and:
    - 'status == "done"'
    - 'priority > 3'

# OR - any condition can be true
filters:
  or:
    - 'file.hasTag("book")'
    - 'file.hasTag("article")'

# NOT - exclude matching items
filters:
  not:
    - 'file.hasTag("archived")'

# Nested filters
filters:
  or:
    - file.hasTag("tag")
    - and:
        - file.hasTag("book")
        - file.hasLink("Textbook")
    - not:
        - file.hasTag("book")
        - file.inFolder("Required Reading")
Filter Operators
OperatorDescription
==equals
!=not equal
>greater than
<less than
>=greater than or equal
<=less than or equal
&&logical and
||logical or
<code>!</code>logical not
Properties
Three Types of Properties
  1. Note properties - From frontmatter: note.author or just author
  2. File properties - File metadata: file.name, file.mtime, etc.
  3. Formula properties - Computed values: formula.my_formula

In order, filters, groupBy, and sort, a note property can be written bare (author) or prefixed (note.author). In the top-level properties: section, always write note.author, because Obsidian ignores a bare key there and shows the raw name as the column header.

File Properties Reference
PropertyTypeDescription
file.nameStringFile name
file.basenameStringFile name without extension
file.pathStringFull path to file
file.folderStringParent folder path
file.extStringFile extension
file.sizeNumberFile size in bytes
file.ctimeDateCreated time
file.mtimeDateModified time
file.tagsListAll tags in file
file.linksListInternal links in file
file.backlinksListFiles linking to this file. Slow in large vaults and doesn't refresh when the vault changes; prefer reversing the lookup with file.links
file.embedsListEmbeds in the note
file.propertiesObjectAll frontmatter properties. Doesn't refresh when the vault changes
file.fileFileFile object, only usable in specific functions
The this Keyword
  • In main content area: refers to the base file itself
  • When embedded: refers to the embedding file
  • In sidebar: refers to the active file in main content
Formula Syntax

Formulas compute values from properties. Defined in the formulas section.

formulas:
  # Simple arithmetic
  total: "price * quantity"

  # Conditional logic
  status_icon: 'if(done, "✅", "⏳")'

  # String formatting
  formatted_price: 'if(price, price.toFixed(2) + " dollars")'

  # Date formatting
  created: 'file.ctime.format("YYYY-MM-DD")'

  # Calculate days since created (use .days for Duration)
  days_old: '(now() - file.ctime).days'

  # Calculate days until due date
  days_until_due: 'if(due_date, (date(due_date) - today()).days, "")'
Key Functions

Most commonly used functions. For the complete reference of all types (Date, String, Number, List, File, Link, Object, RegExp), see [FUNCTIONS_REFERENCE.md](references/FUNCTIONS_REFERENCE.md).

FunctionSignatureDescription
date()date(string): dateParse string to date (YYYY-MM-DD HH:mm:ss)
now()now(): dateCurrent date and time
today()today(): dateCurrent date (time = 00:00:00)
if()if(condition, trueResult, falseResult?)Conditional
duration()duration(string): durationParse duration string
file()file(path): fileGet file object
link()link(path, display?): LinkCreate a link
Duration Type

When subtracting two dates, the result is a Duration type (not a number).

Duration Fields: duration.days, duration.hours, duration.minutes, duration.seconds, duration.milliseconds

IMPORTANT: Duration does NOT support .round(), .floor(), .ceil() directly. Access a numeric field first (like .days), then apply number functions.

# CORRECT: Calculate days between dates
"(date(due_date) - today()).days"                    # Returns number of days
"(now() - file.ctime).days"                          # Days since created
"(date(due_date) - today()).days.round(0)"           # Rounded days

# WRONG - will cause error:
# "((date(due) - today()) / 86400000).round(0)"      # Duration doesn't support division then round
Date Arithmetic
# Duration units: y/year/years, M/month/months, d/day/days,
#                 w/week/weeks, h/hour/hours, m/minute/minutes, s/second/seconds
"now() + \"1 day\""       # Tomorrow
"today() + \"7d\""        # A week from today
"now() - file.ctime"      # Returns Duration
"(now() - file.ctime).days"  # Get days as number
View Types
Table View
views:
  - type: table
    name: "My Table"
    order:
      - file.name
      - status
      - due_date
    summaries:
      price: Sum
      count: Average
Cards View
views:
  - type: cards
    name: "Gallery"
    order:
      - file.name
      - cover_image
      - description
List View
views:
  - type: list
    name: "Simple List"
    order:
      - file.name
      - status
Kanban View

Requires Obsidian 1.14+. Cards are grouped into columns by the groupBy property, which a kanban view needs. groupOrder sets which columns show and in what order; use null to include files with no value. Without groupOrder, every value gets a column. Dragging a card to another column updates that property in the note. Only Markdown notes can be moved, except when grouping by file.folder, where moving a card moves the file to that folder. When grouping by a formula or by a file property other than file.folder, cards and columns can't be moved and notes can't be created from a column.

views:
  - type: kanban
    name: "Projects"
    groupBy:
      property: note.status
      direction: ASC
    groupOrder:
      - Planned
      - In progress
      - Done
    order:
      - file.name
      - due_date
Map View

Requires latitude/longitude properties and the Maps community plugin.

views:
  - type: map
    name: "Locations"
    # Map-specific settings for lat/lng properties
Sorting

Sort results by one or more properties. Each sort entry specifies a property and direction, which must be uppercase ASC or DESC; an entry with any other value, or a sort written as a string, is silently ignored. Multiple sort entries are applied in order — the first entry is the primary sort key, subsequent entries break ties.

views:
  - type: table
    name: "Sorted Tasks"
    sort:
      - property: due
        direction: ASC
      - property: file.name
        direction: ASC
    order:
      - file.name
      - due
      - status

Sort options depend on the property type:

Property TypeASCDESC
TextA→ZZ→A
Number0→99→0
DateOld→NewNew→Old

You can sort by any property including formulas (formula.my_formula), file properties (file.mtime), and note properties.

Default Summary Formulas
NameInput TypeDescription
AverageNumberMathematical mean
MinNumberSmallest number
MaxNumberLargest number
SumNumberSum of all numbers
RangeNumberMax - Min
MedianNumberMathematical median
StddevNumberStandard deviation
EarliestDateEarliest date
LatestDateLatest date
RangeDateLatest - Earliest
CheckedBooleanCount of true values
UncheckedBooleanCount of false values
EmptyAnyCount of empty values
FilledAnyCount of non-empty values
UniqueAnyCount of unique values
Complete Examples
Task Tracker Base
filters:
  and:
    - file.hasTag("task")
    - 'file.ext == "md"'

formulas:
  days_until_due: 'if(due, (date(due) - today()).days, "")'
  is_overdue: 'if(due, date(due) < today() && status != "done", false)'
  priority_label: 'if(priority == 1, "🔴 High", if(priority == 2, "🟡 Medium", "🟢 Low"))'

properties:
  note.status:
    displayName: Status
  formula.days_until_due:
    displayName: "Days Until Due"
  formula.priority_label:
    displayName: Priority

views:
  - type: table
    name: "Active Tasks"
    filters:
      and:
        - 'status != "done"'
    order:
      - file.name
      - status
      - formula.priority_label
      - due
      - formula.days_until_due
    groupBy:
      property: status
      direction: ASC
    sort:
      - property: due
        direction: ASC
      - property: file.name
        direction: ASC
    summaries:
      formula.days_until_due: Average

  - type: table
    name: "Completed"
    filters:
      and:
        - 'status == "done"'
    order:
      - file.name
      - completed_date
Reading List Base
filters:
  or:
    - file.hasTag("book")
    - file.hasTag("article")

formulas:
  reading_time: 'if(pages, (pages * 2).toString() + " min", "")'
  status_icon: 'if(status == "reading", "📖", if(status == "done", "✅", "📚"))'
  year_read: 'if(finished_date, date(finished_date).year, "")'

properties:
  note.author:
    displayName: Author
  formula.status_icon:
    displayName: "Status"
  formula.reading_time:
    displayName: "Est. Time"

views:
  - type: cards
    name: "Library"
    order:
      - cover
      - file.name
      - author
      - formula.status_icon
    filters:
      not:
        - 'status == "dropped"'

  - type: table
    name: "Reading List"
    filters:
      and:
        - 'status == "to-read"'
    order:
      - file.name
      - author
      - pages
      - formula.reading_time
Daily Notes Index
filters:
  and:
    - file.inFolder("Daily Notes")
    - '/^\d{4}-\d{2}-\d{2}$/.matches(file.basename)'

formulas:
  word_estimate: '(file.size / 5).round(0)'
  day_of_week: 'date(file.basename).format("dddd")'

properties:
  formula.day_of_week:
    displayName: "Day"
  formula.word_estimate:
    displayName: "~Words"

views:
  - type: table
    name: "Recent Notes"
    limit: 30
    order:
      - file.name
      - formula.day_of_week
      - formula.word_estimate
      - file.mtime
Embedding Bases
Embed a .base file

Embed an external .base file in any Markdown note:

![[MyBase.base]]

<!-- Specific view -->
![[MyBase.base#View Name]]
Embed inline with a code block

Bases can also be embedded inline directly inside a note using a base fenced code block. This is useful for note-level filters (e.g. using this.file.links) and avoids creating a separate .base file:

filters:
and:

  • file.hasTag("example")

views:

  • type: table

name: Table
order:

  • file.name
  • status

When embedded inline this way, the this keyword refers to the containing note, so you can build per-note views such as showing all notes linked from the current file.

YAML Quoting Rules
  • Use single quotes for formulas containing double quotes: 'if(done, "Yes", "No")'
  • Use double quotes for simple strings: "My View Name"
  • Escape nested quotes properly in complex expressions
Troubleshooting
YAML Syntax Errors

Unquoted special characters: Strings containing :, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, %, @, ` `, !` must be quoted.

# WRONG - colon in unquoted string
displayName: Status: Active

# CORRECT
displayName: "Status: Active"

Mismatched quotes in formulas: When a formula contains double quotes, wrap the entire formula in single quotes.

# WRONG - double quotes inside double quotes
formulas:
  label: "if(done, "Yes", "No")"

# CORRECT - single quotes wrapping double quotes
formulas:
  label: 'if(done, "Yes", "No")'
Common Formula Errors

Duration math without field access: Subtracting dates returns a Duration, not a number. Always access .days, .hours, etc.

# WRONG - Duration is not a number
"(now() - file.ctime).round(0)"

# CORRECT - access .days first, then round
"(now() - file.ctime).days.round(0)"

Missing null checks: Properties may not exist on all notes. Use if() to guard.

# WRONG - crashes if due_date is empty
"(date(due_date) - today()).days"

# CORRECT - guard with if()
'if(due_date, (date(due_date) - today()).days, "")'

`displayName` ignored, column shows the raw name: prefix note properties with note. in the properties: section.

# WRONG - displayName ignored, column header shows "status"
properties:
  status:
    displayName: Status

# CORRECT - column header shows "Status"
properties:
  note.status:
    displayName: Status

Empty `displayName` doesn't hide a header: displayName: "" falls back to the property name, the same as leaving it out, so formula.status_icon shows status_icon. Use a non-empty name such as displayName: "Status".

Referencing undefined formulas: Ensure every formula.X in order or properties has a matching entry in formulas.

# This will fail silently if 'total' is not defined in formulas
order:
  - formula.total

# Fix: define it
formulas:
  total: "price * quantity"
References
Install

Skill: Obsidian CLI

by Steph Ango (kepano)

New

Lets an agent drive a running Obsidian app through the official obsidian CLI: read, create, append to and search notes, manage tasks, properties and daily notes, and reload, debug and screenshot plugins and themes.

Anthropic's official skill for surfacing matching Claude Academy courses, tutorials and use cases at the end of a how-do-I answer — and staying silent when the match is weak.

Browse all skills →