Foam Notes

Work with Foam note repositories. Create, edit, link, and tag notes. Get intelligent wikilink and tag suggestions. Skill supports backlinks discovery, daily...

Security Scan

The skill's files, runtime instructions, and requested access are consistent with a local Foam note management tool — it reads and writes files in your Foam workspace but does not request credentials or make network calls.

Purpose & Capability

Name/description (Foam notes: create, edit, backlinks, templates, tags, suggestions) matches the included scripts and docs. The included Python scripts implement the advertised features (create_note, daily_note, find_backlinks, graph_summary, init_templates, suggest_wikilinks/suggest_tags, etc.). There are no unexpected credentials, cloud SDKs, or unrelated binaries required.

Instruction Scope

SKILL.md and the scripts keep operations within the Foam workspace: scanning and editing Markdown files under foam_root, copying templates to .foam/templates, and printing results. The only interactive behavior is an input() prompt in init_templates.py when the target directory doesn't look like a Foam workspace; otherwise scripts use CLI args or FOAM_WORKSPACE. There are no instructions to read unrelated system state, exfiltrate data, or call external endpoints.

Install Mechanism

No install spec; this is instruction-only with bundled Python scripts. That lowers supply-chain risk. Scripts are plain Python and do not download or execute remote code. They write files only under the detected foam_root and the skill's own assets/templates directory when copying templates.

Credentials

The skill does not require any credentials or special environment variables. It optionally respects FOAM_WORKSPACE or a --foam-root argument to locate the workspace; these are appropriate for its purpose. It does not request or access other secrets or unrelated config paths.

Persistence & Privilege

Skill is not always-enabled and does not request system-wide privileges. It reads and writes files in the user's Foam workspace (expected behavior). It does not modify other skills' configs or agent-wide settings.

Assessment

This skill appears to be a straightforward local Foam workspace utility: it scans and edits Markdown files under a specified foam_root, copies local templates into your workspace, and produces reports like backlinks and graph summaries. Before installing or running: 1) Confirm you trust the skill source (publisher is unknown here). 2) Set foam_root (via --foam-root or FOAM_WORKSPACE or config.json) to avoid accidentally pointing the scripts at an unintended directory. 3) Review the templates in assets/templates before running init_templates.py if you don't want them copied into your workspace. 4) Note: init_templates.py can prompt interactively if the target doesn't look like a Foam workspace and suggest confirming before proceeding. There are no network calls or credential requests, but as always, run code from untrusted publishers in an isolated environment if you have any concern.

Work with Foam note-taking workspaces in VS Code. Foam is a free, open-source personal knowledge management system using standard Markdown files with wikilinks.

Quick Reference

• Wikilinks: [[note-name]] — connect notes bidirectionally
• Embeds: ![[note-name]] — include content from other notes
• Backlinks: Automatically discovered connections to current note
• Tags: #tag or frontmatter tags: [tag1, tag2]
• Daily Notes: Alt+D or command "Foam: Open Daily Note"

Configuration

Copy config.json.template to config.json and edit to taste:

{
  "foam_root": "/path/to/your/foam-workspace",
  "default_template": "new-note",
  "default_notes_folder": "notes",
  "daily_note_folder": "journals",
  "author": "Your Name",
  "wikilinks": {
    "title_stopwords": ["home", "index", "readme", "draft", "template"],
    "suffixes": ["-hub"],
    "min_length": 3
  },
  "tags": {
    "editorial_stopwords": ["notes", "note", "foam", "markdown", "file", "page", "section"]
  }
}

Location: config.json in the skill directory (next to SKILL.md).

Config keys

Key	Type	Default	Description
foam_root	string	"" (auto-detect)	Path to your Foam workspace
default_template	string	"new-note"	Template for new notes
default_notes_folder	string	"notes"	Subfolder for new notes
daily_note_folder	string	"journals"	Subfolder for daily notes
author	string	""	Author name for note creation
wikilinks.title_stopwords	list	[]	Note titles to never match as wikilinks (e.g. "home", "index", "todo"). Add any generic filenames from your workspace that produce false positives.
wikilinks.suffixes	list	[]	Filename suffixes whose base stem should also register as a match key. For example, if you name your hub/MOC notes docker-hub.md, add "-hub" here so that "docker" in prose matches docker-hub.md.
wikilinks.min_length	int	3	Minimum key length to consider for wikilink matching
tags.editorial_stopwords	list	[]	Domain-specific words to exclude from tag suggestions (in addition to standard English stopwords).

Foam root priority order (highest to lowest)

1. --foam-root CLI argument
2. FOAM_WORKSPACE environment variable
3. foam_root in config.json
4. Auto-detect by finding .foam or .vscode directory
5. Current working directory

See references/configuration.md for complete documentation.

Scripts

All scripts support --foam-root to override the workspace path.

init_templates.py

Initialize .foam/templates/ with starter templates from the official Foam template:

