Project Memory Skill

A Claude Code skill that establishes a structured institutional knowledge system for your projects. Track bugs with solutions, architectural decisions (ADRs), key project facts, and work history in a consistent, maintainable format.

Quick Start

# Install via skilz (recommended)
skilz install SpillwaveSolutions_project-memory/project-memory

# Then use in any project
cd your-project
# In Claude Code, type: /project-memory

What This Skill Does

When invoked in a project, this skill:

1. Creates a memory infrastructure in docs/project_notes/ with four files:

   • bugs.md - Bug log with solutions and prevention notes
   • decisions.md - Architectural Decision Records (ADRs)
   • key_facts.md - Project configuration, credentials, ports, URLs
   • issues.md - Work log with ticket IDs and descriptions

2. Configures CLAUDE.md and AGENTS.md to make Claude Code (and other AI tools) memory-aware:

   • Check memory files before proposing changes
   • Search for known solutions to familiar bugs
   • Document new decisions, bugs, and completed work
   • Maintain consistency across coding sessions

3. Provides templates and examples for maintaining institutional knowledge in a way that looks like standard engineering documentation (not AI artifacts).

Installation

There are four installation options depending on your needs.

Option 1: Skilz Universal Installer (Recommended)

The recommended way to install this skill across different AI coding agents is using the skilz universal installer. This skill supports the Agent Skill Standard, which means it works with 14+ coding agents including Claude Code, OpenAI Codex, Cursor, and Gemini.

Install Skilz

pip install skilz

Git URL Options

You can use either -g or --git with HTTPS or SSH URLs:

# HTTPS URL
skilz install -g https://github.com/SpillwaveSolutions/project-memory

# SSH URL
skilz install --git git@github.com:SpillwaveSolutions/project-memory.git

Claude Code

Install to user home (available in all projects):

skilz install -g https://github.com/SpillwaveSolutions/project-memory

Install to current project only:

skilz install -g https://github.com/SpillwaveSolutions/project-memory --project

OpenCode

Install for OpenCode:

skilz install -g https://github.com/SpillwaveSolutions/project-memory --agent opencode

Project-level install:

skilz install -g https://github.com/SpillwaveSolutions/project-memory --project --agent opencode

Gemini

Project-level install for Gemini:

skilz install -g https://github.com/SpillwaveSolutions/project-memory --agent gemini

OpenAI Codex

Install for OpenAI Codex:

skilz install -g https://github.com/SpillwaveSolutions/project-memory --agent codex

Project-level install:

skilz install -g https://github.com/SpillwaveSolutions/project-memory --project --agent codex

Install from SkillzWave Marketplace

# Claude to user home dir ~/.claude/skills
skilz install SpillwaveSolutions_project-memory/project-memory

# Claude skill in project folder ./claude/skills
skilz install SpillwaveSolutions_project-memory/project-memory --project

# OpenCode install to user home dir ~/.config/opencode/skills
skilz install SpillwaveSolutions_project-memory/project-memory --agent opencode

# OpenCode project level
skilz install SpillwaveSolutions_project-memory/project-memory --agent opencode --project

# OpenAI Codex install to user home dir ~/.codex/skills
skilz install SpillwaveSolutions_project-memory/project-memory --agent codex

# OpenAI Codex project level ./.codex/skills
skilz install SpillwaveSolutions_project-memory/project-memory --agent codex --project

# Gemini CLI (project level) -- only works with project level
skilz install SpillwaveSolutions_project-memory/project-memory --agent gemini

See skill Listing for installation details for 14+ different coding agents.

Other Supported Agents

Skilz supports 14+ coding agents including Windsurf, Qwen Code, Aidr, and more. For the full list of supported platforms, visit:

• SkillzWave Platforms
• skilz-cli GitHub Repository

SkillzWave - Largest Agentic Marketplace for AI Agent Skills | SpillWave - Leaders in AI Agent Development

Option 2: Global Installation (Manual)

Install once in your Claude Code home directory to make the skill available across all projects:

# Create the skills directory if it doesn't exist
mkdir -p ~/.claude/skills

# Clone or copy the skill to your skills directory
cp -r project-memory ~/.claude/skills/

# Verify installation
ls ~/.claude/skills/project-memory

When to use: You want this skill available for all your projects without reinstalling.

Option 3: Project-Specific Installation (Manual)

Install in a specific project's .claude/skills/ directory:

# Navigate to your project
cd /path/to/your/project

# Create local skills directory
mkdir -p .claude/skills

# Clone or copy the skill
cp -r /path/to/project-memory .claude/skills/

# Verify installation
ls .claude/skills/project-memory

When to use: You only want this skill available for a specific project.

Option 4: Multi-Project Installation (Workspace)

Install above a workspace directory to share across multiple related projects:

# Navigate to your workspace directory (parent of multiple projects)
cd ~/workspace

# Create shared skills directory
mkdir -p .claude/skills

# Clone or copy the skill
cp -r /path/to/project-memory .claude/skills/

