Skip to content

richfrem/agent-plugins-skills / plugins/agent-memory/.apm/skills/managing-obsidian-vaults

managing-obsidian-vaults

Verified

Interactive vault, wiki and Super-RAG setup in the main conversation. Use for "set up my wiki", "initialize the full knowledge stack" or combined RLM/vector/wiki setup. Manage Obsidian vaults and LLM wikis: initialize vaults, author Markdown and wikilinks, safely edit notes and Bases, create Canvas diagrams, traverse graphs, build concept wikis, distill summary/bullets/deep layers, query and lint knowledge.

FileKindSize
SKILL.mdskill md5.9 KB
assets/templates/config.yaml.templateother556 B
assets/templates/raw-sources.json.exampleother862 B
assets/templates/wiki-node.template.mdmarkdown410 B
evals/README.mdmarkdown569 B
evals/evals.jsonconfig23.4 KB
evals/legacy/obsidian-bases-manager/evals.jsonconfig692 B
evals/legacy/obsidian-bases-manager/results.tsvother301 B
evals/legacy/obsidian-canvas-architect/evals.jsonconfig731 B
evals/legacy/obsidian-canvas-architect/results.tsvother301 B
evals/legacy/obsidian-graph-traversal/evals.jsonconfig706 B
evals/legacy/obsidian-graph-traversal/results.tsvother301 B
evals/legacy/obsidian-init/evals.jsonconfig667 B
evals/legacy/obsidian-init/results.tsvother301 B
evals/legacy/obsidian-markdown-mastery/evals.jsonconfig652 B
evals/legacy/obsidian-markdown-mastery/results.tsvother301 B
evals/legacy/obsidian-query-agent/evals.jsonconfig767 B
evals/legacy/obsidian-rlm-distiller/evals.jsonconfig685 B
evals/legacy/obsidian-vault-crud/evals.jsonconfig638 B
evals/legacy/obsidian-vault-crud/results.tsvother301 B
evals/legacy/obsidian-wiki-builder/evals.jsonconfig732 B
evals/legacy/obsidian-wiki-linter/evals.jsonconfig1.5 KB
evals/results.tsvother73 B
evals/task-success.jsonconfig3.5 KB
references/acceptance-criteria.mdmarkdown2.9 KB
references/architecture-background.mdmarkdown2.8 KB
references/dependencies.mdmarkdown1.7 KB
references/interactive-setup.mdmarkdown7.0 KB
references/interactive-stack-setup.mdmarkdown5.6 KB
references/kepano-analysis-summary.mdmarkdown1.7 KB
references/obsidian-bases-manager-acceptance-criteria.mdmarkdown628 B
references/obsidian-bases-manager-fallback-tree.mdmarkdown787 B
references/obsidian-bases-manager.mdmarkdown2.1 KB
references/obsidian-canvas-architect-acceptance-criteria.mdmarkdown645 B
references/obsidian-canvas-architect-fallback-tree.mdmarkdown836 B
references/obsidian-canvas-architect.mdmarkdown1.9 KB
references/obsidian-graph-traversal-acceptance-criteria.mdmarkdown690 B
references/obsidian-graph-traversal-fallback-tree.mdmarkdown877 B
references/obsidian-graph-traversal.mdmarkdown2.2 KB
references/obsidian-init-acceptance-criteria.mdmarkdown650 B
references/obsidian-init-fallback-tree.mdmarkdown1.1 KB
references/obsidian-init.mdmarkdown2.0 KB
references/obsidian-markdown-mastery-acceptance-criteria.mdmarkdown700 B
references/obsidian-markdown-mastery-fallback-tree.mdmarkdown889 B
references/obsidian-markdown-mastery.mdmarkdown2.2 KB
references/obsidian-query-agent.mdmarkdown1.8 KB
references/obsidian-rlm-distiller.mdmarkdown1.8 KB
references/obsidian-vault-crud-acceptance-criteria.mdmarkdown833 B
references/obsidian-vault-crud-fallback-tree.mdmarkdown1.1 KB
references/obsidian-vault-crud.mdmarkdown2.2 KB
references/obsidian-vault-onboarding-guide.mdmarkdown3.7 KB
references/obsidian-wiki-builder.mdmarkdown1.8 KB
references/obsidian-wiki-linter.mdmarkdown1.7 KB
references/resource-index.mdmarkdown4.3 KB
references/safety-learnings.mdmarkdown2.7 KB
references/wiki-builder-guide.mdmarkdown2.7 KB
references/wiki-distillation-guide.mdmarkdown1.7 KB
references/wiki-linting-guide.mdmarkdown2.1 KB
references/wiki-query-guide.mdmarkdown2.1 KB
requirements.inother32 B
requirements.txtmanifest463 B
scripts/audit.pyscript9.0 KB
scripts/bases_ops.pyscript7.8 KB
scripts/canvas_gen.pyscript7.9 KB
scripts/canvas_ops.pyscript11.5 KB
scripts/concept_extractor.pyscript10.2 KB
scripts/constants.pyscript908 B
scripts/distill_wiki.pyscript12.9 KB
scripts/graph_ops.pyscript11.7 KB
scripts/ingest.pyscript8.3 KB
scripts/init_vault.pyscript5.7 KB
scripts/lint_wiki.pyscript9.3 KB
scripts/obsidian-parser/parser.pyscript6.5 KB
scripts/obsidian-parser/tests/test_parser.pyscript4.1 KB
scripts/query_wiki.pyscript21.3 KB
scripts/raw_manifest.pyscript14.3 KB
scripts/vault_ops.pyscript13.4 KB
scripts/wiki_builder.pyscript14.3 KB

