@qvac/skills 0.0.0 → 0.1.1

package/skills/apple-notes/references/write.md

@@ -0,0 +1,105 @@
+# Creating, Editing, and Deleting Notes
+
+Four bundled operations cover every change. Run one per `exec` call as
+`osascript {{SKILL_DIR}}/<file>.applescript <args...>`.
+
+| Request                         | Command                                                          |
+| ------------------------------- | ---------------------------------------------------------------- |
+| "add a note"                    | `create-note.applescript "Title" '<h1>Title</h1>...'`             |
+| "add to note X"                 | `append-note.applescript "X" '<p>...</p>'`                        |
+| "rewrite / replace note X"      | search for its id, then `edit-note.applescript "<id>" '<h1>…'`   |
+| "delete note X"                 | search for its id, then `delete-note.applescript "<id>"`         |
+
+## Getting a Note's Id
+
+Edit and delete are id-based, not name-based (names collide). Get the stable
+CoreData id from `search-notes.applescript` (argv: query) — it returns one
+`<id>\t<name>` line per matching note. Run it ONCE, then use the id.
+
+```bash
+osascript {{SKILL_DIR}}/search-notes.applescript "Daily Log"
+```
+
+## Create a Note
+
+Apple Notes bodies are HTML, so they contain double quotes (e.g. `href="..."`).
+ALWAYS pass the title and body as ARGUMENTS to `create-note.applescript` (argv:
+name, body, optional folder). Wrap the HTML body in SINGLE quotes at the shell
+level so its double quotes need no escaping. Never embed a body inside
+`osascript -e '...'`: three nested quoting layers drop the closing `"`/`}` and
+produce `syntax error: Expected "}"` and no note.
+
+Plain note in the default folder:
+
+```bash
+osascript {{SKILL_DIR}}/create-note.applescript "What is Bitcoin?" '<h1>What is Bitcoin?</h1><p>Bitcoin is <strong>digital gold</strong>. See <a href="https://bitcoin.org/">bitcoin.org</a>.</p>'
+```
+
+In a specific folder (pass the folder name as a third argument):
+
+```bash
+osascript {{SKILL_DIR}}/create-note.applescript "Sprint Planning" '<h1>Sprint Planning</h1><p>Items:</p><ul><li>Item 1</li></ul>' "Work"
+```
+
+A note whose whole content is one line of text: that text IS the title, so the
+body is the `<h1>` alone. Adding a `<p>` copy of it shows the text twice.
+
+```bash
+osascript {{SKILL_DIR}}/create-note.applescript "Buy milk and eggs" '<h1>Buy milk and eggs</h1>'
+```
+
+Rules:
+
+- Use `<h1>` for the title (it shows as the note's first line), `<p>` for
+  paragraphs, `<ul>/<li>` for lists, `<b>/<i>` for emphasis. The `name`
+  argument names the note without adding a line to the body.
+- Write every piece of content ONCE. Never follow the `<h1>` title with a `<p>`
+  that restates it — the note then shows the same text twice.
+- The HTML body MUST be wrapped in single quotes `'...'`. HTML attribute quotes
+  (`"`) are then safe and need NO backslash escaping.
+- If the body must contain an apostrophe `'`, close-escape-reopen it:
+  `...don'\''t...`.
+
+## Append to a Note
+
+Pass the note name and the HTML fragment to append to
+`append-note.applescript` (argv: noteName, htmlFragment):
+
+```bash
+osascript {{SKILL_DIR}}/append-note.applescript "Daily Log" '<p>New entry: ...</p>'
+```
+
+## Edit a Note
+
+Get the id first (see above), then pass the id and the COMPLETE replacement
+body to `edit-note.applescript` (argv: noteId, replacementBody):
+
+```bash
+osascript {{SKILL_DIR}}/edit-note.applescript "x-coredata://.../ICNote/p67" '<h1>Daily Log</h1><p>Updated content</p>'
+```
+
+The replacement body must include the title as its first heading or line;
+replacing `body` without it also replaces the note's visible title.
+
+## Delete a Note
+
+Get the id first (see above), then pass it to `delete-note.applescript` (argv:
+noteId):
+
+```bash
+osascript {{SKILL_DIR}}/delete-note.applescript "x-coredata://.../ICNote/p67"
+```
+
+Deletion moves the note to Recently Deleted; the user can restore it from Notes
+for 30 days. Confirm the target with the user before deleting — there is no undo
+prompt.
+
+## Common Mistakes
+
+- Treating the body as plain text — it is HTML. Use HTML tags in the body argument.
+- Repeating the title inside the body — write it once as the leading `<h1>`.
+- Embedding an HTML body inside `osascript -e '...'` — the nested quotes break.
+  Use the bundled script and pass name/body as arguments.
+- Forgetting to wrap the HTML body argument in single quotes — its `"` attribute
+  quotes will then break the shell command.
+- Editing or deleting by name — both need the id from `search-notes.applescript`.

package/skills/apple-notes/search-notes.applescript

@@ -0,0 +1,21 @@
+-- Find notes whose name or body contains a term. argv: query
+-- An empty query returns EVERY note (list-all) — AppleScript's `contains ""` is
+-- false, so the empty case is handled explicitly rather than via the filter.
+-- Emits one match per line as `id<tab>name`, so the caller can then read by
+-- name or edit/delete by the stable id (there is no other bundled way to get
+-- a note's id). The query binds as data via argv, never into the script text.
+on run argv
+  set q to item 1 of argv
+  set out to ""
+  tell application "Notes"
+    if q is "" then
+      set matches to every note
+    else
+      set matches to every note whose name contains q or body contains q
+    end if
+    repeat with n in matches
+      set out to out & (id of n) & tab & (name of n) & linefeed
+    end repeat
+  end tell
+  return out
+end run

package/skills/apple-reminders/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: apple-reminders
+description: Manage Apple Reminders through the local remindctl CLI — view, create, complete, and delete reminders, and manage lists, with date filters and JSON/plain output. macOS only.
+tools: [exec(remindctl)]
+platform: [darwin]
+metadata:
+  {
+    "openclaw":
+      {
+        "requires": { "bins": ["remindctl"] },
+        "install":
+          [
+            {
+              "id": "homebrew",
+              "kind": "shell",
+              "bins": ["brew"],
+              "manual": true,
+              "label": "Install Homebrew",
+              "command": "/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\""
+            },
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/remindctl",
+              "bins": ["remindctl"],
+              "label": "Install remindctl via Homebrew"
+            },
+            {
+              "id": "authorize",
+              "kind": "shell",
+              "command": "remindctl authorize",
+              "label": "Grant Reminders access"
+            }
+          ],
+        "setup":
+          {
+            "summary": "Apple Reminders works through the remindctl CLI. Install it with Homebrew, then grant Reminders access once.",
+            "routes":
+              [
+                {
+                  "kind": "install",
+                  "label": "Install remindctl",
+                  "helpUrl": "https://github.com/steipete/remindctl",
+                  "steps":
+                    [
+                      "Install Homebrew if you don't have it.",
+                      "Run: brew install steipete/tap/remindctl",
+                      "Run: remindctl authorize and allow Reminders access.",
+                      "Reopen this Skills page — apple-reminders should show as ready."
+                    ]
+                }
+              ]
+          }
+      }
+  }
+---
+
+# Apple Reminders
+
+Manage Apple Reminders through the local `remindctl` CLI. The CLI talks to the
+macOS Reminders app and its lists, so reminders created here sync to the user's
+iPhone and iPad.
+
+## Load the Recipe File First
+
+This file carries no commands. The working commands live in two reference files
+— load the one for the job with the `skill` tool BEFORE calling `exec`, then
+copy its command and change only the arguments:
+
+Each load is a real `skill` tool call — printing the call as JSON or text in
+your reply loads nothing.
+
+- **Viewing reminders and lists** — "what are my reminders", "what's due
+  today / tomorrow / this week", "what's overdue", "show my lists", "show my
+  Work reminders": call the `skill` tool with `name: "apple-reminders"` and
+  `file: "references/view.md"`.
+- **Changing reminders and lists** — "remind me to X", "add X to my Y list",
+  "mark N done", "delete reminder", "create / delete a list": call the `skill`
+  tool with `name: "apple-reminders"` and `file: "references/edit.md"`. It also
+  covers finding the id a complete or delete needs.
+
+Most requests are ONE command. Run that single command with `exec`, then answer
+from its output.
+
+## Always Use the remindctl CLI — Never Shell Out
+
+Reminders live in the macOS Reminders database. ALWAYS view and edit them with
+`remindctl` commands via the `exec` tool. NEVER use `cat`, `ls`, `find`, `grep`,
+`sqlite3`, filesystem paths, or AppleScript to reach the Reminders store — those
+bypass `remindctl` and are wrong even when they appear to work. If a `remindctl`
+command fails, correct its arguments and retry the `remindctl` command; do not
+switch to shell or file tools.
+
+Use `exec` only, one `remindctl` command per call. Do not chain with `&&`, `;`,
+or pipes.
+
+## When to Use
+
+- The user explicitly mentions "reminder" or the "Reminders app".
+- Creating personal to-dos with due dates that should sync to iPhone/iPad.
+- Viewing or managing Apple Reminders lists.
+
+## When NOT to Use
+
+- Calendar events or appointments — those are not Reminders.
+- Project or work task tracking — use Notion, GitHub Issues, or the task queue.
+- The user says "remind me" but means a local alert or notification in this
+  app, not the Reminders app — ask: "Do you want this in Apple Reminders (syncs
+  to your phone) or as a local alert here?" and use this skill only for the
+  Apple Reminders answer.
+- Notes — use Obsidian, Notion, or Apple Notes.
+
+## Setup and Availability
+
+- macOS only. On any other platform, report that Apple Reminders is unavailable
+  and stop.
+- Requires the `remindctl` binary: `brew install steipete/tap/remindctl`.
+- The Reminders app must have granted access. Check with `remindctl status`;
+  request access with `remindctl authorize`.
+- If a command fails because `remindctl` is missing or access is not granted,
+  report that clearly and ask the user to install or authorize — do not fall
+  back to another tool.
+
+## Output Policy
+
+- Keep results small: the reminder title, its list, and its due date.
+- After a successful command, finish with a concise visible answer.
+- Do not dump every list or the full reminder database unless the user
+  explicitly asks.