# Verify installation
ls .claude/skills/project-memory

When to use: You have multiple projects in a workspace and want to share the skill without global installation.

Example structure:

~/workspace/
├── .claude/
│   └── skills/
│       └── project-memory/    # Shared across all projects below
├── project-a/
├── project-b/
└── project-c/

How to Use

First-Time Setup in a Project

1. Navigate to your project directory
2. Invoke the skill in Claude Code:

   /project-memory
   

3. The skill will:
   • Create docs/project_notes/ directory
   • Initialize the four memory files with templates
   • Update (or create) CLAUDE.md with memory protocols
   • Optionally update AGENTS.md if it exists

Daily Usage

Once set up, Claude Code will automatically:

• Check memory files before proposing architectural changes
• Search bugs.md when you encounter errors
• Reference key_facts.md for project configuration

You can also explicitly request updates:

Add this CORS fix to our bug log

Document the decision to use FastAPI in decisions.md

Update key_facts.md with the new database connection string

Log this completed ticket in issues.md

File Structure After Setup

your-project/
├── docs/
│   └── project_notes/
│       ├── bugs.md         # Bug log with solutions
│       ├── decisions.md    # Architectural Decision Records
│       ├── key_facts.md    # Project configuration
│       └── issues.md       # Work log
├── CLAUDE.md              # Updated with memory protocols
└── AGENTS.md              # Updated with memory protocols (if exists)

Memory File Formats

bugs.md - Bug Log

### 2025-01-15 - Docker Architecture Mismatch
- **Issue**: Container failing to start with "exec format error"
- **Root Cause**: Built on ARM64 Mac but deploying to AMD64 Cloud Run
- **Solution**: Added `--platform linux/amd64` to docker build
- **Prevention**: Always specify platform in Dockerfile

decisions.md - Architectural Decisions

### ADR-001: Use Workload Identity Federation (2025-01-10)

**Context:**
- Need secure authentication from GitHub Actions to GCP

**Decision:**
- Use Workload Identity Federation instead of service account keys

**Alternatives Considered:**
- Service account JSON keys → Rejected: security risk

**Consequences:**
- ✅ More secure (no long-lived credentials)
- ❌ Slightly more complex initial setup

key_facts.md - Project Configuration

⚠️ SECURITY WARNING: Never store passwords, API keys, or credentials in key_facts.md. Only store non-sensitive reference information like hostnames, ports, client names, project IDs, and account names. Store secrets in .env (excluded via .gitignore), password managers, or secrets management systems.

### Database Configuration

**AlloyDB Cluster:**
- Cluster Name: `prod-cluster`
- Private IP: `10.0.0.5`
- Port: `5432`
- Database Name: `contacts`

**Connection:**
- Use AlloyDB Auth Proxy for local development
- Proxy command: `./alloydb-auth-proxy "projects/..."`
- Credentials: Stored in `.env` file (not in git)

issues.md - Work Log

### 2025-01-15 - PROJ-123: Implement Contact API
- **Status**: Completed
- **Description**: Created FastAPI endpoints for contact CRUD
- **URL**: https://jira.company.com/browse/PROJ-123
- **Notes**: Added unit tests, coverage at 85%

Verification

After installation, verify the skill is available:

1. Open Claude Code in any project
2. Type / to see available skills
3. You should see project-memory in the list

Or check manually:

# For global installation
ls ~/.claude/skills/project-memory/SKILL.md

# For project-specific installation
ls .claude/skills/project-memory/SKILL.md

# For workspace installation
ls ../.claude/skills/project-memory/SKILL.md  # From inside a project

Security Best Practices

⚠️ Critical: Never Store Secrets in Version Control

The key_facts.md file is designed to store non-sensitive project reference information only. This file is typically committed to version control and should NEVER contain:

❌ NEVER store in key_facts.md or any git-tracked file:

• Passwords or passphrases
• API keys or authentication tokens
• Service account JSON keys or credentials
• Database passwords
• OAuth client secrets
• Private keys or certificates
• Session tokens
• Any secret values from environment variables

✅ SAFE to store in key_facts.md:

• Database hostnames, ports, and cluster names
• Client names and project identifiers
• JIRA project keys and Confluence space names
• AWS account names and profile names (e.g., "dev", "staging", "prod")
• API endpoint URLs (public URLs only)
• Service account email addresses (not the keys!)
• GCP project IDs and region names
• Docker registry names
• Environment names and deployment targets

✅ WHERE to store sensitive credentials:

• .env files - Excluded via .gitignore, used for local development
• Password managers - 1Password, LastPass, Bitwarden, etc.
• Secrets managers - AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, Azure Key Vault
• CI/CD environment variables - GitHub Secrets, GitLab CI/CD Variables, etc.
• Platform credential stores - Kubernetes Secrets, Cloud Run Secret Manager integration

✅ VERIFICATION steps before committing:

1. Run git status to see what will be committed
2. Verify .env, credentials.json, and other sensitive files are in .gitignore
3. Never use git add . blindly - review each file being sta