scripts/canvas_ops.py

View on GitHub
"""
canvas_ops.py (CLI)
=====================================

Purpose:
    Programmatically create and manipulate Obsidian Canvas (.canvas) files.
    Uses JSON Canvas Spec 1.0. Enables agents to generate visual flowcharts,
    architecture diagrams, and planning boards with nodes and edges.

Layer: Core Operations

Usage Examples:
    pythoncanvas_ops.py read --file example.canvas
    pythoncanvas_ops.py create --file example.canvas
    pythoncanvas_ops.py add-node --file example.canvas --type text --text "Node Content"

Supported Object Types:
    - .canvas (JSON layout)

CLI Arguments:
    Subcommands: read, create, add-node, add-edge. Run with --help for details.

Input Files:
    - .canvas files.

Output:
    - JSON results or modified .canvas files.

Key Functions:
    read_canvas(): Read and parse a .canvas file.
    create_canvas(): Create a new empty canvas.
    add_node(): Add a node to an existing canvas.
    add_edge(): Add an edge between nodes.

Script Dependencies:
    sys, json, uuid, argparse, pathlib, os

Consumed by:
    - obsidian-canvas-architect skill
"""
import sys
import json
import uuid
import argparse
from pathlib import Path
from typing import Dict, Any, List, Optional
import os


class CanvasError(Exception):
    """Non-fatal error for canvas operations."""
    pass


# ---------------------------------------------------------------------------
# Schema Validation
# ---------------------------------------------------------------------------
REQUIRED_NODE_FIELDS = {
    "text": ["id", "type", "text", "x", "y", "width", "height"],
    "file": ["id", "type", "file", "x", "y", "width", "height"],
    "link": ["id", "type", "url", "x", "y", "width", "height"],
    "group": ["id", "type", "x", "y", "width", "height"],
}

REQUIRED_EDGE_FIELDS = ["id", "fromNode", "toNode"]
VALID_SIDES = ["top", "right", "bottom", "left"]


def _validate_node(node: Dict[str, Any]) -> Optional[str]:
    """Validate a node against JSON Canvas Spec 1.0. Returns None if valid, error string otherwise."""
    node_type = node.get("type")
    if node_type not in REQUIRED_NODE_FIELDS:
        return f"Unknown node type: {node_type}. Valid: {list(REQUIRED_NODE_FIELDS.keys())}"

    for field in REQUIRED_NODE_FIELDS[node_type]:
        if field not in node:
            return f"Node missing required field '{field}' for type '{node_type}'"

    return None


def _validate_edge(edge: Dict[str, Any], node_ids: set) -> Optional[str]:
    """Validate an edge. Returns None if valid, error string otherwise."""
    for field in REQUIRED_EDGE_FIELDS:
        if field not in edge:
            return f"Edge missing required field '{field}'"

    if edge["fromNode"] not in node_ids:
        return f"Edge references unknown fromNode: {edge['fromNode']}"
    if edge["toNode"] not in node_ids:
        return f"Edge references unknown toNode: {edge['toNode']}"

    for side_field in ["fromSide", "toSide"]:
        if side_field in edge and edge[side_field] not in VALID_SIDES:
            return f"Invalid {side_field}: {edge[side_field]}. Valid: {VALID_SIDES}"

    return None


