What I do

•Record and retrieve project learnings and insights
•Capture issue-specific notes and resolutions
•Build a growing, AI-searchable knowledge base
•Provide context about project architecture and decisions

When to use me

Use this skill when you need to:

•Record learnings: Capture new insights, patterns, or best practices discovered during development
•Track issues: Add notes to ongoing or resolved issues
•Query knowledge: Search for previous decisions, learnings, or solutions
•Maintain context: Build institutional memory for the project

How it works

This skill provides a unified knowledge management system. You install the skill once, and it manages knowledge across all your projects using qmd collections:

code

# The qmd-knowledge skill (installed to your AI tool's skills directory)
# Location varies by tool: ~/.config/opencode/skill/, ~/.claude/skills/, or ~/.config/amp/skills/
├── SKILL.md              # This file - the skill definition
├── scripts/              # Executable scripts
│   └── record.sh         # Record learnings/issues/notes
└── references/           # Example structure and READMEs

# Project knowledge storage (managed by the skill)
~/.ai-knowledges/
├── <project-name>/       # Collection for your project
│   ├── learnings/
│   └── issues/
└── another-project/      # Collection for another project
    ├── learnings/
    └── issues/

The qmd MCP server provides AI-powered search across all stored knowledge, allowing your AI assistant to autonomously query and update the knowledge base.

Available scripts

Recording knowledge

bash

# Record a learning (use the skill's script)
$SKILL_PATH/scripts/record.sh learning "qmd MCP integration"

# Add a note to an issue
$SKILL_PATH/scripts/record.sh issue 123 "Fixed by updating dependencies"

# Record a general note
$SKILL_PATH/scripts/record.sh note "Consider using agent skills for extensibility"

Querying knowledge

Use the qmd MCP server tools directly from Claude or OpenCode:

bash

# Fast keyword search
qmd search "MCP servers" -c <project-name>

# Semantic search with AI embeddings
qmd vsearch "how to configure MCP"

# Hybrid search with reranking (best quality)
qmd query "MCP server configuration"

# Get specific document
qmd get "references/learnings/2024-01-26-qmd-integration.md"

# Search with minimum score filter
qmd search "API" --all --files --min-score 0.3 -c <project-name>

Setup

•

Install qmd:

bash

bun install -g https://github.com/tobi/qmd

•

Install the skill:

bash

# The skill is installed to your AI tool's skills directory:
# - OpenCode: ~/.config/opencode/skill/qmd-knowledge/
# - Claude Code: ~/.claude/skills/qmd-knowledge/
# - Amp: ~/.config/amp/skills/qmd-knowledge/

•
Configure MCP server (see installation docs for Claude/OpenCode/Amp)

•

Create a knowledge collection for your project:

bash

# The skill's record.sh script will auto-detect the project name when executed.
# For manual setup, use your desired project name consistently in the commands below.
# Optional: export QMD_PROJECT=<project-name> to override auto-detection

# Create storage directory for your project (replace <project-name> with your project)
mkdir -p ~/.ai-knowledges/<project-name>/learnings
mkdir -p ~/.ai-knowledges/<project-name>/issues

# Add qmd collection
qmd collection add ~/.ai-knowledges/<project-name> --name <project-name>
qmd context add qmd://<project-name> "Knowledge base for <project-name> project: learnings, issue notes, and conventions"

# Generate embeddings for AI-powered search
qmd embed

Knowledge structure

•
references/learnings/: Time-stamped markdown files with project insights
- •Format: YYYY-MM-DD-topic-slug.md
- •Contains learnings, patterns, architectural decisions
•
references/issues/: Issue-specific notes and resolutions
- •Format: <issue-id>.md
- •Append-only log of notes related to specific issues

Integration with qmd MCP server

The qmd MCP server allows Claude to:

•Search knowledge: Use natural language queries to find relevant context
•Auto-update index: Automatically reindex after adding new knowledge
•Filter by project: Use --collection flag to scope searches to specific projects

Example workflow

•
During development, you discover something useful:

"I learned that qmd MCP server allows Claude to use tools autonomously."

•

Claude recognizes the skill and executes:

bash

$SKILL_PATH/scripts/record.sh learning "qmd MCP autonomous tool use"

•
Later, you ask:

"What did I learn about MCP servers?"
•
Claude queries the knowledge base using qmd MCP tools:
bash
```
qmd query --collection <project-name> "MCP servers"
```

Benefits over claude-mem

•Portable: Standard markdown files in ~/.ai-knowledges/
•Project-scoped: Each project has its own isolated knowledge base
•AI-searchable: Powered by qmd's embedding-based search
•Self-documenting: Follows skills.md specification
•No repository pollution: Knowledge stored outside project directories
•Version controllable: Can optionally track knowledge in separate git repos

Project detection

The skill automatically detects your project name using the following priority:

•
QMD_PROJECT environment variable (highest priority)
bash
```
export QMD_PROJECT=my-project-name
```
•
Git remote URL (most reliable - extracts repo name from origin URL)
- •Example: https://github.com/user/my-project.git → my-project
- •Works even if the local folder has a different name
•
Git repository folder name (fallback)
- •Uses the name of the git repository root directory
- •Works when you're anywhere inside a git repository
- •Note: May not match the actual repo name if the folder was renamed
•
Current directory name (last resort)
- •Uses the name of your current working directory
- •Used when not in a git repository

This means you can use the skill in any project without hardcoding project names. The knowledge base will be stored at ~/.ai-knowledges/<detected-project-name>/.

Important: The script prioritizes the git remote URL to ensure consistent project naming even if local folders are renamed or in non-standard locations (e.g., dated folders like 2026-01-08-my-ai-tools.qmd-skill).

📋 Best Practices

🎨 Session Wrap-up

At the end of a work session, consider prompting the user about key learnings:

"What were the main discoveries or decisions from this session? Would you like me to record any learnings?"

🎨 Pattern Detection

Be attentive to phrases that indicate valuable knowledge capture opportunities:

•"I discovered that..."
•"I learned that..."
•"The solution was..."
•"The key insight is..."
•"Don't forget to..."
•"Make sure to..."

When you detect these patterns, suggest recording:

"That sounds like a useful learning. Would you like me to record it?"

🎨 Auto-Index Updates

The record script automatically runs qmd embed after each write, ensuring the knowledge base is searchable immediately. No manual re-indexing required.