From 4f92b9b89408f185739324013218d933d811c33c Mon Sep 17 00:00:00 2001 From: Lukas Gold Date: Wed, 23 Sep 2026 10:54:40 +0200 Subject: [PATCH] docs(skill): note the CLI and MCP prerequisite and version skew - SKILL.md: new "What this skill needs" section, with an `osw schema --help` preflight and a stop instruction when neither the CLI nor an MCP tool is present - SKILL.md: new "Troubleshooting" section, comparing `metadata.version` against `osw --version`; nothing checks this automatically - SKILL.md: shorter description, keeping the triggers and dropping the list of covered sections - docs/tools/cli.md: the plugin marketplace path installs the skill file only, not the package or the MCP server --- docs/tools/cli.md | 4 ++++ src/osw/skills/osl-tasks/SKILL.md | 29 ++++++++++++++++++++++++++++- 2 files changed, 32 insertions(+), 1 deletion(-) diff --git a/docs/tools/cli.md b/docs/tools/cli.md index 51f820b2..87892de5 100644 --- a/docs/tools/cli.md +++ b/docs/tools/cli.md @@ -113,3 +113,7 @@ Install it one of two ways: `/plugin install osl-tasks`. A new Claude Code session picks it up with no further action. + +Path 2 installs the skill file only. The skill drives the `osw` CLI and the +MCP server, so install the package separately, and register the MCP server as +described in [MCP server](mcp.md). diff --git a/src/osw/skills/osl-tasks/SKILL.md b/src/osw/skills/osl-tasks/SKILL.md index 5df59133..bbbfc218 100644 --- a/src/osw/skills/osl-tasks/SKILL.md +++ b/src/osw/skills/osl-tasks/SKILL.md @@ -1,6 +1,6 @@ --- name: osl-tasks -description: Use when importing local todo or note files into an OpenSemanticLab (OSL) wiki as Task entities, or when listing, filtering and updating tasks that already live in OSL. Drives the generic entity, schema and search operations of the `osw` CLI and MCP server; there are no task-specific commands. Covers the Task, Person and Project category page names, how to read the status and priority vocabularies from the schema, the update-by-uuid rule, the duplicate rule and the link marker written back into the local file. +description: Use when importing local todo or note files into an OpenSemanticLab (OSL) wiki as Task entities, or when listing, filtering and updating tasks that already live in OSL. Requires the `osw` CLI or the osw MCP server. metadata: version: "2.8.0" --- @@ -18,6 +18,17 @@ mistakes silently produce a wrong result. Commands are shown in CLI form. Each one has an MCP tool with the same parameters; the tool name is given in the table below. +## What this skill needs + +This skill calls the `osw` CLI or the osw MCP server, and installing the skill +file or the `osl-tasks` plugin installs neither of them. Run `osw schema +--help` first. It fails when the CLI is missing, and when it is old enough to +lack the command groups below. It does not tell you whether the version +matches this file. Troubleshooting covers that. If it fails and this session +has no osw MCP tool, ask the +user to install the `osw` package, plus the `mcp` extra and a registered +server for the MCP tools. Then stop. + ## When to use this skill - Importing todos or notes from a local file into OSL. @@ -339,3 +350,19 @@ and reversible. A skipped todo is silent and loses work. update, not create. - Anything weaker than an exact label match is a candidate. Show the candidates to the user and let them decide. Do not resolve it yourself. + +## Troubleshooting + +Nothing checks that this file and the installed `osw` package come from the +same release, although both versions are set together when a release is made. +Compare `metadata.version` in this file's frontmatter with the version that +`osw --version` prints. With the MCP server and no CLI, ask the user for the +version of the `osw` package that serves it. + +If the two differ, this file can describe operations, flags or field names +that the installed package does not have, or omit ones it does have. +Reinstall with `osw skill install --force`, or update the `osl-tasks` plugin, +or update the `osw` package, until both report the same version. + +If this file's frontmatter has no `metadata.version` at all, the copy is older +than the release that added that field. Reinstall it.