def _gen_id() -> str:
    """Generate a short unique ID for nodes/edges."""
    return uuid.uuid4().hex[:12]


# ---------------------------------------------------------------------------
# Core Operations
# ---------------------------------------------------------------------------
def read_canvas(filepath: Path) -> Dict[str, Any]:
    """Read and parse a .canvas file."""
    if not filepath.exists():
        return {"error": f"File not found: {filepath}"}

    try:
        content = filepath.read_text(encoding='utf-8')
        data = json.loads(content)

        # Validate structure
        if not isinstance(data, dict):
            return {"error": "Canvas file is not a JSON object", "file": str(filepath)}

        nodes = data.get("nodes", [])
        edges = data.get("edges", [])

        # Validate each node
        warnings = []
        for i, node in enumerate(nodes):
            err = _validate_node(node)
            if err:
                warnings.append(f"Node {i}: {err}")

        # Validate each edge
        node_ids = {n["id"] for n in nodes if "id" in n}
        for i, edge in enumerate(edges):
            err = _validate_edge(edge, node_ids)
            if err:
                warnings.append(f"Edge {i}: {err}")

        return {
            "file": str(filepath),
            "node_count": len(nodes),
            "edge_count": len(edges),
            "nodes": nodes,
            "edges": edges,
            "warnings": warnings if warnings else None
        }

    except json.JSONDecodeError as e:
        return {"error": f"JSON_PARSE_ERROR: {str(e)}", "file": str(filepath)}
    except Exception as e:
        return {"error": f"READ_ERROR: {str(e)}", "file": str(filepath)}


def create_canvas(filepath: Path) -> Dict[str, Any]:
    """Create a new empty .canvas file."""
    if filepath.exists():
        return {"error": f"File already exists: {filepath}"}

    filepath.parent.mkdir(parents=True, exist_ok=True)

    canvas = {"nodes": [], "edges": []}
    content = json.dumps(canvas, indent=2)

    # Atomic write
    tmp_path = filepath.parent / f"{filepath.name}.agent-tmp"
    tmp_path.write_text(content, encoding='utf-8')
    os.rename(str(tmp_path), str(filepath))

    return {"status": "created", "file": str(filepath)}


def _apply_node_type_fields(node: Dict[str, Any], node_type: str, kwargs: Dict[str, Any]) -> None:
    """Populate node's type-specific field (text/file/url/label) from kwargs, in place."""
    if node_type == "text":
        node["text"] = kwargs.get("text", "")
    elif node_type == "file":
        node["file"] = kwargs.get("file_path", "")
    elif node_type == "link":
        node["url"] = kwargs.get("url", "")
    elif node_type == "group":
        node["label"] = kwargs.get("label", "")


def _write_canvas_atomic(filepath: Path, data: Dict[str, Any]) -> None:
    """Dump data as JSON and atomically replace filepath's contents."""
    new_content = json.dumps(data, indent=2)
    tmp_path = filepath.parent / f"{filepath.name}.agent-tmp"
    tmp_path.write_text(new_content, encoding='utf-8')
    os.rename(str(tmp_path), str(filepath))


def add_node(filepath: Path, node_type: str, x: int = 0, y: int = 0,
             width: int = 250, height: int = 60, **kwargs) -> Dict[str, Any]:
    """Add a node to an existing canvas."""
    if not filepath.exists():
        return {"error": f"File not found: {filepath}"}

    try:
        content = filepath.read_text(encoding='utf-8')
        data = json.loads(content)

        node = {
            "id": _gen_id(),
            "type": node_type,
            "x": x,
            "y": y,
            "width": width,
            "height": height,
        }
        _apply_node_type_fields(node, node_type, kwargs)

        # Optional color
        if "color" in kwargs:
            node["color"] = kwargs["color"]

        # Validate before adding
        err = _validate_node(node)
        if err:
            return {"error": f"VALIDATION_ERROR: {err}"}

        if "nodes" not in data:
            data["nodes"] = []
        data["nodes"].append(node)

        _write_canvas_atomic(filepath, data)

        return {"status": "node_added", "node_id": node["id"], "file": str(filepath)}

    except json.JSONDecodeError as e:
        return {"error": f"JSON_PARSE_ERROR: {str(e)}"}
    except Exception as e:
        return {"error": f"ADD_NODE_ERROR: {str(e)}"}


