diff --git a/app/assets/css/main.css b/app/assets/css/main.css index 8049366..8392108 100644 --- a/app/assets/css/main.css +++ b/app/assets/css/main.css @@ -214,7 +214,7 @@ :where(main) h1::before { content: "#"; - margin-right: 0.4rem; + margin-right: 0.4rem !important; color: var(--docs-marker); font-family: var(--docs-font-mono); font-size: 0.48em; @@ -252,7 +252,7 @@ :where(main) h2 > a:first-child::before, :where(main) h3 > a:first-child::before { display: inline-block; - margin-right: 0.55rem; + margin-right: 0.9rem !important; color: var(--docs-marker); font-family: var(--docs-font-mono); font-size: 0.55em; diff --git a/content/08.integrations/11.skills.md b/content/08.integrations/11.skills.md index d313876..f3c370c 100644 --- a/content/08.integrations/11.skills.md +++ b/content/08.integrations/11.skills.md @@ -3,156 +3,115 @@ title: Agent Skills description: Pre-built skills that teach AI agents how to use Basic Memory effectively. --- -Agent skills are markdown instruction files (`SKILL.md`) that teach AI coding agents best practices for using Basic Memory's MCP tools. Your agent already has access to the tools — skills teach it *when* and *how* to use them effectively, with examples and patterns for specific workflows. -The skills are open source and live in the basic-memory monorepo — browse the full collection in [`skills/`](https://github.com/basicmachines-co/basic-memory/tree/main/skills). (The former `basic-memory-skills` repository is now just a distribution target; development happens in the monorepo.) +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. ::tip -Skills work with Claude Desktop, Claude Code, Cursor, Windsurf, and any agent that supports markdown-based skill files. +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. :: --- -## Installation +## Install a skill in Claude or ChatGPT -### npx (Recommended) +### Add the skill to Claude -`npx` ships with Node.js — if you don't have it, [install Node.js](https://nodejs.org/en/download) first. +1. [Choose a skill](#choose-a-skill) from the list below. +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. +4. Turn the skill on. -Install all skills at once: +[See Claude's walkthrough with screenshots](https://support.claude.com/en/articles/12512180-getting-started-with-skills-on-claude-ai). -```bash -npx skills add basicmachines-co/basic-memory/skills -``` - -Or install a single skill: - -```bash -npx skills add basicmachines-co/basic-memory/skills --skill memory-tasks -``` +### Add the skill to ChatGPT -Target a specific agent, or list what's available first: - -```bash -npx skills add basicmachines-co/basic-memory/skills --agent claude -npx skills add basicmachines-co/basic-memory/skills --list -``` - -::note -If your installed Skills CLI can't load `basicmachines-co/basic-memory/skills`, update the CLI or copy the `memory-*` directories manually (see below). -:: +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. -### Claude Desktop - -1. Open **Settings → Capabilities** -2. Enable **Code execution** and **Skills** -3. Upload the `SKILL.md` files from each skill folder - -### Manual - -Clone the repo and copy skill folders to your agent's skills directory: - -```bash -git clone https://github.com/basicmachines-co/basic-memory.git -cp -r basic-memory/skills/memory-notes ~/.claude/skills/ -``` - -For project-scoped skills, copy to `.claude/skills/` in your project root instead. +[See the ChatGPT skills walkthrough](https://help.openai.com/en/articles/20001066-skills-in-chatgpt). --- -## Using skills - -You don't need special syntax — once installed, skills activate when your request matches what they teach. Asking "where did we leave off?" pulls in `memory-continue`; pasting a meeting transcript triggers `memory-ingest`. - -When you want a specific behavior, name the skill in plain language: - -```text -"Use the /memory-notes skill to write up what we just discussed." -"Use /memory-continue to pick up where we left off on the auth refactor." -"Run /memory-defrag on my knowledge base and tell me what you'd clean up." -"Use /memory-research to look into Model Context Protocol and save what you find." -``` - -In Claude Code and Codex, installed skills are also literal slash commands — typing `/memory-notes` on its own invokes it directly. - ---- +## Choose a skill -## Available Skills +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. | Skill | Purpose | |-------|---------| -| **memory-notes** | Core note format — frontmatter, observations, relations, memory:// URLs | -| **memory-capture** | Capture the state of a working thread into a single coherent note | -| **memory-continue** | Resume prior work by rebuilding context from the knowledge graph | -| **memory-tasks** | Structured task tracking that survives context compaction | -| **memory-schema** | Schema lifecycle — infer, validate, create definitions, detect drift | -| **memory-curate** | Find orphan notes, propose relations, merge duplicates, build hub notes | -| **memory-reflect** | Review conversations, extract insights, consolidate knowledge | -| **memory-defrag** | Split bloated files, merge duplicates, restructure hierarchy | -| **memory-lifecycle** | Status transitions through folder-based organization, archive-never-delete | -| **memory-metadata-search** | Query notes by custom frontmatter fields (equality, range, array filters) | -| **memory-ingest** | Process transcripts, emails, and documents into structured notes | -| **memory-research** | Web research synthesized into knowledge entities | -| **memory-literary-analysis** | Analyze a complete literary work into a structured knowledge graph | +| [**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 | ::note -Start with **memory-notes** — it covers foundational note-writing patterns that all other skills build on. +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). :: -### Core Skills - -**memory-notes** — The foundation. Teaches proper note structure: frontmatter, semantic observation categories, relations with wiki-links, and memory:// URL usage. Install this first. +--- -**memory-tasks** — Structured task tracking with typed Task notes. Tasks survive context compaction, making this essential for multi-step work that spans beyond a single context window. +## Install skills in a coding agent -**memory-schema** — Schema lifecycle management. Discovers unschemaed notes, infers schemas from existing content, creates and edits definitions, validates notes against schemas, and detects drift. +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. -**memory-capture** — Captures the state of a working thread into a single coherent note — synthesizing where it landed, not an append-log. Re-captures rewrite the same note in place. +### Install with npx -**memory-continue** — Resumes prior work by rebuilding context from the knowledge graph — `build_context` via memory:// URLs, recent activity, and search. The "where were we?" skill. +Install all Basic Memory skills: -### Knowledge Maintenance +```bash +npx skills add basicmachines-co/basic-memory/skills +``` -**memory-reflect** — Inspired by sleep-time compute patterns. Reviews recent conversations, extracts insights, and consolidates them into your knowledge base. Works well as a scheduled daily or twice-daily routine. +Or install one skill: -**memory-defrag** — Memory defragmentation. Splits bloated files, merges duplicates, removes stale information, and restructures folder hierarchy. Run weekly or when your knowledge base feels disorganized. +```bash +npx skills add basicmachines-co/basic-memory/skills --skill memory-onboarding +``` -**memory-lifecycle** — Entity lifecycle management. Manages status transitions through folder-based organization with an archive-never-delete philosophy — information is preserved through moves, not removal. +List the available skills: -**memory-curate** — Knowledge-graph curation. Finds orphan notes and suggests links, proposes typed relations, merges duplicates, audits tags and folders, and builds hub notes. +```bash +npx skills add basicmachines-co/basic-memory/skills --list +``` -### Advanced Workflows +::note +If the command cannot load `basicmachines-co/basic-memory/skills`, update the Skills CLI or install manually. +:: -**memory-metadata-search** — Structured metadata search. Query notes by custom frontmatter fields using equality, range, array, and nested filters. Useful for finding notes by status, priority, or any custom YAML fields. +### Install manually -**memory-ingest** — Processes unstructured external input into structured entities. Parses meeting transcripts, conversation logs, and pasted documents into properly formatted Basic Memory notes. +Clone the repo and copy a skill folder into your agent's skills directory. This example installs `memory-notes` for Claude Code: -**memory-research** — Performs web research and synthesizes findings into Basic Memory entities. Use for researching companies, people, technologies, or any topic you want to capture in your knowledge base. +```bash +git clone https://github.com/basicmachines-co/basic-memory.git +cp -r basic-memory/skills/memory-notes ~/.claude/skills/ +``` -**memory-literary-analysis** — Analyzes a complete literary work into a structured knowledge graph — characters, themes, chapters, locations, symbols, and literary devices. +For a project-scoped Claude Code skill, copy it to `.claude/skills/` in your project root. --- -## Recommended Combinations - -**Developers** — `memory-notes` + `memory-tasks` + `memory-schema` -:br -Core note writing, task tracking across sessions, and schema consistency for project documentation. +## Use a skill -**Researchers** — `memory-notes` + `memory-research` + `memory-ingest` -:br -Capture web research and process external documents into structured knowledge. +Skills activate automatically when your request matches what they teach. You can also name the skill directly: -**Knowledge Maintenance** — `memory-notes` + `memory-defrag` + `memory-lifecycle` + `memory-reflect` -:br -Keep your knowledge base organized with regular reflection, defragmentation, and lifecycle management. - -**Everything** — Install the full set for comprehensive memory management across capture, ingestion, organization, reflection, and lifecycle. - -```bash -npx skills add basicmachines-co/basic-memory/skills +```text +"Use memory-onboarding to help me set up Basic Memory." +"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