package/skills/apple-reminders/cli.schema.json

@@ -0,0 +1,201 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "x-positionals": [
+    "date"
+  ],
+  "properties": {
+    "date": {
+      "type": "string"
+    },
+    "json": {
+      "type": "boolean"
+    },
+    "plain": {
+      "type": "boolean"
+    },
+    "quiet": {
+      "type": "boolean"
+    },
+    "today": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "json": {
+          "type": "boolean"
+        },
+        "plain": {
+          "type": "boolean"
+        },
+        "quiet": {
+          "type": "boolean"
+        }
+      },
+      "x-effect": "read"
+    },
+    "tomorrow": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "json": {
+          "type": "boolean"
+        },
+        "plain": {
+          "type": "boolean"
+        },
+        "quiet": {
+          "type": "boolean"
+        }
+      },
+      "x-effect": "read"
+    },
+    "week": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "json": {
+          "type": "boolean"
+        },
+        "plain": {
+          "type": "boolean"
+        },
+        "quiet": {
+          "type": "boolean"
+        }
+      },
+      "x-effect": "read"
+    },
+    "overdue": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "json": {
+          "type": "boolean"
+        },
+        "plain": {
+          "type": "boolean"
+        },
+        "quiet": {
+          "type": "boolean"
+        }
+      },
+      "x-effect": "read"
+    },
+    "all": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "json": {
+          "type": "boolean"
+        },
+        "plain": {
+          "type": "boolean"
+        },
+        "quiet": {
+          "type": "boolean"
+        }
+      },
+      "x-effect": "read"
+    },
+    "list": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "create": {
+          "type": "boolean"
+        },
+        "delete": {
+          "type": "boolean"
+        },
+        "json": {
+          "type": "boolean"
+        },
+        "plain": {
+          "type": "boolean"
+        },
+        "quiet": {
+          "type": "boolean"
+        }
+      },
+      "x-positionals": [
+        "name"
+      ]
+    },
+    "add": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "title": {
+          "type": "string"
+        },
+        "list": {
+          "type": "string"
+        },
+        "due": {
+          "type": "string"
+        },
+        "json": {
+          "type": "boolean"
+        },
+        "plain": {
+          "type": "boolean"
+        },
+        "quiet": {
+          "type": "boolean"
+        }
+      },
+      "x-positionals": [
+        "title"
+      ]
+    },
+    "complete": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "ids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "x-rest": "ids"
+    },
+    "delete": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "force": {
+          "type": "boolean"
+        },
+        "ids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "x-positionals": [
+        "id"
+      ],
+      "x-rest": "ids"
+    },
+    "status": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {},
+      "x-effect": "read"
+    },
+    "authorize": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {}
+    }
+  }
+}