def add_edge(filepath: Path, from_node: str, to_node: str,
             from_side: str = "right", to_side: str = "left",
             label: Optional[str] = None) -> Dict[str, Any]:
    """Add a directional edge between two nodes."""
    if not filepath.exists():
        return {"error": f"File not found: {filepath}"}

    try:
        content = filepath.read_text(encoding='utf-8')
        data = json.loads(content)

        node_ids = {n["id"] for n in data.get("nodes", []) if "id" in n}

        edge = {
            "id": _gen_id(),
            "fromNode": from_node,
            "toNode": to_node,
            "fromSide": from_side,
            "toSide": to_side,
        }
        if label:
            edge["label"] = label

        # Validate
        err = _validate_edge(edge, node_ids)
        if err:
            return {"error": f"VALIDATION_ERROR: {err}"}

        if "edges" not in data:
            data["edges"] = []
        data["edges"].append(edge)

        # Atomic write
        new_content = json.dumps(data, indent=2)
        tmp_path = filepath.parent / f"{filepath.name}.agent-tmp"
        tmp_path.write_text(new_content, encoding='utf-8')
        os.rename(str(tmp_path), str(filepath))

        return {"status": "edge_added", "edge_id": edge["id"], "file": str(filepath)}

    except json.JSONDecodeError as e:
        return {"error": f"JSON_PARSE_ERROR: {str(e)}"}
    except Exception as e:
        return {"error": f"ADD_EDGE_ERROR: {str(e)}"}


# ---------------------------------------------------------------------------
# CLI Entry Point
# ---------------------------------------------------------------------------
def main() -> None:
    """Parse CLI subcommand args and dispatch to read/create/add-node/add-edge operations."""
    parser = argparse.ArgumentParser(description="Obsidian Canvas Architect")
    subparsers = parser.add_subparsers(dest='command', help='Commands')

    read_p = subparsers.add_parser('read', help='Read a .canvas file')
    read_p.add_argument('--file', required=True)

    create_p = subparsers.add_parser('create', help='Create a new canvas')
    create_p.add_argument('--file', required=True)

    node_p = subparsers.add_parser('add-node', help='Add a node')
    node_p.add_argument('--file', required=True)
    node_p.add_argument('--type', required=True, choices=['text', 'file', 'link', 'group'])
    node_p.add_argument('--text', help='Text content (for text nodes)')
    node_p.add_argument('--file-path', help='File path (for file nodes)')
    node_p.add_argument('--url', help='URL (for link nodes)')
    node_p.add_argument('--label', help='Label (for group nodes)')
    node_p.add_argument('--x', type=int, default=0)
    node_p.add_argument('--y', type=int, default=0)
    node_p.add_argument('--width', type=int, default=250)
    node_p.add_argument('--height', type=int, default=60)
    node_p.add_argument('--color', help='Node color')

    edge_p = subparsers.add_parser('add-edge', help='Add an edge')
    edge_p.add_argument('--file', required=True)
    edge_p.add_argument('--from-node', required=True)
    edge_p.add_argument('--to-node', required=True)
    edge_p.add_argument('--from-side', default='right', choices=VALID_SIDES)
    edge_p.add_argument('--to-side', default='left', choices=VALID_SIDES)
    edge_p.add_argument('--label', help='Edge label')

    args = parser.parse_args()

    if args.command == 'read':
        print(json.dumps(read_canvas(Path(args.file)), indent=2))
    elif args.command == 'create':
        print(json.dumps(create_canvas(Path(args.file)), indent=2))
    elif args.command == 'add-node':
        kwargs = {}
        if args.text: kwargs["text"] = args.text
        if args.file_path: kwargs["file_path"] = args.file_path
        if args.url: kwargs["url"] = args.url
        if args.label: kwargs["label"] = args.label
        if args.color: kwargs["color"] = args.color
        print(json.dumps(add_node(Path(args.file), args.type, args.x, args.y, args.width, args.height, **kwargs), indent=2))
    elif args.command == 'add-edge':
        print(json.dumps(add_edge(Path(args.file), args.from_node, args.to_node, args.from_side, args.to_side, args.label), indent=2))
    else:
        parser.print_help()


if __name__ == '__main__':
    main()
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall