Skip to content

Commit bd3a795

Browse files
phernandezphernandez
authored
Merge pull request #36 from basicmachines-co/codex/simplify-skills-page
docs(skills): simplify installation guide
2 parents 547cb45 + 7cc8e8d commit bd3a795

2 files changed

Lines changed: 67 additions & 108 deletions

File tree

‎app/assets/css/main.css‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -214,7 +214,7 @@
214214

215215
:where(main) h1::before {
216216
content: "#";
217-
margin-right: 0.4rem;
217+
margin-right: 0.4rem !important;
218218
color: var(--docs-marker);
219219
font-family: var(--docs-font-mono);
220220
font-size: 0.48em;
@@ -252,7 +252,7 @@
252252
:where(main) h2 > a:first-child::before,
253253
:where(main) h3 > a:first-child::before {
254254
display: inline-block;
255-
margin-right: 0.55rem;
255+
margin-right: 0.9rem !important;
256256
color: var(--docs-marker);
257257
font-family: var(--docs-font-mono);
258258
font-size: 0.55em;

‎content/08.integrations/11.skills.md‎

Lines changed: 65 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -3,156 +3,115 @@ title: Agent Skills
33
description: Pre-built skills that teach AI agents how to use Basic Memory effectively.
44
---
55

6-
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.
7-
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.)
6+
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.
87

98
::tip
10-
Skills work with Claude Desktop, Claude Code, Cursor, Windsurf, and any agent that supports markdown-based skill files.
9+
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.
1110
::
1211

1312
---
1413

15-
## Installation
14+
## Install a skill in Claude or ChatGPT
1615

17-
### npx (Recommended)
16+
### Add the skill to Claude
1817

19-
`npx` ships with Node.js — if you don't have it, [install Node.js](https://nodejs.org/en/download) first.
18+
1. [Choose a skill](#choose-a-skill) from the list below.
19+
2. Open **Customize → Skills** and click **+**.
20+
3. Choose **Upload a skill** and select its `SKILL.md` file. For `memory-onboarding`, upload the packaged ZIP instead.
21+
4. Turn the skill on.
2022

21-
Install all skills at once:
23+
[See Claude's walkthrough with screenshots](https://support.claude.com/en/articles/12512180-getting-started-with-skills-on-claude-ai).
2224

23-
```bash
24-
npx skills add basicmachines-co/basic-memory/skills
25-
```
26-
27-
Or install a single skill:
28-
29-
```bash
30-
npx skills add basicmachines-co/basic-memory/skills --skill memory-tasks
31-
```
25+
### Add the skill to ChatGPT
3226

33-
Target a specific agent, or list what's available first:
34-
35-
```bash
36-
npx skills add basicmachines-co/basic-memory/skills --agent claude
37-
npx skills add basicmachines-co/basic-memory/skills --list
38-
```
39-
40-
::note
41-
If your installed Skills CLI can't load `basicmachines-co/basic-memory/skills`, update the CLI or copy the `memory-*` directories manually (see below).
42-
::
27+
1. [Choose a skill](#choose-a-skill) from the list below.
28+
2. Click your **profile icon → Skills**.
29+
3. Choose **New skill → Upload from your computer** and select its `SKILL.md` file. For `memory-onboarding`, upload the packaged ZIP instead.
30+
4. Wait for ChatGPT to finish scanning it.
4331

44-
### Claude Desktop
45-
46-
1. Open **Settings → Capabilities**
47-
2. Enable **Code execution** and **Skills**
48-
3. Upload the `SKILL.md` files from each skill folder
49-
50-
### Manual
51-
52-
Clone the repo and copy skill folders to your agent's skills directory:
53-
54-
```bash
55-
git clone https://github.com/basicmachines-co/basic-memory.git
56-
cp -r basic-memory/skills/memory-notes ~/.claude/skills/
57-
```
58-
59-
For project-scoped skills, copy to `.claude/skills/` in your project root instead.
32+
[See the ChatGPT skills walkthrough](https://help.openai.com/en/articles/20001066-skills-in-chatgpt).
6033

6134
---
6235

63-
## Using skills
64-
65-
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`.
66-
67-
When you want a specific behavior, name the skill in plain language:
68-
69-
```text
70-
"Use the /memory-notes skill to write up what we just discussed."
71-
"Use /memory-continue to pick up where we left off on the auth refactor."
72-
"Run /memory-defrag on my knowledge base and tell me what you'd clean up."
73-
"Use /memory-research to look into Model Context Protocol and save what you find."
74-
```
75-
76-
In Claude Code and Codex, installed skills are also literal slash commands — typing `/memory-notes` on its own invokes it directly.
77-
78-
---
36+
## Choose a skill
7937

80-
## Available Skills
38+
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.
8139

8240
| Skill | Purpose |
8341
|-------|---------|
84-
| **memory-notes** | Core note format — frontmatter, observations, relations, memory:// URLs |
85-
| **memory-capture** | Capture the state of a working thread into a single coherent note |
86-
| **memory-continue** | Resume prior work by rebuilding context from the knowledge graph |
87-
| **memory-tasks** | Structured task tracking that survives context compaction |
88-
| **memory-schema** | Schema lifecycle — infer, validate, create definitions, detect drift |
89-
| **memory-curate** | Find orphan notes, propose relations, merge duplicates, build hub notes |
90-
| **memory-reflect** | Review conversations, extract insights, consolidate knowledge |
91-
| **memory-defrag** | Split bloated files, merge duplicates, restructure hierarchy |
92-
| **memory-lifecycle** | Status transitions through folder-based organization, archive-never-delete |
93-
| **memory-metadata-search** | Query notes by custom frontmatter fields (equality, range, array filters) |
94-
| **memory-ingest** | Process transcripts, emails, and documents into structured notes |
95-
| **memory-research** | Web research synthesized into knowledge entities |
96-
| **memory-literary-analysis** | Analyze a complete literary work into a structured knowledge graph |
42+
| [**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 |
43+
| [**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 |
44+
| [**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 |
45+
| [**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 |
46+
| [**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 |
47+
| [**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 |
48+
| [**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 |
49+
| [**memory-reflect**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-reflect/SKILL.md) | Review conversations, extract insights, consolidate knowledge |
50+
| [**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 |
51+
| [**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 |
52+
| [**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) |
53+
| [**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 |
54+
| [**memory-research**](https://github.com/basicmachines-co/basic-memory/raw/refs/heads/main/skills/memory-research/SKILL.md) | Web research synthesized into knowledge entities |
55+
| [**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 |
9756

9857
::note
99-
Start with **memory-notes** — it covers foundational note-writing patterns that all other skills build on.
58+
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).
10059
::
10160

102-
### Core Skills
103-
104-
**memory-notes** — The foundation. Teaches proper note structure: frontmatter, semantic observation categories, relations with wiki-links, and memory:// URL usage. Install this first.
61+
---
10562

106-
**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.
63+
## Install skills in a coding agent
10764

108-
**memory-schema** — Schema lifecycle management. Discovers unschemaed notes, infers schemas from existing content, creates and edits definitions, validates notes against schemas, and detects drift.
65+
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.
10966

110-
**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.
67+
### Install with npx
11168

112-
**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.
69+
Install all Basic Memory skills:
11370

114-
### Knowledge Maintenance
71+
```bash
72+
npx skills add basicmachines-co/basic-memory/skills
73+
```
11574

116-
**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.
75+
Or install one skill:
11776

118-
**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.
77+
```bash
78+
npx skills add basicmachines-co/basic-memory/skills --skill memory-onboarding
79+
```
11980

120-
**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.
81+
List the available skills:
12182

122-
**memory-curate** — Knowledge-graph curation. Finds orphan notes and suggests links, proposes typed relations, merges duplicates, audits tags and folders, and builds hub notes.
83+
```bash
84+
npx skills add basicmachines-co/basic-memory/skills --list
85+
```
12386

124-
### Advanced Workflows
87+
::note
88+
If the command cannot load `basicmachines-co/basic-memory/skills`, update the Skills CLI or install manually.
89+
::
12590

126-
**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.
91+
### Install manually
12792

128-
**memory-ingest** — Processes unstructured external input into structured entities. Parses meeting transcripts, conversation logs, and pasted documents into properly formatted Basic Memory notes.
93+
Clone the repo and copy a skill folder into your agent's skills directory. This example installs `memory-notes` for Claude Code:
12994

130-
**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.
95+
```bash
96+
git clone https://github.com/basicmachines-co/basic-memory.git
97+
cp -r basic-memory/skills/memory-notes ~/.claude/skills/
98+
```
13199

132-
**memory-literary-analysis** — Analyzes a complete literary work into a structured knowledge graph — characters, themes, chapters, locations, symbols, and literary devices.
100+
For a project-scoped Claude Code skill, copy it to `.claude/skills/` in your project root.
133101

134102
---
135103

136-
## Recommended Combinations
137-
138-
**Developers** — `memory-notes` + `memory-tasks` + `memory-schema`
139-
:br
140-
Core note writing, task tracking across sessions, and schema consistency for project documentation.
104+
## Use a skill
141105

142-
**Researchers** — `memory-notes` + `memory-research` + `memory-ingest`
143-
:br
144-
Capture web research and process external documents into structured knowledge.
106+
Skills activate automatically when your request matches what they teach. You can also name the skill directly:
145107

146-
**Knowledge Maintenance** — `memory-notes` + `memory-defrag` + `memory-lifecycle` + `memory-reflect`
147-
:br
148-
Keep your knowledge base organized with regular reflection, defragmentation, and lifecycle management.
149-
150-
**Everything** — Install the full set for comprehensive memory management across capture, ingestion, organization, reflection, and lifecycle.
151-
152-
```bash
153-
npx skills add basicmachines-co/basic-memory/skills
108+
```text
109+
"Use memory-onboarding to help me set up Basic Memory."
110+
"Use memory-notes to write up what we just discussed."
154111
```
155112

113+
In Claude Code and Codex, you can also invoke an installed skill as a slash command, such as `/memory-notes`.
114+
156115
---
157116

158117
## Next Steps

0 commit comments

Comments
 (0)