package/skills/apple-reminders/references/edit.md

@@ -0,0 +1,69 @@
+# Creating, Completing, and Deleting Reminders
+
+One `remindctl` command per `exec` call, no chaining. Run `add` in the
+foreground (the default): the exit code confirms whether the reminder was
+created — never claim success unless the command succeeded.
+
+| Request                          | Command                                          |
+| -------------------------------- | ------------------------------------------------ |
+| "remind me to X"                 | `remindctl add --title "X"`                      |
+| "remind me to X tomorrow"        | `remindctl add --title "X" --due tomorrow`       |
+| "add X to my <List> list"        | `remindctl add --title "X" --list Personal`      |
+| "mark X done"                    | `remindctl all --json` for its id, then `remindctl complete <id>` |
+| "delete reminder X"              | `remindctl all --json` for its id, then `remindctl delete <id> --force` |
+| "create a list called X"         | `remindctl list X --create`                      |
+| "delete the list X"              | `remindctl list X --delete`                      |
+
+## Create reminders
+
+```bash
+remindctl add "Buy milk"
+remindctl add --title "Call mom" --list Personal --due tomorrow
+remindctl add --title "Meeting prep" --due "2026-02-15 09:00"
+```
+
+`--due` accepts `today`, `tomorrow`, `YYYY-MM-DD`, `YYYY-MM-DD HH:mm`, and ISO
+8601 (`2026-01-04T12:34:56Z`). Without `--list` the reminder lands in the
+default list.
+
+## Finding the id
+
+`complete` and `delete` take reminder ids, and there is NO search command —
+`remindctl search`, `remindctl show`, `remindctl find` all fail. Get the id
+from a JSON view: `remindctl all --json` lists every reminder in every list,
+including completed ones, one object per reminder with `id`, `title`,
+`listName`, `dueDate`, `isCompleted`. Pick the entry whose `title` matches
+what the user named and copy its `id` (a short prefix like `4A83` is enough).
+Narrow with `remindctl list <Name> --json` or `remindctl today --json` when the
+list or day is known.
+
+```bash
+remindctl all --json
+remindctl list Personal --json
+```
+
+## Complete / delete
+
+```bash
+remindctl complete 4A83
+remindctl complete 1 2 3
+remindctl delete 4A83 --force
+```
+
+Only delete a reminder when the user explicitly asks; prefer `complete` for
+finished to-dos. `--force` skips the confirmation prompt, which cannot be
+answered from `exec`.
+
+## Lists
+
+```bash
+remindctl list Projects --create
+remindctl list Work --delete
+```
+
+## Answering
+
+Only the commands shown in this file exist; if one fails, fix its arguments
+rather than inventing another subcommand. Confirm with the title, list, and due date of what changed. If the command
+fails because `remindctl` is missing or access is denied, report that and ask
+the user to install or authorize; never switch to another tool.