python3 scripts/init_templates.py              # Copy to current workspace
python3 scripts/init_templates.py --foam-root ~/notes
python3 scripts/init_templates.py --list      # Show available templates
python3 scripts/init_templates.py --force     # Overwrite existing
python3 scripts/init_templates.py --dry-run   # Preview what would be copied

Templates included:

• new-note.md — Default template for new notes
• daily-note.md — Template for daily notes
• your-first-template.md — Example template demonstrating VS Code snippets

create_note.py

Create a new note from template:

python3 scripts/create_note.py "My New Idea"
python3 scripts/create_note.py "Meeting Notes" --template meeting
python3 scripts/create_note.py "Research Topic" --dir research/

find_backlinks.py

Find all notes that link to a given note:

python3 scripts/find_backlinks.py "Machine Learning"
python3 scripts/find_backlinks.py "ml-basics" --format json

search_tags.py

Find notes by tag:

python3 scripts/search_tags.py "#research"
python3 scripts/search_tags.py machine-learning --include-frontmatter

list_tags.py

List all tags with usage counts:

python3 scripts/list_tags.py
python3 scripts/list_tags.py --hierarchy --min-count 3

graph_summary.py

Analyze the knowledge graph:

python3 scripts/graph_summary.py
python3 scripts/graph_summary.py --format json

daily_note.py

Create daily notes:

python3 scripts/daily_note.py
python3 scripts/daily_note.py --yesterday
python3 scripts/daily_note.py --template custom-daily
python3 scripts/daily_note.py --print-path   # Just output the path

suggest_wikilinks.py

Suggest wikilinks by finding text in a note that matches existing note titles:

python3 scripts/suggest_wikilinks.py my-note.md              # Interactive mode
python3 scripts/suggest_wikilinks.py my-note.md --apply 1,3,5  # Auto-apply
python3 scripts/suggest_wikilinks.py my-note.md --auto-apply   # Apply all
python3 scripts/suggest_wikilinks.py my-note.md --dry-run      # Preview only
python3 scripts/suggest_wikilinks.py my-note.md --with-aliases # Create [[target|text]] format

The script scans the note content and identifies words/phrases that match existing note titles in the archive. It presents them as a numbered list:

1. Line 12, col 8
   Text: "machine learning"
   Link to: [[machine-learning]]
   Context: ...working on machine learning projects...

Wikilink formats:

• Default: [[target]] — clean, simple links
• With --with-aliases: [[target|display text]] — preserves original text as alias

Respond with:

• Numbers to implement (e.g., 1 3 5)
• all to apply all suggestions
• none to cancel

suggest_tags.py

Suggest tags for a note based on content and existing tags in the archive:

python3 scripts/suggest_tags.py my-note.md              # Interactive mode
python3 scripts/suggest_tags.py my-note.md --apply all  # Add all suggested
python3 scripts/suggest_tags.py my-note.md --apply existing  # Only existing tags
python3 scripts/suggest_tags.py my-note.md --frontmatter     # Add to frontmatter

The script:

1. Extracts keywords from note content
2. Finds matching existing tags (with usage counts)
3. Suggests new tags based on content analysis

Presented as numbered list with two sections:

• Existing Tags — Already used in your archive
• New Suggestions — Extracted from current note content

Respond with:

• Numbers (e.g., 1 3 5)
• all — all suggestions
• existing — only existing tags
• new — only new suggestions
• none — cancel
• Or type custom tags: #mytag #project

delete_note.py

Delete notes with optional backup and automatic backlink handling:

python3 scripts/delete_note.py "Old Note"                    # Interactive deletion
python3 scripts/delete_note.py "Old Note" --force          # Skip confirmation
python3 scripts/delete_note.py "Old Note" --backup         # Move to .foam/trash/
python3 scripts/delete_note.py "Old Note" --fix-links      # Remove wikilinks from other notes

Features:

• Backup mode: Moves note to .foam/trash/ instead of permanent deletion
• Backlink detection: Shows which notes link to the one being deleted
• Link fixing: Automatically removes wikilinks from other notes
• Confirmation: Prompts before deletion (skip with --force)

rename_note.py

Rename notes and automatically update all wikilinks:

python3 scripts/rename_note.py "Old Name" "New Name"       # Interactive rename
python3 scripts/rename_note.py "Old Name" "New Name" --force  # Skip confirmation

Features:

• Automatic wikilink updates: Finds and updates all [[old-name]] references
• File rename: Changes filename from old-name.md to new-name.md
• Title preservation: Keeps note content intact, only updates links
• Confirmation: Shows affected notes before proceeding

When to Use This Skill

Use this skill when:

• Creating or editing notes in a Foam workspace
• Working with wikilinks, backlinks, or the knowledge graph
• Analyzing note relationships and connections
• Setting up or configuring Foam templates
• Working with daily notes or tags
• Publishing Foam workspaces to static sites

Foam Workspace Structure

foam-workspace/
├── .vscode/
│   ├── extensions.json      # Recommended extensions
│   └── settings.json        # VS Code settings
├── .foam/
│   └── templates/           # Note templates (.md and .js)
├── journals/                # Daily notes (default location)
├── attachments/             # Images and files
├── *.md                     # Your notes
└── foam.json (optional)     # Foam configuration

