---
slug: "conport-mcporter-skills"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/nicobailon/conport-mcporter-skills@main/README.md"
repo: "https://github.com/nicobailon/conport-mcporter-skills"
source_file: "README.md"
branch: "main"
---
# ConPort + MCPorter Skills for Claude Code

Persistent project memory for Claude Code without MCP server bloat.

## The Problem

Installing MCP servers directly in Claude Code has a hidden cost: **tool description bloat**.

ConPort MCP alone exposes **25+ tools**, each with detailed JSON schemas that consume Claude's context window on every request - even when you're not using them. This wastes tokens and can crowd out actual conversation context.

## The Solution

Use [MCPorter](https://github.com/anthropics/mcporter) to access ConPort via CLI instead:

```bash
npx mcporter call --stdio "uvx --from context-portal-mcp conport-mcp --mode stdio" conport.get_product_context
```

The tools are invoked **on-demand** through the skill, not constantly present in context.

## Benefits Comparison

| Aspect | Direct MCP Install | MCPorter + Skill |
|--------|-------------------|------------------|
| Tool descriptions in context | Always (25+ tools) | Never |
| Token overhead per request | ~2000+ tokens | 0 tokens |
| Configuration required | MCP server setup | None (npx) |
| Tool availability | Instant | On-demand via CLI |
| Context window impact | Significant | Minimal |

## What's Included

### Skills
- **mcporter** - General MCPorter CLI access for any MCP server
- **conport-memory** - ConPort-specific commands and workflows

### Slash Commands
- `/conport-init` - Initialize ConPort database for a project
- `/conport-context` - Load and display current project context
- `/conport-decision` - Log architectural decisions with rationale
- `/conport-pattern` - Document reusable system patterns
- `/conport-link` - Create knowledge graph links between items
- `/conport-export` - Export all context to markdown files

### Subagent
- **conport-archivist** - Autonomous agent for complex ConPort queries

## Prerequisites

- [Claude Code CLI](https://claude.ai/code)
- Node.js (for npx)
- Python with uvx (for ConPort MCP)

Install uvx if needed:
```bash
pip install uvx
# or
pipx install uvx
```

## Installation

### 1. Copy Skills

```bash
cp -r skills/* ~/.claude/skills/
```

### 2. Copy Commands

```bash
cp commands/* ~/.claude/commands/
```

### 3. Add Subagent (Optional)

Add the subagent definition from `subagents/conport-archivist.md` to your `~/.claude/CLAUDE.md` file.

## Quick Start

### Initialize a Project

```
/conport-init
```

This creates a `context_portal/context.db` SQLite database and prompts you for project details.

### Load Context at Session Start

```
/conport-context
```

Displays:
- Project overview (product context)
- Current focus (active context)
- Pending work (in-progress items)
- Recent decisions

### Log a Decision

```
/conport-decision Use PostgreSQL for the database
```

### Export for Handoff

```
/conport-export ./handoff-docs
```

## How It Works

### The MCPorter Pattern

Instead of installing ConPort as an MCP server:

```json
// NOT THIS - adds 25+ tool descriptions to every request
{
  "mcpServers": {
    "conport": {
      "command": "uvx",
      "args": ["--from", "context-portal-mcp", "conport-mcp"]
    }
  }
}
```

We use MCPorter to call tools on-demand:

```bash
# THIS - only invoked when the skill activates
npx mcporter call --stdio "uvx --from context-portal-mcp conport-mcp --mode stdio" \
  conport.log_decision summary:"Decision" rationale:"Why"
```

### Skill-Based Activation

The `conport-memory` skill teaches Claude:
1. When to use ConPort (session start, decisions, task completion)
2. The exact MCPorter commands for each operation
3. Recommended workflows for different scenarios

Claude invokes the skill when appropriate, runs the CLI commands, and interprets results - all without permanent tool presence.

## Available ConPort Tools

All ConPort tools are accessible via MCPorter:

**Context Management**
- `get_product_context` / `update_product_context`
- `get_active_context` / `update_active_context`

**Decisions**
- `log_decision` / `get_decisions` / `search_decisions_fts`

**Progress Tracking**
- `log_progress` / `get_progress` / `update_progress`

**Patterns**
- `log_system_pattern` / `get_system_patterns`

**Knowledge Graph**
- `link_conport_items` / `get_linked_items`

**Utility**
- `export_conport_to_markdown` / `import_markdown_to_conport`
- `get_recent_activity_summary` / `batch_log_items`

## Why This Matters

Claude Code's context window is precious. Every token spent on tool descriptions is a token not available for:
- Your code
- Conversation history
- Actual problem-solving

By moving MCP tools behind skills, you get the same functionality with dramatically reduced overhead. This pattern works for any MCP server, not just ConPort.

## Related Projects

- [MCPorter](https://github.com/anthropics/mcporter) - CLI for MCP servers
- [Context Portal MCP](https://github.com/nicobailon/context-portal-mcp) - The ConPort MCP server
- [skills-hook](https://github.com/nicobailon/skills-hook) - Improve skill activation reliability

## License

MIT