package/skills/apple-reminders/references/view.md

@@ -0,0 +1,58 @@
+# Viewing Reminders and Lists
+
+One `remindctl` command per `exec` call, no chaining. Pick the command from the
+request and answer from its output.
+
+| Request                                  | Command                     |
+| ---------------------------------------- | --------------------------- |
+| "what are my reminders" / "due today"    | `remindctl today`           |
+| "what's due tomorrow" / "this week"      | `remindctl tomorrow` · `remindctl week` |
+| "what's overdue"                         | `remindctl overdue`         |
+| "everything" / "all my reminders"        | `remindctl all`             |
+| "what's due on <date>"                   | `remindctl 2026-01-04`      |
+| "show my reminder lists"                 | `remindctl list`            |
+| "show my <List> reminders"               | `remindctl list Work`       |
+
+## View by date
+
+```bash
+remindctl today
+remindctl tomorrow
+remindctl week
+remindctl overdue
+remindctl all
+remindctl 2026-01-04
+```
+
+Date filters accept `today`, `tomorrow`, `yesterday`, `YYYY-MM-DD`,
+`YYYY-MM-DD HH:mm`, and ISO 8601 (`2026-01-04T12:34:56Z`).
+
+## Lists
+
+```bash
+remindctl list
+remindctl list Work
+```
+
+`remindctl list` alone names the lists; `remindctl list <Name>` shows the
+reminders in that list, including ones without a due date.
+
+## Output formats
+
+```bash
+remindctl today --json
+remindctl today --plain
+remindctl today --quiet
+```
+
+Use `--json` when you need structured fields (ids, due dates) before a
+follow-up command; the `id` field is what `complete` and `delete` take.
+`remindctl all --json` covers every list including completed reminders. There
+is no search command — filter the JSON view by `title` yourself.
+
+## Answering
+
+Report the title, its list, and its due date for each reminder — not the whole
+database. An empty result means nothing is due: say so plainly. If the command
+fails because `remindctl` is missing or access is denied, report that and ask
+the user to install or authorize; never switch to another tool.

