Skip to content

Commit 46d648d

Browse files
cybaeacybaea
authored
feat: add new skills for Obsidian JSON Canvas, Bases, Markdown, and CLI, and update existing agent definitions. (#304)
1 parent 72d3b03 commit 46d648d

12 files changed

Lines changed: 1794 additions & 17 deletions

File tree

‎.agents/skills/defuddle/SKILL.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
name: defuddle
3+
description: Extract clean markdown content from web pages using Defuddle CLI, removing clutter and navigation to save tokens. Use instead of WebFetch when the user provides a URL to read or analyze, for online documentation, articles, blog posts, or any standard web page.
4+
---
5+
6+
# Defuddle
7+
8+
Use Defuddle CLI to extract clean readable content from web pages. Prefer over WebFetch for standard web pages — it removes navigation, ads, and clutter, reducing token usage.
9+
10+
If not installed: `npm install -g defuddle`
11+
12+
## Usage
13+
14+
Always use `--md` for markdown output:
15+
16+
```bash
17+
defuddle parse <url> --md
18+
```
19+
20+
Save to file:
21+
22+
```bash
23+
defuddle parse <url> --md -o content.md
24+
```
25+
26+
Extract specific metadata:
27+
28+
```bash
29+
defuddle parse <url> -p title
30+
defuddle parse <url> -p description
31+
defuddle parse <url> -p domain
32+
```
33+
34+
## Output formats
35+
36+
| Flag | Format |
37+
|------|--------|
38+
| `--md` | Markdown (default choice) |
39+
| `--json` | JSON with both HTML and markdown |
40+
| (none) | HTML |
41+
| `-p <name>` | Specific metadata property |

‎.agents/skills/json-canvas/SKILL.md‎

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
---
2+
name: json-canvas
3+
description: Create and edit JSON Canvas files (.canvas) with nodes, edges, groups, and connections. Use when working with .canvas files, creating visual canvases, mind maps, flowcharts, or when the user mentions Canvas files in Obsidian.
4+
---
5+
6+
# JSON Canvas Skill
7+
8+
## File Structure
9+
10+
A canvas file (`.canvas`) contains two top-level arrays following the [JSON Canvas Spec 1.0](https://jsoncanvas.org/spec/1.0/):
11+
12+
```json
13+
{
14+
"nodes": [],
15+
"edges": []
16+
}
17+
```
18+
19+
- `nodes` (optional): Array of node objects
20+
- `edges` (optional): Array of edge objects connecting nodes
21+
22+
## Common Workflows
23+
24+
### 1. Create a New Canvas
25+
26+
1. Create a `.canvas` file with the base structure `{"nodes": [], "edges": []}`
27+
2. Generate unique 16-character hex IDs for each node (e.g., `"6f0ad84f44ce9c17"`)
28+
3. Add nodes with required fields: `id`, `type`, `x`, `y`, `width`, `height`
29+
4. Add edges referencing valid node IDs via `fromNode` and `toNode`
30+
5. **Validate**: Parse the JSON to confirm it is valid. Verify all `fromNode`/`toNode` values exist in the nodes array
31+
32+
### 2. Add a Node to an Existing Canvas
33+
34+
1. Read and parse the existing `.canvas` file
35+
2. Generate a unique ID that does not collide with existing node or edge IDs
36+
3. Choose position (`x`, `y`) that avoids overlapping existing nodes (leave 50-100px spacing)
37+
4. Append the new node object to the `nodes` array
38+
5. Optionally add edges connecting the new node to existing nodes
39+
6. **Validate**: Confirm all IDs are unique and all edge references resolve to existing nodes
40+
41+
### 3. Connect Two Nodes
42+
43+
1. Identify the source and target node IDs
44+
2. Generate a unique edge ID
45+
3. Set `fromNode` and `toNode` to the source and target IDs
46+
4. Optionally set `fromSide`/`toSide` (top, right, bottom, left) for anchor points
47+
5. Optionally set `label` for descriptive text on the edge
48+
6. Append the edge to the `edges` array
49+
7. **Validate**: Confirm both `fromNode` and `toNode` reference existing node IDs
50+
51+
### 4. Edit an Existing Canvas
52+
53+
1. Read and parse the `.canvas` file as JSON
54+
2. Locate the target node or edge by `id`
55+
3. Modify the desired attributes (text, position, color, etc.)
56+
4. Write the updated JSON back to the file
57+
5. **Validate**: Re-check all ID uniqueness and edge reference integrity after editing
58+
59+
## Nodes
60+
61+
Nodes are objects placed on the canvas. Array order determines z-index: first node = bottom layer, last node = top layer.
62+
63+
### Generic Node Attributes
64+
65+
| Attribute | Required | Type | Description |
66+
|-----------|----------|------|-------------|
67+
| `id` | Yes | string | Unique 16-char hex identifier |
68+
| `type` | Yes | string | `text`, `file`, `link`, or `group` |
69+
| `x` | Yes | integer | X position in pixels |
70+
| `y` | Yes | integer | Y position in pixels |
71+
| `width` | Yes | integer | Width in pixels |
72+
| `height` | Yes | integer | Height in pixels |
73+
| `color` | No | canvasColor | Preset `"1"`-`"6"` or hex (e.g., `"#FF0000"`) |
74+
75+
### Text Nodes
76+
77+
| Attribute | Required | Type | Description |
78+
|-----------|----------|------|-------------|
79+
| `text` | Yes | string | Plain text with Markdown syntax |
80+
81+
```json
82+
{
83+
"id": "6f0ad84f44ce9c17",
84+
"type": "text",
85+
"x": 0,
86+
"y": 0,
87+
"width": 400,
88+
"height": 200,
89+
"text": "# Hello World\n\nThis is **Markdown** content."
90+
}
91+
```
92+
93+
**Newline pitfall**: Use `\n` for line breaks in JSON strings. Do **not** use the literal `\\n` -- Obsidian renders that as the characters `\` and `n`.
94+
95+
### File Nodes
96+
97+
| Attribute | Required | Type | Description |
98+
|-----------|----------|------|-------------|
99+
| `file` | Yes | string | Path to file within the system |
100+
| `subpath` | No | string | Link to heading or block (starts with `#`) |
101+
102+
```json
103+
{
104+
"id": "a1b2c3d4e5f67890",
105+
"type": "file",
106+
"x": 500,
107+
"y": 0,
108+
"width": 400,
109+
"height": 300,
110+
"file": "Attachments/diagram.png"
111+
}
112+
```
113+
114+
### Link Nodes
115+
116+
| Attribute | Required | Type | Description |
117+
|-----------|----------|------|-------------|
118+
| `url` | Yes | string | External URL |
119+
120+
```json
121+
{
122+
"id": "c3d4e5f678901234",
123+
"type": "link",
124+
"x": 1000,
125+
"y": 0,
126+
"width": 400,
127+
"height": 200,
128+
"url": "https://obsidian.md"
129+
}
130+
```
131+
132+
### Group Nodes
133+
134+
Groups are visual containers for organizing other nodes. Position child nodes inside the group's bounds.
135+
136+
| Attribute | Required | Type | Description |
137+
|-----------|----------|------|-------------|
138+
| `label` | No | string | Text label for the group |
139+
| `background` | No | string | Path to background image |
140+
| `backgroundStyle` | No | string | `cover`, `ratio`, or `repeat` |
141+
142+
```json
143+
{
144+
"id": "d4e5f6789012345a",
145+
"type": "group",
146+
"x": -50,
147+
"y": -50,
148+
"width": 1000,
149+
"height": 600,
150+
"label": "Project Overview",
151+
"color": "4"
152+
}
153+
```
154+
155+
## Edges
156+
157+
Edges connect nodes via `fromNode` and `toNode` IDs.
158+
159+
| Attribute | Required | Type | Default | Description |
160+
|-----------|----------|------|---------|-------------|
161+
| `id` | Yes | string | - | Unique identifier |
162+
| `fromNode` | Yes | string | - | Source node ID |
163+
| `fromSide` | No | string | - | `top`, `right`, `bottom`, or `left` |
164+
| `fromEnd` | No | string | `none` | `none` or `arrow` |
165+
| `toNode` | Yes | string | - | Target node ID |
166+
| `toSide` | No | string | - | `top`, `right`, `bottom`, or `left` |
167+
| `toEnd` | No | string | `arrow` | `none` or `arrow` |
168+
| `color` | No | canvasColor | - | Line color |
169+
| `label` | No | string | - | Text label |
170+
171+
```json
172+
{
173+
"id": "0123456789abcdef",
174+
"fromNode": "6f0ad84f44ce9c17",
175+
"fromSide": "right",
176+
"toNode": "a1b2c3d4e5f67890",
177+
"toSide": "left",
178+
"toEnd": "arrow",
179+
"label": "leads to"
180+
}
181+
```
182+
183+
## Colors
184+
185+
The `canvasColor` type accepts either a hex string or a preset number:
186+
187+
| Preset | Color |
188+
|--------|-------|
189+
| `"1"` | Red |
190+
| `"2"` | Orange |
191+
| `"3"` | Yellow |
192+
| `"4"` | Green |
193+
| `"5"` | Cyan |
194+
| `"6"` | Purple |
195+
196+
Preset color values are intentionally undefined -- applications use their own brand colors.
197+
198+
## ID Generation
199+
200+
Generate 16-character lowercase hexadecimal strings (64-bit random value):
201+
202+
```
203+
"6f0ad84f44ce9c17"
204+
"a3b2c1d0e9f8a7b6"
205+
```
206+
207+
## Layout Guidelines
208+
209+
- Coordinates can be negative (canvas extends infinitely)
210+
- `x` increases right, `y` increases down; position is the top-left corner
211+
- Space nodes 50-100px apart; leave 20-50px padding inside groups
212+
- Align to grid (multiples of 10 or 20) for cleaner layouts
213+
214+
| Node Type | Suggested Width | Suggested Height |
215+
|-----------|-----------------|------------------|
216+
| Small text | 200-300 | 80-150 |
217+
| Medium text | 300-450 | 150-300 |
218+
| Large text | 400-600 | 300-500 |
219+
| File preview | 300-500 | 200-400 |
220+
| Link preview | 250-400 | 100-200 |
221+
222+
## Validation Checklist
223+
224+
After creating or editing a canvas file, verify:
225+
226+
1. All `id` values are unique across both nodes and edges
227+
2. Every `fromNode` and `toNode` references an existing node ID
228+
3. Required fields are present for each node type (`text` for text nodes, `file` for file nodes, `url` for link nodes)
229+
4. `type` is one of: `text`, `file`, `link`, `group`
230+
5. `fromSide`/`toSide` values are one of: `top`, `right`, `bottom`, `left`
231+
6. `fromEnd`/`toEnd` values are one of: `none`, `arrow`
232+
7. Color presets are `"1"` through `"6"` or valid hex (e.g., `"#FF0000"`)
233+
8. JSON is valid and parseable
234+
235+
If validation fails, check for duplicate IDs, dangling edge references, or malformed JSON strings (especially unescaped newlines in text content).
236+
237+
## Complete Examples
238+
239+
See [references/EXAMPLES.md](references/EXAMPLES.md) for full canvas examples including mind maps, project boards, research canvases, and flowcharts.
240+
241+
## References
242+
243+
- [JSON Canvas Spec 1.0](https://jsoncanvas.org/spec/1.0/)
244+
- [JSON Canvas GitHub](https://github.com/obsidianmd/jsoncanvas)

0 commit comments

Comments
 (0)