From c40738a382c8c00c44c5351ebd8728ce974f1e36 Mon Sep 17 00:00:00 2001 From: Gowtham Date: Sun, 31 May 2026 13:40:55 -0600 Subject: [PATCH] Add official CLI skills --- README.md | 23 ++++++-- docs/api.html | 1 + docs/cli.html | 2 +- docs/concepts.html | 1 + docs/contributing.html | 1 + docs/getting-started.html | 1 + docs/index.html | 4 +- docs/mcp.html | 5 ++ docs/memory-contract.html | 1 + docs/obsidian.html | 1 + docs/scale.html | 1 + docs/security.html | 1 + docs/skills.html | 108 ++++++++++++++++++++++++++++++++++ docs/team-security.html | 1 + docs/troubleshooting.html | 1 + docs/ui.html | 1 + docs/why-link.html | 1 + skills/link-health/SKILL.md | 34 +++++++++++ skills/link-ingest/SKILL.md | 28 +++++++++ skills/link-memory/SKILL.md | 37 ++++++++++++ skills/link-retrieve/SKILL.md | 32 ++++++++++ tests/test_official_skills.py | 74 +++++++++++++++++++++++ 22 files changed, 353 insertions(+), 6 deletions(-) create mode 100644 docs/skills.html create mode 100644 skills/link-health/SKILL.md create mode 100644 skills/link-ingest/SKILL.md create mode 100644 skills/link-memory/SKILL.md create mode 100644 skills/link-retrieve/SKILL.md create mode 100644 tests/test_official_skills.py diff --git a/README.md b/README.md index 6431b1a..f0862af 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,7 @@ Website · Quick start · MCP setup · + Skills · CLI · MCP Registry · PyPI · @@ -166,15 +167,15 @@ The public scale model is documented at bounded by default, how to measure your own wiki, and where the current local limits are. -## Three Ways To Use Link +## Ways To Use Link Pick the surface that matches how you work. They all read and write the same local Markdown wiki. These surfaces are independent. `lnk serve` / `serve.py` is only the local web -viewer. CLI commands and MCP tools read the same `wiki/` files directly, so -Claude, Codex, Kiro, Cursor, or another MCP client can use Link even when the -web viewer is not running. +viewer. CLI commands, official skills, and MCP tools read the same `wiki/` files +directly, so Claude, Codex, Kiro, Cursor, or another agent can use Link even +when the web viewer is not running. @@ -196,6 +197,19 @@ web viewer is not running.
+Prefer skills instead of MCP? Link ships small, lazy-loadable CLI skills under +`skills/`. They let an agent use `lnk health`, `lnk query`, `lnk ingest-status`, +and `lnk remember` directly, without MCP setup or a running web viewer. + +```text +skills/link-health/SKILL.md +skills/link-retrieve/SKILL.md +skills/link-ingest/SKILL.md +skills/link-memory/SKILL.md +``` + +Full guide: [Link Skills](https://gowtham0992.github.io/link/skills.html). + ## Install For Your Agent Run one installer from the cloned checkout: @@ -449,6 +463,7 @@ More detail: [Security guide](https://gowtham0992.github.io/link/security.html). | Understand raw/wiki/memory | [Concepts](https://gowtham0992.github.io/link/concepts.html) | | Configure MCP | [MCP setup](https://gowtham0992.github.io/link/mcp.html) | | Find a command | [CLI reference](https://gowtham0992.github.io/link/cli.html) | +| Use Link without MCP setup | [Official skills](https://gowtham0992.github.io/link/skills.html) | | Use local HTTP endpoints | [HTTP API](https://gowtham0992.github.io/link/api.html) | | Review security boundaries | [Security model](https://gowtham0992.github.io/link/security.html) | | Evaluate Link for a small team | [Team security review](https://gowtham0992.github.io/link/team-security.html) | diff --git a/docs/api.html b/docs/api.html index 16e8e6a..c00e689 100644 --- a/docs/api.html +++ b/docs/api.html @@ -27,6 +27,7 @@ MCP Contract CLI + Skills API Security Contribute diff --git a/docs/cli.html b/docs/cli.html index 5576cf6..9211565 100644 --- a/docs/cli.html +++ b/docs/cli.html @@ -59,7 +59,7 @@

CLI Tour

Animated Link CLI walkthrough
Status, query, brief, and benchmark are the core terminal loop.
-

The CLI is independent of the web viewer. Use lnk query, lnk brief, lnk health, and maintenance commands even when lnk serve is not running.

+

The CLI is independent of the web viewer. Use lnk query, lnk brief, lnk health, and maintenance commands even when lnk serve is not running. Agents that support lazy-loaded instructions can also use the official Link skills instead of MCP setup.

Use lnk try when you want the shortest proof loop: demo creation, readiness, query proof, brief proof, viewer command, and first agent prompts in one command.

Daily Loop

diff --git a/docs/concepts.html b/docs/concepts.html index 65c4a3d..ae47992 100644 --- a/docs/concepts.html +++ b/docs/concepts.html @@ -27,6 +27,7 @@ MCP Contract CLI + Skills API Security Contribute diff --git a/docs/contributing.html b/docs/contributing.html index 0a97aeb..082402f 100644 --- a/docs/contributing.html +++ b/docs/contributing.html @@ -27,6 +27,7 @@ MCP Contract CLI + Skills API Security Contribute diff --git a/docs/getting-started.html b/docs/getting-started.html index 58f7d45..aebc237 100644 --- a/docs/getting-started.html +++ b/docs/getting-started.html @@ -27,6 +27,7 @@ MCP Contract CLI + Skills API Security Contribute diff --git a/docs/index.html b/docs/index.html index 0d45351..a01193b 100644 --- a/docs/index.html +++ b/docs/index.html @@ -27,6 +27,7 @@ MCP Contract CLI + Skills API Security Contribute @@ -219,7 +220,7 @@

Agents get a small set of reliable moves.

Read next

Start small, then make it your agent memory.

-

The docs are arranged by user path: try the demo, understand the model, wire MCP, then use the CLI and maintenance tools when you need them.

+

The docs are arranged by user path: try the demo, understand the model, choose MCP or skills, then use the CLI and maintenance tools when you need them.

First 10 minutes

Run the demo, add one source, save one direct memory, and verify the loop.

Why Link?

Understand where Link fits versus notes apps, hosted memory APIs, agent runtimes, and graph memory systems.

@@ -227,6 +228,7 @@

Start small, then make it your agent memory.

Concepts

Understand raw sources, wiki pages, memories, graph indexes, and budgeted query packets.

MCP setup

Install the MCP server and teach local agents how to use Link reliably.

CLI reference

Every local command, grouped by daily workflow and maintenance jobs.

+

Official skills

Use lazy-loadable CLI workflows when MCP setup is more than you need.

HTTP API

Local endpoints for status, query, memory, graph, validation, and web UI actions.

Security model

Local-first constraints, secret scanning, backup behavior, and HTTP safety boundaries.

Team security review

Deployment patterns, audit exports, Git sharing, approval gates, and current limits for small teams.

diff --git a/docs/mcp.html b/docs/mcp.html index cd7d637..085e575 100644 --- a/docs/mcp.html +++ b/docs/mcp.html @@ -27,6 +27,7 @@ MCP Contract CLI + Skills API Security Contribute @@ -63,6 +64,10 @@

MCP Tour

MCP does not need serve.py The local web viewer is only for humans. MCP clients start python -m link_mcp --wiki ... over stdio and read the same Markdown wiki directly.
+
+ Prefer no MCP? + Use the official Link skills when an agent can run local CLI commands and you want a lazy-loaded workflow instead of MCP configuration. +

For agent builders, the stable read/write behavior is summarized in the Link memory contract.

Agent Installers

diff --git a/docs/memory-contract.html b/docs/memory-contract.html index 08e52f6..b06b7d1 100644 --- a/docs/memory-contract.html +++ b/docs/memory-contract.html @@ -27,6 +27,7 @@ MCP Contract CLI + Skills API Security Contribute diff --git a/docs/obsidian.html b/docs/obsidian.html index 2d5f960..74c7f35 100644 --- a/docs/obsidian.html +++ b/docs/obsidian.html @@ -27,6 +27,7 @@ MCP Contract CLI + Skills API Security Contribute diff --git a/docs/scale.html b/docs/scale.html index c8e233b..403edba 100644 --- a/docs/scale.html +++ b/docs/scale.html @@ -27,6 +27,7 @@ MCP Contract CLI + Skills API Security Contribute diff --git a/docs/security.html b/docs/security.html index b459a2c..87f7d95 100644 --- a/docs/security.html +++ b/docs/security.html @@ -27,6 +27,7 @@ MCP Contract CLI + Skills API Security Contribute diff --git a/docs/skills.html b/docs/skills.html new file mode 100644 index 0000000..8400477 --- /dev/null +++ b/docs/skills.html @@ -0,0 +1,108 @@ + + + + + + + Link - Skills + + + + + + + + + + + + + +
+
+ No MCP required +

Lazy-load Link through skills.

+

Official skills are small CLI workflows an agent can load only when needed: health, retrieval, ingest, and memory lifecycle.

+
+
+ +
+
+ +
+

Why Skills

+

MCP gives Link structured tool calls, but it should not be the only path. If an agent can run local commands, it can use Link through lnk without an MCP server, background viewer, or extra client configuration. From a source checkout, the same workflows work with python3 link.py.

+
+ lnk serve is optional +

The web viewer is only for humans. Skills, CLI commands, and MCP tools all read the same local Markdown wiki directly.

+
+ +

Included Skills

+

The repo ships official skill folders under skills/:

+ + + + + + + + + + +
SkillUse it forFirst command
link-healthReadiness, interrupted writes, backups, repair, validation.lnk health
link-retrieveBounded query packets, briefs, graph summaries, benchmarks.lnk query "..."
link-ingestRaw source ingest, stale sources, memory proposals, post-ingest checks.lnk ingest-status
link-memoryRemember, recall, review, explain, update, archive, restore, forget.lnk brief "..."
+ +

Use Them

+

Point your agent at the skill folder it supports, or copy the relevant SKILL.md into that agent's local skill directory.

+ 
skills/link-health/SKILL.md
+skills/link-retrieve/SKILL.md
+skills/link-ingest/SKILL.md
+skills/link-memory/SKILL.md
+

Then use natural prompts that map to the skills:

+ 
is Link ready?
+brief me from Link before we continue
+query Link for the release process
+ingest raw/notes.md into Link
+remember that I prefer short release notes
+ +

Rules For Agents

+
    +
  • Prefer lnk health when readiness is unclear.
    • +
  • Prefer lnk query, lnk brief, and lnk graph-summary over reading the whole wiki.
    • +
  • Use lnk ingest-status before touching raw sources.
    • +
  • Do not silently create durable memory; use lnk remember only when the user asks or approves a proposal.
    • +
  • Run lnk validate and lnk health after ingest or broad wiki edits.
    • +
+

Use MCP when you want structured tool calls inside an MCP client. Use skills when you want a lightweight, lazy-loaded CLI workflow.

+
+
+
+ + + + diff --git a/docs/team-security.html b/docs/team-security.html index b83b9ea..e158657 100644 --- a/docs/team-security.html +++ b/docs/team-security.html @@ -27,6 +27,7 @@ MCP Contract CLI + Skills API Security Contribute diff --git a/docs/troubleshooting.html b/docs/troubleshooting.html index 9c28456..f570f74 100644 --- a/docs/troubleshooting.html +++ b/docs/troubleshooting.html @@ -27,6 +27,7 @@ MCP Contract CLI + Skills API Security Contribute diff --git a/docs/ui.html b/docs/ui.html index fa15e61..f090400 100644 --- a/docs/ui.html +++ b/docs/ui.html @@ -27,6 +27,7 @@ MCP Contract CLI + Skills API Security Contribute diff --git a/docs/why-link.html b/docs/why-link.html index baada86..830b96c 100644 --- a/docs/why-link.html +++ b/docs/why-link.html @@ -27,6 +27,7 @@ MCP Contract CLI + Skills API Security Contribute diff --git a/skills/link-health/SKILL.md b/skills/link-health/SKILL.md new file mode 100644 index 0000000..2d6640d --- /dev/null +++ b/skills/link-health/SKILL.md @@ -0,0 +1,34 @@ +--- +name: link-health +description: Use when a user wants to verify Link readiness, troubleshoot a local wiki, inspect interrupted writes, repair generated indexes, or back up Link without setting up MCP. +--- + +# Link Health + +Use the `lnk` CLI. In a source checkout, replace `lnk` with `python3 link.py`. MCP and the local web viewer are optional; `lnk serve` is only for humans to browse the wiki. + +1. Check readiness first: + ```bash + lnk health [link-root] + ``` +2. If the output mentions interrupted or stale operations, inspect them before repair: + ```bash + lnk operations [link-root] + ``` +3. Before broad repairs, migrations, or restore work, create a backup: + ```bash + lnk backup [link-root] + ``` +4. Repair only generated or structural state that Link reports as safe: + ```bash + lnk doctor --fix [link-root] + lnk rebuild-index [link-root] + lnk rebuild-backlinks [link-root] + ``` +5. Validate before saying the wiki is healthy: + ```bash + lnk validate [link-root] + lnk health [link-root] + ``` + +If the user asks whether MCP is ready, run `lnk verify-mcp [link-root]`. Do not start `lnk serve` for MCP or CLI work. diff --git a/skills/link-ingest/SKILL.md b/skills/link-ingest/SKILL.md new file mode 100644 index 0000000..977eba5 --- /dev/null +++ b/skills/link-ingest/SKILL.md @@ -0,0 +1,28 @@ +--- +name: link-ingest +description: Use when a user asks to ingest raw files into Link, refresh stale source pages, propose memories from sources, or validate source-backed wiki updates through the CLI without MCP. +--- + +# Link Ingest + +Use `lnk ingest-status` as the source of truth. In a source checkout, replace `lnk` with `python3 link.py`. The command tells you which raw files need work and which checks must run next. + +1. Inspect the ingest plan: + ```bash + lnk ingest-status [link-root] + ``` +2. If Link reports secret-looking values, unreadable files, or unsafe paths, stop and ask the user to fix or redact them. +3. Read only the pending raw files named by the ingest plan. Create or update one `wiki/sources/...` page per raw file, and update existing concept/entity/exploration/memory pages before creating thin duplicates. +4. Keep durable memory proposal-only until the user approves it: + ```bash + lnk propose-memories raw/ [link-root] + ``` +5. After writing wiki pages, rebuild generated indexes and validate: + ```bash + lnk rebuild-index [link-root] + lnk rebuild-backlinks [link-root] + lnk validate [link-root] + lnk health [link-root] + ``` + +Do not put raw source contents into chat unless needed for the current ingest task. Preserve source paths and provenance on generated pages. diff --git a/skills/link-memory/SKILL.md b/skills/link-memory/SKILL.md new file mode 100644 index 0000000..33ebca9 --- /dev/null +++ b/skills/link-memory/SKILL.md @@ -0,0 +1,37 @@ +--- +name: link-memory +description: Use when a user asks an agent to remember, recall, review, update, archive, restore, forget, or explain local Link memories through the CLI without requiring MCP. +--- + +# Link Memory + +Use explicit memory operations. In a source checkout, replace `lnk` with `python3 link.py`. Do not silently save durable memory; only remember when the user asks or approves a proposal. + +1. Prime before work: + ```bash + lnk brief "" [link-root] + ``` +2. Recall specific memory: + ```bash + lnk recall "" [link-root] + ``` +3. Save an explicit memory: + ```bash + lnk remember "" [link-root] --type note --scope user + ``` + Use `--project ` for project-scoped memory, `--visibility private|project|team` for sharing intent, `--review-after YYYY-MM-DD` for stale-risk memories, and `--expires-at YYYY-MM-DD` for temporary context. +4. Review and explain before trusting uncertain memory: + ```bash + lnk memory-inbox [link-root] + lnk explain-memory [link-root] + lnk review-memory [link-root] + ``` +5. Change lifecycle safely: + ```bash + lnk update-memory "" [link-root] + lnk archive-memory [link-root] --reason "" + lnk restore-memory [link-root] + lnk forget-memory [link-root] --confirm + ``` + +When duplicate or conflict warnings appear, prefer updating, reviewing, or archiving existing memory over creating another page. diff --git a/skills/link-retrieve/SKILL.md b/skills/link-retrieve/SKILL.md new file mode 100644 index 0000000..3daaff6 --- /dev/null +++ b/skills/link-retrieve/SKILL.md @@ -0,0 +1,32 @@ +--- +name: link-retrieve +description: Use when a user asks an agent to search, answer from, summarize, brief from, or navigate Link context through the CLI without loading the whole wiki or configuring MCP. +--- + +# Link Retrieve + +Use bounded CLI commands so the agent does not dump the whole wiki into context. In a source checkout, replace `lnk` with `python3 link.py`. + +1. If readiness is unclear, start with: + ```bash + lnk health [link-root] + ``` +2. For most questions, use a compact query packet: + ```bash + lnk query "" [link-root] --budget small + ``` + Increase to `--budget medium` or `--budget large` only when the packet says more context is needed. +3. Before longer work, prime from memory: + ```bash + lnk brief "" [link-root] + ``` +4. For graph context, stay bounded: + ```bash + lnk graph-summary "" [link-root] --limit 40 --depth 1 + ``` +5. For performance checks, use: + ```bash + lnk benchmark "" [link-root] --budget small + ``` + +Do not enumerate every page or request the full graph unless the user explicitly asks for an export or exhaustive audit. diff --git a/tests/test_official_skills.py b/tests/test_official_skills.py new file mode 100644 index 0000000..462357d --- /dev/null +++ b/tests/test_official_skills.py @@ -0,0 +1,74 @@ +import unittest +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] +SKILLS_DIR = ROOT / "skills" + +EXPECTED_SKILLS = { + "link-health": ("lnk health", "lnk operations", "lnk backup", "lnk validate"), + "link-retrieve": ("lnk query", "lnk brief", "lnk graph-summary", "lnk benchmark"), + "link-ingest": ("lnk ingest-status", "lnk propose-memories", "lnk rebuild-index", "lnk validate"), + "link-memory": ("lnk brief", "lnk recall", "lnk remember", "lnk memory-inbox"), +} + + +def read_skill(name: str) -> str: + return (SKILLS_DIR / name / "SKILL.md").read_text(encoding="utf-8") + + +def parse_frontmatter(text: str) -> dict[str, str]: + if not text.startswith("---\n"): + return {} + _, frontmatter, _body = text.split("---", 2) + parsed: dict[str, str] = {} + for line in frontmatter.splitlines(): + if ":" not in line: + continue + key, value = line.split(":", 1) + parsed[key.strip()] = value.strip() + return parsed + + +class OfficialSkillsTests(unittest.TestCase): + def test_expected_skills_exist_with_valid_frontmatter(self): + for name in EXPECTED_SKILLS: + with self.subTest(skill=name): + path = SKILLS_DIR / name / "SKILL.md" + self.assertTrue(path.exists(), f"missing official skill: {path}") + + frontmatter = parse_frontmatter(read_skill(name)) + self.assertEqual(frontmatter.get("name"), name) + self.assertGreaterEqual(len(frontmatter.get("description", "")), 60) + + def test_skills_are_cli_backed_and_lazy_loadable(self): + forbidden_claims = ( + "mcp is required", + "requires mcp", + "start the mcp server", + "must run `lnk serve`", + "must run lnk serve", + ) + for name, commands in EXPECTED_SKILLS.items(): + with self.subTest(skill=name): + text = read_skill(name) + lower = text.lower() + self.assertIn("lnk", text) + self.assertIn("[link-root]", text) + self.assertIn("MCP", text) + for command in commands: + self.assertIn(command, text) + for forbidden in forbidden_claims: + self.assertNotIn(forbidden, lower) + + def test_docs_and_readme_reference_official_skills(self): + readme = (ROOT / "README.md").read_text(encoding="utf-8") + docs = (ROOT / "docs/skills.html").read_text(encoding="utf-8") + + self.assertIn("https://gowtham0992.github.io/link/skills.html", readme) + self.assertIn("Lazy-load Link through skills", docs) + for name in EXPECTED_SKILLS: + with self.subTest(skill=name): + skill_path = f"skills/{name}/SKILL.md" + self.assertIn(skill_path, readme) + self.assertIn(skill_path, docs)