package/skills/asana/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: asana
+description: Asana tasks, projects, and comments via the official Asana MCP server (OAuth). Also handles pasted app.asana.com task links.
+tools: [mcp_call]
+platform: [darwin, linux, win32]
+credentials: [asana_mcp_access_token]
+allow_list: [https://mcp.asana.com/v2/mcp]
+mcp_reads: [get_task, get_tasks, get_my_tasks, get_projects, search_tasks, search_objects]
+---
+
+# Asana
+
+One wired transport: the official Asana MCP server (v2), authorized with a pre-registered Asana OAuth app.
+
+Use the `mcp_call` tool against `https://mcp.asana.com/v2/mcp`. Authentication uses a pre-registered Asana MCP app (client ID and secret) with PKCE — the user connects "Asana" from the Asana skill's setup, which stores the access token under the credential key `asana_mcp_access_token`. If the credential is connected, act immediately and call the tool(s) — do NOT ask the user for a token. If the credential is missing (a tool result reports it), tell the user to connect "Asana"; do not attempt to drive OAuth yourself.
+
+Sessions are automatic: `mcp_call` runs the initialize handshake itself and threads the session for you. Do NOT call `initialize` or `notifications/initialized`, and do NOT pass `sessionId`.
+
+If a call returns `Status: 401`, the token is expired/invalid — tell the user to reconnect "Asana" from the Asana skill's setup.
+
+## Workflow
+
+Pass the **tool name as `method`** and the **tool's args as `params`** directly. The MCP `url` must be a top-level field beside `method` and `params` — never put `url` inside `params`. Do NOT build a `{ "name": …, "arguments": … }` envelope, and do NOT pass `tokenCredentialKey` — the runtime wraps the envelope and injects the bearer token by host for you.
+
+V2's tool set evolves. Call `tools/list` once before the first Asana operation in a conversation, then use the exact returned name and schema. Common tools include:
+
+| tool | use for |
+| --- | --- |
+| `get_my_tasks` | list tasks assigned to the connected user |
+| `get_tasks` / `search_tasks` | list or search tasks |
+| `get_task` | fetch one task |
+| `create_tasks` / `update_tasks` | create or update tasks |
+| `search_objects` | find projects, users, teams, tags, or portfolios |
+| `get_projects` | list projects in the authorized workspace |
+
+If a tool is absent, do not invent or fall back to a V1 `asana_*` name. Explain the V2 limitation. If a call returns an input validation error, use the `tools/list` schema and retry the same tool once.
+
+### Example: list my tasks
+
+```json
+{
+  "url": "https://mcp.asana.com/v2/mcp",
+  "method": "get_my_tasks",
+  "params": {}
+}
+```
+
+## Tool choice and pasted links
+
+- Use `mcp_call` only. NEVER use `http_request` for Asana, and NEVER fetch `app.asana.com` URLs — they serve the browser login page, not data.
+- When the user pastes an Asana link, extract the task gid and pass it to the matching MCP tool: the number after `/task/` (`…/project/<p>/task/1215448540812360` → `1215448540812360`), or the last path segment in the older `app.asana.com/0/<project>/<task>` form.
+
+## Output Policy
+
+- Always quote the task `gid` when reporting tasks back so follow-up actions stay deterministic.
+- Surface workspace and project names, not just GIDs, when human-friendly.
+- For list responses, show name, assignee, due date, and completion state. Fetch full detail only on request.
+- Confirm with the user before deleting anything — task deletion is permanent and takes subtasks with it.
+- Do not ask for or echo credentials in chat. If a tool result reports the credential is missing, tell the user to connect "Asana" from the Asana skill's setup.