Core Concepts

Wikilinks

Create connections between notes using double brackets:

See also [[related-concept]] for more information.

• Autocomplete with [[ + type note name
• Navigate with Ctrl+Click (or Cmd+Click on Mac)
• Create new notes by clicking non-existent links
• Link to sections: [[note-name#Section Title]]

See references/wikilinks.md for complete documentation.

Backlinks

Backlinks show which notes reference the current note — discovered automatically by Foam.

Access via:

• Command palette: "Explorer: Focus on Connections"
• Shows forward links, backlinks, or both

Use backlinks for:

• Finding unexpected connections between ideas
• Identifying hub concepts (notes with many backlinks)
• Building context around ideas across domains

See references/backlinks.md for complete documentation.

Tags

Organize notes beyond wikilinks:

# Inline tags
#machine-learning #research #in-progress

# Frontmatter tags
---
tags: [machine-learning, research, in-progress]
---

• Hierarchical: #programming/python
• Browse in Tag Explorer panel
• Search: "Foam: Search Tag"

See references/tags.md for complete documentation.

Daily Notes

Quick daily journaling:

• Shortcut: Alt+D
• Command: "Foam: Open Daily Note"
• Snippets: /today, /yesterday, /tomorrow

Template: .foam/templates/daily-note.md

See references/daily-notes.md for complete documentation.

Templates

Customize note creation. Foam looks for templates in .foam/templates/.

To initialize starter templates:

python3 scripts/init_templates.py

This copies official Foam templates to your workspace:

• new-note.md — Default template
• daily-note.md — Daily notes template
• your-first-template.md — Example with VS Code snippets

Markdown templates (.md):

---
foam_template:
  filepath: '$FOAM_CURRENT_DIR/$FOAM_SLUG.md'
---

# $FOAM_TITLE

Created: $FOAM_DATE_YEAR-$FOAM_DATE_MONTH-$FOAM_DATE_DATE

$FOAM_SELECTED_TEXT

JavaScript templates (.js) — for smart, context-aware templates.

See references/templates.md for complete documentation.

Common Tasks

Creating a New Note

When creating notes programmatically (not via VS Code), always read the workspace template in .foam/templates/new-note.md first and follow its structure exactly.

In VS Code:

1. Use "Foam: Create New Note" for default template
2. Use "Foam: Create New Note From Template" to choose template
3. Or click a non-existent wikilink [[new-note]]

Finding Note Relationships

1. Backlinks: Check Connections panel for linked notes
2. Graph View: Command "Foam: Show Graph" for visual network
3. Tag Explorer: Browse notes by tag

Working with Embeds

Include content from other notes:

![[glossary]]

See the full definition above.

Publishing

Foam can publish to static sites:

• GitHub Pages (built-in template)
• Netlify
• Vercel
• GitLab Pages
• Custom static site generators (Gatsby, MkDocs, etc.)

See recipes in Foam documentation for publishing options.

Foam vs Obsidian

Feature	Foam	Obsidian
Wikilinks	[[note]]	[[note]]
Embeds	![[note]]	![[note]]
Platform	VS Code	Dedicated app
Plugin ecosystem	Minimal (VS Code extensions)	Extensive
File format	Standard Markdown	Markdown with extensions
Configuration	.vscode/settings.json	.obsidian/ folder
Price	Free	Freemium

Both use the same core linking syntax. Foam prioritizes simplicity and standard formats.

Configuration

Key .vscode/settings.json options:

{
  "foam.openDailyNote.onStartup": true,
  "foam.dateSnippets.format": "yyyy-mm-dd",
  "markdown.styles": [".foam/css/custom.css"]
}

Foam CLI Commands

Key VS Code commands:

• Foam: Open Daily Note — Create/open today's note
• Foam: Create New Note — Create from default template
• Foam: Create New Note From Template — Choose template
• Foam: Create New Template — Create new template
• Foam: Show Graph — Visualize knowledge graph
• Foam: Search Tag — Search for tagged notes
• Explorer: Focus on Connections — Show backlinks panel

Reference Documentation

• foam-overview.md — General Foam introduction and philosophy
• wikilinks.md — Complete wikilinks guide
• backlinks.md — Backlinks and knowledge discovery
• tags.md — Tag organization and filtering
• daily-notes.md — Daily note workflows
• templates.md — Template creation (Markdown and JavaScript)

Read these files for detailed information on specific features.

External Resources

• Official site: https://foamnotes.com
• GitHub: https://github.com/foambubble/foam
• Discord: https://foambubble.github.io/join-discord/w

Tips

1. Start small: Foam works best with consistent note-taking habits
2. Link liberally: Create wikilinks even to non-existent notes (placeholders)
3. Use the graph: Visualize your knowledge network to find gaps
4. Trust the process: Backlinks reveal connections you didn't plan
5. Keep it standard: Foam uses standard Markdown — your notes remain portable