diff --git a/content/02.whats-new/09.agent-skills.md b/content/02.whats-new/09.agent-skills.md index 97520bc..0077bb9 100644 --- a/content/02.whats-new/09.agent-skills.md +++ b/content/02.whats-new/09.agent-skills.md @@ -20,11 +20,13 @@ AI assistants are powerful, but they don't automatically know the best way to or ## Quick Install +In Claude Code, Codex, Cursor, and other coding agents: + ```bash -npx skills add basicmachines-co/basic-memory/skills +npx skills add basicmachines-co/basic-memory/skills -g ``` -Works with Claude Desktop, Claude Code, Cursor, Windsurf, and other AI tools that support markdown-based skill files. Installation options, per-agent targeting, and usage examples are on the [Agent Skills guide](/integrations/skills). +In Claude (claude.ai and Claude Desktop) or ChatGPT, download the combined `basic-memory.zip` skill (or `basic-memory-chatgpt.zip`) and upload it. Download links, per-skill ZIPs, and plan requirements are on the [Agent Skills guide](/integrations/skills). ## Next Steps diff --git a/content/08.integrations/11.skills.md b/content/08.integrations/11.skills.md index f3c370c..a1cba51 100644 --- a/content/08.integrations/11.skills.md +++ b/content/08.integrations/11.skills.md @@ -3,79 +3,72 @@ title: Agent Skills description: Pre-built skills that teach AI agents how to use Basic Memory effectively. --- -Agent skills are ready-made instructions that help Claude and ChatGPT use Basic Memory well. They teach your assistant when to save something, how to organize it, and how to pick up where you left off. +Agent skills are ready-made instructions that help your AI assistant use Basic Memory well. They teach it when to save something, how to organize it, and how to pick up where you left off. + +Pick the install path for the assistant you use: + +- **[Claude](#install-in-claude)** (claude.ai and Claude Desktop): upload [`basic-memory.zip`](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/basic-memory.zip). +- **[ChatGPT](#install-in-chatgpt)**: upload [`basic-memory-chatgpt.zip`](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/basic-memory-chatgpt.zip). +- **[Coding agents](#install-in-a-coding-agent)** (Claude Code, Codex, Cursor, and others): install from the terminal with `npx`. ::tip -New to Basic Memory? Start with [**memory-onboarding**](#choose-a-skill). It guides you through setting up a useful knowledge system by asking a few questions and doing the technical work for you. +New to Basic Memory? Once the skill is installed, ask your assistant to help you set up Basic Memory. The [**memory-onboarding**](#individual-skills-optional) guidance interviews you and builds a useful knowledge system for you. :: --- -## Install a skill in Claude or ChatGPT +## Install in Claude -### Add the skill to Claude +Skills work in claude.ai and Claude Desktop on the Free, Pro, Max, Team, and Enterprise plans. -1. [Choose a skill](#choose-a-skill) from the list below. +**Before you start:** turn on code execution in **Settings → Capabilities → Code execution and file creation**. Skills need it to run. On Enterprise, an organization owner must also enable Skills in **Organization settings → Plugins & skills**. + +1. Download [**basic-memory.zip**](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/basic-memory.zip). Don't unzip it. 2. Open **Customize → Skills** and click **+**. -3. Choose **Upload a skill** and select its `SKILL.md` file. For `memory-onboarding`, upload the packaged ZIP instead. +3. Choose **Create skill → Upload a skill** and select `basic-memory.zip`. 4. Turn the skill on. +`basic-memory.zip` is one combined skill: core Basic Memory guidance, plus the other skills that work with the hosted connector (notes, search, continue, capture, quest, comark, and more) as references Claude reads when it needs them. Claude takes one skill per upload, so this is the easiest way to get everything at once. If you only want one skill, upload its ZIP from [Individual skills](#individual-skills-optional) instead. + [See Claude's walkthrough with screenshots](https://support.claude.com/en/articles/12512180-getting-started-with-skills-on-claude-ai). -### Add the skill to ChatGPT +--- -1. [Choose a skill](#choose-a-skill) from the list below. -2. Click your **profile icon → Skills**. -3. Choose **New skill → Upload from your computer** and select its `SKILL.md` file. For `memory-onboarding`, upload the packaged ZIP instead. -4. Wait for ChatGPT to finish scanning it. +## Install in ChatGPT -[See the ChatGPT skills walkthrough](https://help.openai.com/en/articles/20001066-skills-in-chatgpt). +Uploading skills is available on ChatGPT Business, Enterprise, Healthcare, and Edu. A workspace admin must allow skill uploading. ---- - -## Choose a skill +1. Download [**basic-memory-chatgpt.zip**](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/basic-memory-chatgpt.zip). Don't unzip it. +2. Open **Plugins** and select the **Skills** tab. +3. Click **Create → Upload from your computer** and select `basic-memory-chatgpt.zip`. +4. Wait for ChatGPT to finish scanning it. -Most skills are a single `SKILL.md` file that you can upload directly. **memory-onboarding** includes supporting reference files, so it uses a packaged ZIP. +`basic-memory-chatgpt.zip` is the same combined skill as `basic-memory.zip`, plus an `agents/openai.yaml` file that gives it a name and card in ChatGPT. ChatGPT takes one skill per upload; for a single skill, upload its `-chatgpt.zip` from [Individual skills](#individual-skills-optional) instead. -| Skill | Purpose | -|-------|---------| -| [**memory-onboarding**](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-onboarding.zip) | Guided setup — interview, design, and build a complete knowledge system from scratch | -| [**memory-notes**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-notes/SKILL.md) | Core note format — frontmatter, observations, relations, memory:// URLs | -| [**memory-capture**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-capture/SKILL.md) | Capture the state of a working thread into a single coherent note | -| [**memory-continue**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-continue/SKILL.md) | Resume prior work by rebuilding context from the knowledge graph | -| [**memory-tasks**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-tasks/SKILL.md) | Structured task tracking that survives context compaction | -| [**memory-schema**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-schema/SKILL.md) | Schema lifecycle — infer, validate, create definitions, detect drift | -| [**memory-curate**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-curate/SKILL.md) | Find orphan notes, propose relations, merge duplicates, build hub notes | -| [**memory-reflect**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-reflect/SKILL.md) | Review conversations, extract insights, consolidate knowledge | -| [**memory-defrag**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-defrag/SKILL.md) | Split bloated files, merge duplicates, restructure hierarchy | -| [**memory-lifecycle**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-lifecycle/SKILL.md) | Status transitions through folder-based organization, archive-never-delete | -| [**memory-metadata-search**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-metadata-search/SKILL.md) | Query notes by custom frontmatter fields (equality, range, array filters) | -| [**memory-ingest**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-ingest/SKILL.md) | Process transcripts, emails, and documents into structured notes | -| [**memory-research**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-research/SKILL.md) | Web research synthesized into knowledge entities | -| [**memory-literary-analysis**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-literary-analysis/SKILL.md) | Analyze a complete literary work into a structured knowledge graph | +[See the ChatGPT skills walkthrough](https://help.openai.com/en/articles/20001066-skills-in-chatgpt). ::note -The skills are open source. You can read every `SKILL.md` file in the [Basic Memory skills collection](https://github.com/basicmachines-co/basic-memory/tree/main/skills). +ChatGPT Free, Plus, and Pro can't upload skills. You can still [connect Basic Memory Cloud to ChatGPT](/integrations/chatgpt) and add standing guidance as custom instructions; the [AI Assistant Guide](/reference/ai-assistant-guide) has a starting instruction block to paste in. :: --- -## Install skills in a coding agent - -If you use Claude Code or Codex, install skills from the terminal with `npx`. It ships with Node.js; [install Node.js](https://nodejs.org/en/download) first if needed. +## Install in a coding agent -### Install with npx +Claude Code, Codex, Cursor, and other coding agents can install skills from the terminal with `npx`. It ships with Node.js; [install Node.js](https://nodejs.org/en/download) first if needed. -Install all Basic Memory skills: +Install every Basic Memory skill: ```bash -npx skills add basicmachines-co/basic-memory/skills +npx skills add basicmachines-co/basic-memory/skills -g ``` +The `-g` flag installs the skills for your user account, so they're available in every project. Leave it off to install them into the current project only. + Or install one skill: ```bash -npx skills add basicmachines-co/basic-memory/skills --skill memory-onboarding +npx skills add basicmachines-co/basic-memory/skills --skill memory-onboarding -g ``` List the available skills: @@ -84,20 +77,55 @@ List the available skills: npx skills add basicmachines-co/basic-memory/skills --list ``` -::note -If the command cannot load `basicmachines-co/basic-memory/skills`, update the Skills CLI or install manually. -:: +Skills activate automatically when your request matches what they teach. You can also invoke one by name: -### Install manually +- **Claude Code:** `/memory-notes` +- **Codex:** `$memory-notes` -Clone the repo and copy a skill folder into your agent's skills directory. This example installs `memory-notes` for Claude Code: +### Install by hand + +If you'd rather not use `npx`, download [**basic-memory-skills.zip**](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/basic-memory-skills.zip) and unzip it into your agent's skills folder. It holds every skill as its own folder. For Claude Code: ```bash -git clone https://github.com/basicmachines-co/basic-memory.git -cp -r basic-memory/skills/memory-notes ~/.claude/skills/ +unzip basic-memory-skills.zip -d ~/.claude/skills/ ``` -For a project-scoped Claude Code skill, copy it to `.claude/skills/` in your project root. +[**basic-memory-skills-chatgpt.zip**](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/basic-memory-skills-chatgpt.zip) is the same bundle with `agents/openai.yaml` metadata in each skill, for Codex and other OpenAI tools. + +::note +Don't confuse the bundles with the combined skill. `basic-memory-skills.zip` and `basic-memory-skills-chatgpt.zip` are folders of many skills for unzipping by hand, and Claude and ChatGPT will reject them as uploads. `basic-memory.zip` and `basic-memory-chatgpt.zip` are a single skill made for uploading. +:: + +--- + +## Individual skills (optional) + +Most people should install the combined skill above. If you want just one skill, download its ZIP here and upload it the same way. Don't unzip it first. + +| Skill | Purpose | Claude | ChatGPT | +|-------|---------|--------|---------| +| **memory-onboarding** | Guided setup: interview, design, and build a complete knowledge system from scratch. | [memory-onboarding.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-onboarding.zip) | [memory-onboarding-chatgpt.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-onboarding-chatgpt.zip) | +| **memory-quest** | Finish Memory Quest Mission 8 by saving your Memory Master note. | [memory-quest.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-quest.zip) | [memory-quest-chatgpt.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-quest-chatgpt.zip) | +| **memory-notes** | Core note format: frontmatter, observations, relations, memory:// URLs. | [memory-notes.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-notes.zip) | [memory-notes-chatgpt.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-notes-chatgpt.zip) | +| **memory-capture** | Capture the state of a working thread into a single coherent note. | [memory-capture.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-capture.zip) | [memory-capture-chatgpt.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-capture-chatgpt.zip) | +| **memory-continue** | Resume prior work by rebuilding context from the knowledge graph. | [memory-continue.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-continue.zip) | [memory-continue-chatgpt.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-continue-chatgpt.zip) | +| **memory-tasks** | Structured task tracking that survives context compaction. | [memory-tasks.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-tasks.zip) | [memory-tasks-chatgpt.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-tasks-chatgpt.zip) | +| **memory-schema** | Schema lifecycle: infer, validate, create definitions, detect drift. | [memory-schema.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-schema.zip) | [memory-schema-chatgpt.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-schema-chatgpt.zip) | +| **memory-curate** | Find orphan notes, propose relations, merge duplicates, build hub notes. | [memory-curate.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-curate.zip) | [memory-curate-chatgpt.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-curate-chatgpt.zip) | +| **memory-comark** | Write notes that render as charts, tables, boards, and live dashboards. | [memory-comark.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-comark.zip) | [memory-comark-chatgpt.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-comark-chatgpt.zip) | +| **memory-lifecycle** | Status transitions through folder-based organization, archive-never-delete. | [memory-lifecycle.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-lifecycle.zip) | [memory-lifecycle-chatgpt.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-lifecycle-chatgpt.zip) | +| **memory-metadata-search** | Query notes by custom frontmatter fields (equality, range, array filters). | [memory-metadata-search.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-metadata-search.zip) | [memory-metadata-search-chatgpt.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-metadata-search-chatgpt.zip) | +| **memory-ingest** | Process transcripts, emails, and documents into structured notes. | [memory-ingest.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-ingest.zip) | [memory-ingest-chatgpt.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-ingest-chatgpt.zip) | +| **memory-research** | Web research synthesized into knowledge entities. | [memory-research.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-research.zip) | [memory-research-chatgpt.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-research-chatgpt.zip) | +| **memory-reflect** | Review conversations, extract insights, consolidate knowledge. *Requires local Basic Memory.* | [memory-reflect.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-reflect.zip) | [memory-reflect-chatgpt.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-reflect-chatgpt.zip) | +| **memory-defrag** | Split bloated files, merge duplicates, restructure hierarchy. *Requires local Basic Memory.* | [memory-defrag.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-defrag.zip) | [memory-defrag-chatgpt.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-defrag-chatgpt.zip) | +| **memory-literary-analysis** | Analyze a complete literary work into a structured knowledge graph. *Requires local Basic Memory.* | [memory-literary-analysis.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-literary-analysis.zip) | [memory-literary-analysis-chatgpt.zip](https://github.com/basicmachines-co/basic-memory/releases/download/skills-latest/memory-literary-analysis-chatgpt.zip) | + +Skills marked *Requires local Basic Memory* work with files on your computer or the `bm` command line, so they need a [local Basic Memory install](/local/local-install) rather than only the hosted connector. They aren't part of the combined `basic-memory.zip` skill. + +::note +The skills are open source. You can read every one in the [Basic Memory skills collection](https://github.com/basicmachines-co/basic-memory/tree/main/skills). +:: --- @@ -110,8 +138,6 @@ Skills activate automatically when your request matches what they teach. You can "Use memory-notes to write up what we just discussed." ``` -In Claude Code and Codex, you can also invoke an installed skill as a slash command, such as `/memory-notes`. - --- ## Next Steps diff --git a/content/10.reference/3.ai-assistant-guide.md b/content/10.reference/3.ai-assistant-guide.md index 13e39ef..1b0ffd3 100644 --- a/content/10.reference/3.ai-assistant-guide.md +++ b/content/10.reference/3.ai-assistant-guide.md @@ -13,11 +13,14 @@ There are three ways to give those instructions, from least to most effort. [Agent Skills](/integrations/skills) are packaged instructions that teach agents Basic Memory best practices — the note format, when to capture, how to search and resume work, schema workflows, and knowledge-base maintenance. If your client supports skills, this replaces hand-written guidance: +- **Claude** (claude.ai and Claude Desktop) and **ChatGPT**: download the combined skill, `basic-memory.zip` for Claude or `basic-memory-chatgpt.zip` for ChatGPT, and upload it. The [Agent Skills guide](/integrations/skills) has the download links and where to upload. +- **Coding agents** (Claude Code, Codex, Cursor, and others): install from the terminal. + ```bash -npx skills add basicmachines-co/basic-memory/skills +npx skills add basicmachines-co/basic-memory/skills -g ``` -That installs the full set. To start smaller, add just one: `npx skills add basicmachines-co/basic-memory/skills --skill memory-notes` — the core note-writing skill — and add others as you need them. +That installs the full set for your user account. To start smaller, add just one: `npx skills add basicmachines-co/basic-memory/skills --skill memory-notes -g` (the core note-writing skill), and add others as you need them. ---