Build Your First Claude Code Skill: A Simple Project Memory System That Saves Hours

How a 300-line skill became my most-used productivity tool for AI-assisted development.

Picture this: It’s 11 PM on a Tuesday. You’re staring at an error message that feels hauntingly familiar. “Connection refused on port 5432”. You’ve seen this before. You know you’ve solved it before. But where? When? The commit message just said “fixed db connection.” Stack Overflow gives you twelve different answers. Your AI assistant cheerfully suggests solutions you’ve already tried.

This is AI amnesia in action, and it costs you more than you realize.

Every AI coding assistant shares the same frustrating limitation: they forget everything between sessions. Start a new chat, and Claude doesn’t know that yesterday you spent 45 minutes discovering your staging environment uses port 5433, not 5432. It doesn’t remember that you chose PostgreSQL over MongoDB because of your team’s existing expertise. It can’t recall that the “connection refused” error always means the VPN disconnected. Or it starts using an new NLP lib or charting lib when the whole project uses something else and you already decided which one you wanted to use. Then you have to explain it again. And again.

All that hard-won knowledge? Gone. Every. Single. Time.

I discovered a simple solution while watching a YouTube video about keeping Claude Code up-to-date with project context. The creator linked small markdown files from their CLAUDE.md to track decisions, bugs, and key facts. A lightbulb moment hit me: What if I could create a skill that manages this automatically?

That idea became project-memory, one of the very first skills I wrote for Claude Code. Despite being remarkably simple (under 300 lines), it has genuinely saved me hours upon hours of work. This tutorial shows you how to build your own project memory skill and, more importantly, how to think about creating skills that solve real problems.

Claude Code isn’t the only player anymore. Codex, GitHub Copilot, and OpenCode have all announced support for Agentic Skills. There’s even a marketplace for agentic skills that supports Gemini, Aidr, Qwen Code, Kimi K2 Code, Cursor, and more; 14+ platforms and counting with a universal agentic skills installer (skilz). Throughout this guide, I’ll use “Claude” and “coding agent” interchangeably, like saying “Xerox this paper” instead of “copy this paper.” (For what it’s worth, I prefer Claude Code, OpenCode, and Gemini CLI in my own workflows.)

The True Cost of AI Amnesia

Let me paint a picture you might recognize:

Month 1: The Discovery

Error: CORS policy blocked request from localhost:3000
[2 hours of debugging, trying proxy configs, header changes, nginx rewrites]
Solution: Add proxy configuration to package.json

Month 6: The Deja Vu

Error: CORS policy blocked request from localhost:3000
Developer: "This looks familiar... how did we fix this?"
[Searches old commits, checks Stack Overflow again, asks Claude who has no memory]
[1 hour to re-discover the exact same proxy config solution]

Sound familiar? Here’s the uncomfortable truth: AI code assistants actually make this worse, not better. Without memory:

Each new chat session starts from zero knowledge
Every bug feels like you’re solving it for the first time
Solutions get “rediscovered” repeatedly (I once solved the same CORS issue four times in six months)
No learning accumulates over time, for you or your AI assistant

The hidden cost is staggering. If you spend just 30 minutes per week re-solving problems you’ve already solved, that’s 26 hours per year. At $100/hour, that’s $2,600 of wasted time per developer.

But what if your AI assistant could remember?

What is a Claude Code Skill?

Before diving into project-memory, let’s understand what skills actually are. If you’ve ever wished you could teach Claude a specific workflow or give it domain knowledge, skills are the answer.

A skill is simply a folder containing a SKILL.md file and optional supporting resources. The SKILL.md file has two parts:

YAML frontmatter: Metadata that tells Claude when to activate the skill
Markdown body: Instructions Claude follows when the skill is active

Think of skills as reusable “expert modes” you can install. When you say “set up project memory,” Claude doesn’t just guess what you mean. It loads specific, tested instructions for exactly that task.

Skill Structure Anatomy

SKILL.md file structure showing YAML frontmatter with name and description, and Markdown body with sections for Overview, When to Use, Core Capabilities, Examples, and Success Criteria

The SKILL.md file structure showing YAML frontmatter with name and description, and Markdown body with sections for Overview, When to Use, Core Capabilities, Examples, and Success Criteria.

Skills can live in typically two locations:

Store skills in your user home directory ~/.claude/skills/.These are global available in all projects and they are for general-purpose skills like code review, documentation. Then you can have project specific skills that live in .claude/skills/. These are local only this project project-specific workflows, team conventions. I say typically because you have have enterprise skills, shared skills at a mono-repo level, etc. And it also depend on which provider you are using (~/.codex/skills/ , ~/.config/opencode/skill/ , ~/.gemini/skills/ , .claude/skills/ , .codex/skills/ , .opencode/skills/ just to name a few).

💡 Try This: Run ls ~/.claude/skills/ to see what skills you already have installed. If the directory doesn't exist yet, you'll create it when you install your first skill.

How Skill Activation Works

When you make a request, Claude Code follows a progressive disclosure pattern for writing agentic skills. It only loads what it needs, when it needs it. This keeps interactions fast while giving you access to powerful capabilities on demand.

Skill activation flowchart showing three phases: Discovery (scan directories, load metadata), Matching (check if request matches skill), and Execution (load SKILL.md, follow instructions, complete task)

See the skill activation flowchart showing three phases: Discovery (scan directories, load metadata), Matching (check if request matches skill), and Execution (load SKILL.md, follow instructions, complete task).

The key insight: Claude scans skill directories and reads only the metadata (name + description) until it finds a match. Only then does it load the full instructions. This means you can have dozens of skills installed without slowing down normal interactions.

Now that you understand the mechanics, let’s see how project-memory puts them into practice.

The Project Memory Skill

The project-memory skill creates a structured knowledge system in docs/project_notes/ with four specialized files. Each serves a distinct purpose in preserving and recalling project knowledge.

Memory File Structure

Note the project memory file structure showing docs/project_notes/ folder containing bugs.md, decisions.md, key_facts.md, and issues.md, plus configuration files CLAUDE.md and AGENTS.md which it links to project notes files which makes up the project memory.

Each memory file serves a specific role in capturing project knowledge. For instance, bugs.md, acts as a searchable bug database where entries like “BUG-018: Pulumi state drift — run pulumi refresh — yes “ document both the problem and its solution, preventing future time loss when the same issue reappears. I use this to track reoccurring problems with the project. The decisions.md file tracks architectural choices through ADRs (Architectural Decision Records), such as “ADR-012: Use D3.js for all charts (team expertise),” ensuring consistency and preventing conflicting technology decisions down the line. Meanwhile, key_facts.md serves as a quick reference for essential project details like “Staging API: https://api.staging.example.com:8443," eliminating guesswork about ports and URLs. Finally, issues.md maintains a chronological work log with entries like “TICKET-456: Implemented user auth — 2024–01–15,” creating an audit trail that connects completed work to specific tickets and dates.

Let me break down how each part of the skill works.

Part 1: The Frontmatter (The “When” of Your Skill)

---
name: project-memory
description: Set up and maintain a structured project memory system in docs/project_notes/
  that tracks bugs with solutions, architectural decisions, key project facts, and work
  history. Use this skill when asked to "set up project memory", "track our decisions",
  "log a bug fix", "update project memory", or "initialize memory system".
---

The description field is critical. It's arguably the most important part of your skill. It tells Claude when to activate. Notice the specific trigger phrases embedded in the description: "set up project memory", "track our decisions", "log a bug fix". When you say any of these, Claude recognizes the match and loads the full instructions. (The complete skill is listed at the end or the article.)

💡 Try This: When writing your own skill descriptions, include 3–5 specific phrases users might naturally say. Test activation by trying variations: “help me track decisions” vs “set up decision tracking” vs “I want to log our architectural choices.”

Part 2: When to Use This Skill (Contextual Triggers)

## When to Use This Skill

Invoke this skill when:

- Starting a new project that will accumulate knowledge over time
- The project already has recurring bugs or decisions that should be documented
- The user asks to "set up project memory" or "track our decisions"
- Encountering a problem that feels familiar ("didn't we solve this before?")
- Before proposing an architectural change (check existing decisions first)

This section reinforces the triggers and helps Claude understand the broader context where memory is useful. The phrase “didn’t we solve this before?” is particularly powerful. It captures the exact moment of frustration where memory would help.

Part 3: Initial Setup Instructions (The “What” of Your Skill)

## Core Capabilities

### 1. Initial Setup - Create Memory Infrastructure

When invoked for the first time in a project, create the following structure:

docs/
└── project_notes/
    ├── bugs.md         # Bug log with solutions
    ├── decisions.md    # Architectural Decision Records
    ├── key_facts.md    # Project configuration and constants
    └── issues.md       # Work log with ticket references

**Directory naming rationale:** Using `docs/project_notes/` instead of `memory/`
makes it look like standard engineering organization, not AI-specific tooling.

This design decision matters more than it might seem: make memory look like normal documentation. If you create files in ai-memory/ or claude-context/, developers will view it as AI tooling and won't maintain it. In docs/project_notes/, it looks like standard engineering documentation that anyone can update, whether they use AI assistance or not.

Part 4: Memory Entry Formats (Structured Knowledge)

The skill defines consistent formats for each type of entry. Consistency matters because Claude can parse structured formats reliably, even months later:

Side-by-side comparison of bugs.md entry format (Issue, Root Cause, Solution, Prevention) and decisions.md ADR format (Context, Decision, Alternatives, Consequences)

The above is a s Side-by-side comparison of bugs.md entry format (Issue, Root Cause, Solution, Prevention) and decisions.md ADR format (Context, Decision, Alternatives, Consequences).

The Prevention field in bug entries is particularly valuable. It transforms bugs from “problems we fixed” into “lessons we learned.” Six months from now, Claude can warn you before you hit the same issue.

Part 5: Memory Protocols for CLAUDE.md (The Magic)

Here’s where the real power emerges. The skill configures CLAUDE.md to make Claude memory-aware by default:

### 2. Configure CLAUDE.md - Memory-Aware Behavior

Add or update the following section in the project's `CLAUDE.md` file:

## Project Memory System

### Memory-Aware Protocols

**Before proposing architectural changes:**
- Check `docs/project_notes/decisions.md` for existing decisions
- Verify the proposed approach doesn't conflict with past choices

**When encountering errors or bugs:**
- Search `docs/project_notes/bugs.md` for similar issues
- Apply known solutions if found
- Document new bugs and solutions when resolved

**When looking up project configuration:**
- Check `docs/project_notes/key_facts.md` for credentials, ports, URLs
- Prefer documented facts over assumptions

This is where the magic happens. Once these protocols are in CLAUDE.md, Claude will automatically check memory files before making decisions or suggestions. You don't have to remember to say "check the bug log." It becomes the default behavior.

Real-World Impact: Knowledge Compound Interest

Let me share specific examples of how memory changes everyday development workflows.

Memory-Aware Bug Resolution

Comparison diagram showing bug resolution without memory (45 minutes of debugging from scratch) versus with memory (5 minutes by looking up known solution in bugs.md)

The above shows a comparison diagram showing bug resolution without memory (45 minutes of debugging from scratch) versus with memory (5 minutes by looking up known solution in bugs.md). And I have wasted hours chasing stuff that I have seen before so 45 minutes is under embellishing the potential savings. It is not just the time. It is the absolute frustration that you can avoid!

Example 1: Bug Resolution Speed (Real Numbers)

The Scenario:

On October 20th, I encountered a Pulumi state drift error during deployment. The error message was cryptic: error: update failed. After 45 minutes of debugging, checking IAM permissions, reviewing recent changes, and trying different deployment strategies, I discovered the solution: pulumi refresh --yes to sync the state file.

I documented it as BUG-018:

### 2024-10-20 - BUG-018: Pulumi State Drift During Deploy

**Issue**: Deploy failed with cryptic "update failed" error after manual 
GCP console changes

**Root Cause**: Pulumi state file out of sync with actual infrastructure 
after teammate made console changes

**Solution**: Run `pulumi refresh --yes` before deploy to sync state

**Prevention**: Add `pulumi refresh --yes` to CI/CD pipeline before deploys; 
document that manual console changes require refresh

Two days later, on October 22nd, the same error appeared. This time:

I told Claude about the error
Claude checked bugs.md and found BUG-018
Claude suggested pulumi refresh --yes
Problem solved in 5 minutes

Result: 45 minutes reduced to 5 minutes. An 89% reduction in resolution time.

Example 2: Architectural Consistency (Preventing Bundle Bloat)

Without Memory:

User: "Add a bar chart to the dashboard"
Claude: "I'll add Chart.js for the bar chart. Let me install it..."
Result: Bundle size +85KB, duplicate charting dependencies, inconsistent styling

With Memory:

User: "Add a bar chart to the dashboard"
Claude: Checking decisions.md...
Found: ADR-012 - Use D3.js for all charts (team has D3 expertise, already in bundle)
Claude: "I see we've decided to use D3.js for charts. I'll create the bar chart using D3 to match your existing charts."
Result: Uses existing D3.js, consistent styling, no bundle increase

This kind of consistency compounds. One charting library decision prevents dozens of future dependency conflicts. These are real world scenarios for me.

The Compound Interest Effect

Knowledge compound interest timeline showing progression from first encounter (2 hours debugging) to documentation to second encounter (5 minutes) to third (2 minutes) to preventative advice

The fact is that knowledge capture pays back with compound interest. The above diagram shows a timeline showing progression from first encounter (2 hours debugging) to documentation to second encounter (5 minutes) to third (2 minutes) to preventative advice

Notice the progression: by the fourth encounter, Claude doesn’t just fix the bug. It prevents it. “I notice you’re about to make a change that caused state drift issues before. Should I run pulumi refresh first?"

Your project gets easier to maintain over time, not harder. That’s the compound interest effect of documented knowledge.

Cross-Platform: The Agent Skill Standard

Here’s something powerful: project-memory isn’t just for Claude Code. It follows the Agent Skill Standard (agentskills.io), which means the same skill works across 14+ AI coding assistants. There are also instructions in the skill to keep AGENTS.md up to date.

Why does this matter? Teams often use different AI tools. One developer might prefer Claude Code, another uses Cursor, and a third likes GitHub Copilot. With standardized skills, everyone shares the same project memory.

Diagram showing Agent Skill Standard enabling one skill to work across Claude Code, Codex, Gemini, Cursor, and more

The above shows how the Agent Skill Standard enables one skill to work across Claude Code, Codex, Gemini, Cursor, and more.

Cross-Platform Installation

Cross-platform skill installation diagram showing GitHub and SkillzWave marketplace as sources, skilz CLI as the installer, distributing to Claude Code, Codex, Gemini, Cursor, Copilot and more AI agents

Agent skills have become cross-platform so there are a few universal skill installers out there. The above shows finding skills on GitHub and SkillzWave marketplace as sources, the open source skilz CLI as the agent skill installer, distributing to Claude Code, Codex, Gemini, Cursor, Github Copilot and more AI agents.

Installing with skilz CLI

# Install skilz
pip install skilz

# Install for Claude Code (global)
skilz install -g https://github.com/SpillwaveSolutions/project-memory

# Install for a specific project only
skilz install -g https://github.com/SpillwaveSolutions/project-memory --project

# Install for other agents
skilz install -g https://github.com/SpillwaveSolutions/project-memory \
                --agent codex
skilz install -g https://github.com/SpillwaveSolutions/project-memory \
               --agent gemini
skilz install -g https://github.com/SpillwaveSolutions/project-memory \
               --agent cursor
skilz install -g https://github.com/SpillwaveSolutions/project-memory \
               --agent opencode

Same knowledge, accessible from any AI coding tool you use. When you document a bug fix in Claude Code, your teammate using Cursor or Gemini or Codex can benefit from that knowledge the next day.

You can install it anywhere.

Viewing project-memory in the skillz marketplace with install instructions for various coding agent platforms

Security: What You Must Never Store

This section is critical. Read it carefully before using project memory.

The key_facts.md file is designed for convenient lookup of project configuration. However, convenience creates risk if you're not careful. Never store secrets in your memory files. They're version-controlled markdown that anyone with repo access can read. The skill specifies this caveat.

The Danger Zone

Never store these in key_facts.md (or any memory file):

Never Store in key_facts.md (Summary)

Authentication Credentials: Passwords, API keys, access tokens, or any form of authentication secrets
Service Account Keys: GCP/AWS JSON key files, private keys, or service account credentials
OAuth Secrets: Client secrets, refresh tokens, or OAuth configuration secrets
Database Credentials: Connection strings containing passwords or any database authentication details
Infrastructure Secrets: SSH private keys, VPN credentials, or network access credentials

The Safe Zone

Safe to store in key_facts.md:

Safe to Store (Summary)

Hostnames and URLs: Public domain names like api.staging.example.com or https://api.example.com/v1
Port Numbers: Standard ports like PostgreSQL: 5432 or Redis: 6379
Project Identifiers: GCP project IDs, AWS account IDs, or similar non-sensitive identifiers
Service Account Email Addresses: Identity information like service-account@project.iam.gserviceaccount.com
Environment Names: Environment labels like staging, production, or dev
Public Endpoints: Any publicly accessible URLs or API endpoints
Configuration Values: Non-sensitive settings like timeout values, retry counts, or feature flags

Where Secrets Belong

Where Secrets Belong (Summary)

.env Files (gitignored): Best for local development secrets like DATABASE_PASSWORD=secret123
Cloud Secrets Managers: Production systems should use GCP Secret Manager, AWS Secrets Manager, or Azure Key Vault
CI/CD Variables: Automated pipelines should use GitHub Actions secrets, GitLab CI/CD variables, or similar
Password Managers: Team sharing of credentials through 1Password, LastPass, Bitwarden, or similar tools
Environment Variables: Runtime secrets injected at deployment time, never committed to version control
Kubernetes Secrets: For containerized applications using Kubernetes Secret objects
Hardware Security Modules (HSM): For highly sensitive cryptographic keys in enterprise environments

💡 Try This: Right now, search your existing key_facts.md (if you have one) for patterns like password, secret, key, or token. If you find any secrets, move them immediately and rotate the compromised credentials.

Common Pitfalls (and How to Avoid Them)

After using project-memory across dozens of projects and helping others adopt it, I’ve seen the same mistakes repeatedly. Learn from these to save yourself frustration.

Pitfall 1: The Documentation Ghost Town

The Problem: You set up project memory with enthusiasm, add three entries, then never touch it again. Six months later, the files are outdated and useless.

The Solution: Add memory updates to your workflow, not your todo list. After every bug fix, ask Claude: “Log this in bugs.md.” After every architectural discussion, say: “Add an ADR for this decision.” Make it reflexive, not deliberate.

I also wrote another skill where I break up the workflow into an architect agent, code agent and human in the middle. This skill has the ability to install a hook for Claude or a plugin for OpenCode and automatically track log files of key decisions and redirections which I can later start up a background agent to scan for key decisions, bugs, key_facts that I might have missed, and I have done this. This way if you do forget, you can have an background agent scan the logs and look for this important factoids.

Pitfall 2: The Novel-Length Entry

The Problem: Bug entries become multi-page essays. Decision records include the entire discussion history. Nobody reads them because they’re too long.

The Solution: Each entry should be scannable in 30 seconds. Use the structured format (Issue, Root Cause, Solution, Prevention). If you need more detail, link to a separate document.

Pitfall 3: The Everything File

The Problem: All information goes into key_facts.md, which grows to 500 lines with no organization.

The Solution: Use all four files for their intended purposes:

Bugs go in bugs.md
Decisions go in decisions.md
Configuration goes in key_facts.md
Work history goes in issues.md

If key_facts.md exceeds 100 lines, it probably contains decisions disguised as facts.

The Déjà Vu Trap

The Problem: You experience that frustrating moment: “I know I’ve seen this bug before. I know we fixed it. I know there’s a workaround.” But you can’t remember the details, so you spend another 30 minutes rediscovering the solution.

The Solution: This is exactly what project memory eliminates. When that déjà vu feeling hits, your first response should be: “Check the bugs.md file.” That reoccurring CORS issue? It’s documented. That flaky test that fails on Tuesdays? The workaround is recorded. That authentication edge case? Already solved and logged.

The beauty is that project memory creates institutional knowledge; what teams often call “tribal knowledge”; but makes it accessible instead of locked in someone’s head. When your team decides to use D3.js for all charts, that decision gets recorded. Six months later, when someone new joins and asks “which charting library should I use?”, Claude doesn’t guess. It checks decisions.md and gives the right answer.

Real impact: No more solving the same problem twice. No more inconsistent technology choices. No more “I swear we fixed this before” frustration. The reoccurring stuff ends because the memory persists.

Pitfall 4: The Secret Stash

The Problem: Developers store API keys in key_facts.md "just for convenience." The keys end up in git history forever. Use .env and add the .env to your .gitignore. We are civilized and societies have rules. :)

The Solution: See the Security section above. If you’ve already committed secrets, rotate them immediately. Removing from git history isn’t enough because the secret may already be cloned elsewhere.

Pitfall 5: The Island Memory

The Problem: One developer maintains project memory religiously. Others don’t know it exists. Knowledge silos form.

The Solution: Add a section about project memory to your README or onboarding docs. Mention memory files in PR reviews: “This bug fix should be documented in bugs.md.”

Pitfall 6: The Stale Decisions

The Problem: ADR-003 says “Use REST for all APIs” but the team migrated to GraphQL two years ago. The memory file now contains misleading information.

The Solution: Review decision records quarterly. Mark outdated decisions as superseded: **Status**: Superseded by ADR-027. Don't delete. Future developers might wonder why old code uses REST.

Building Your Own Skills

The project-memory skill demonstrates key principles you can apply to any skill you create. These guidelines come from building dozens of skills and seeing which ones get used versus abandoned.

1. Solve a Real Problem You Actually Have

Build skills when you notice yourself:

Repeating the same explanation to Claude (or teammates)
Looking up the same information repeatedly
Following the same multi-step process manually
Wishing Claude “just knew” something about your project

Anti-pattern: Don’t build skills for hypothetical problems. If you haven’t experienced the pain, you won’t design the right solution.

2. Keep It Focused (One Skill = One Purpose)

Resist the urge to create a “super skill” that does everything. Composable, focused skills are more reusable and easier to maintain.

Good: project-memory handles memory. code-review handles reviews.
Bad: project-everything tries to manage memory, reviews, deployments, and coffee orders.

3. Use Clear, Natural Trigger Phrases

Your description should include specific phrases users might naturally say:

“set up project memory”
“log this bug”
“update key facts”
“track our decisions”

Test your triggers by asking: “Would I actually say this?” Avoid jargon-heavy triggers like “initialize documentation subsystem.”

4. Make It Look Like Standard Documentation

Files in docs/ get maintained. Files in ai-stuff/ get ignored.

Name your files and directories using conventions your team already follows. If decisions would normally go in an adr/ folder, put them there. If your team uses Notion, consider creating a skill that exports to Notion format.

5. Include Templates and Examples

Show the exact format you want. Claude will follow examples more reliably than abstract instructions.

Less effective:

Create a bug entry with relevant information

More effective:

### YYYY-MM-DD - Bug Title

**Issue**: What happened
**Root Cause**: Why it happened
**Solution**: How you fixed it
**Prevention**: How to avoid it

Try It Yourself

Ready to add project memory to your workflow? Here’s how to start in the next five minutes.

Quick Start

# Install skilz CLI
pip install skilz

# Install project-memory globally (works in all projects)
skilz install <https://github.com/SpillwaveSolutions/project-memory

Then open Claude Code in any project:

"Set up project memory for this project"

Claude will create the memory infrastructure, configure your CLAUDE.md, and you're ready to go.

If that does not work you can try one of these.

"Set up project memory for this project using the project memory skill"

Or...

"/project-memory-skill Set up project memory for this project"

The skill also works with AGENTS.md out of the gate because I often work with OpenCode as well as Claude Code, I wrote it to work with both. Again, this is one of my first skills that I wrote and it could use some love.

Your First Week Challenge

Don’t try to document everything at once. Instead:

Day 1: Set up project memory

Day 2: Add one entry to key_facts.md (a URL or port you always forget)

Day 3: Document a bug when you fix one in bugs.md

Day 4: Record one architectural decision in decisions.md

Day 5: Ask Claude about something you documented earlier

By Day 5, you’ll experience that first “aha!” moment when Claude remembers something you told it days ago. That’s when the value becomes real.

What Success Looks Like

After one week, you should have:

3–5 entries across your memory files
At least one instance where Claude used memory to help you
A habit forming around documentation

After one month:

15–25 entries across memory files
Multiple instances of time saved through memory lookups
Teammates asking “how does Claude know that?”

Future Improvements: Making Project Memory Even Better

While this skill solves the core problem of AI amnesia, there’s plenty of room for enhancement. Here are some improvements that could take project memory to the next level:

1. Automatic Table of Contents Generation

The Need: As bugs.md, decisions.md, and key_facts.md grow beyond 50-100 entries, finding specific information becomes harder. AI coding assistants use agentic search, but structured navigation helps both humans and AI.

The Solution: Automatically generate a table of contents at the top of each file when it exceeds a certain threshold (e.g., 20 entries). This improves semantic search capabilities and makes manual browsing much faster. This would help with partial discovery architecture.

## Table of Contents
- [Authentication Issues](#authentication-issues)
- [Database Performance](#database-performance)
- [CORS Problems](#cors-problems)

2. Automatic File Archiving

The Need: Bug entries from two years ago aren’t as relevant as recent ones. Keeping everything in one file creates noise and degrades search quality. This is in addition to the TOC.

The Solution: Implement automatic archiving for bugs.md and issues.md:

Move bugs older than 6–12 months to bugs-archive-2025.md
Keep a reference in the main file: See bugs-archive-2025.md for older entries
Decisions and key facts typically don’t need archiving. They remain relevant indefinitely until you decide to change them.

4. Multi-Agent Support (Beyond Claude)

The Need: When this skill was originally created, Claude Code skills weren’t an open standard. Now that the Agent Skill Standard exists, we should make project memory truly universal.

The Solution: Make the skill detect and configure multiple AI coding assistants:

If using Claude Code, update CLAUDE.md
If using Gemini, update GEMINI.md
If using Codex or other tools, update AGENT.md or prompt for the configuration file location

The skill could ask during setup: “Which AI coding assistant(s) do you use?” and configure all relevant files automatically.

The Evolution Continues: These future improvements reflect a deeper understanding of both AI coding assistants and agentic search capabilities. As the ecosystem matures and we learn more about how agents use project memory, the skill will continue to evolve.

The beauty of the skill system is that these enhancements can be added incrementally without breaking existing functionality. Start with the basics, then layer on sophistication as your needs grow.

I hope you enjoyed this very simple skill and it helps you understand Agentic skills a bit better, if it did give like and a comment.

Conclusion: Start Small, Compound Fast

The project-memory skill is intentionally simple. It’s a folder with a SKILL.md and some template files, probably under 300 lines total. Yet this minimal investment has saved me dozens of hours by:

Eliminating repeated debugging sessions (the same bug never takes 45 minutes twice)
Maintaining architectural consistency (no more accidental framework sprawl)
Preserving project knowledge across sessions (context survives chat restarts)
Working across multiple AI coding tools (team-wide benefits)

More importantly, it demonstrates how small, focused skills can have outsized impact. You don’t need complex automation. Sometimes a structured markdown file and clear protocols are enough.

Here’s my challenge to you: Install project-memory today. Document one bug, one decision, and one key fact this week. Experience the compound interest of remembered knowledge.

Then, when you find yourself explaining the same thing to Claude for the third time, build your own skill. Start small. Solve a real problem. Watch the time savings compound.

Your future self, the one who doesn’t have to re-solve that CORS issue for the fifth time, will thank you.

Resources:

Project Memory on GitHub: Full source code and examples
Project Memory Skill on SkillzWave Marketplace: Skill with install instructions
Agent Skill Standard: Cross-platform skill specification
SkillzWave Marketplace: Browse and install community skills
skilz CLI GitHub Repo: Installation and usage guide, plus source code
skilz CLI documentation: Manual, Installation, and Usage Guide.

Have you built a skill that solved a nagging problem? Share it in the comments. I’d love to see what the community creates.

#AI #Claude #ClaudeCode #DeveloperTools #Productivity #SoftwareDevelopment #Programming #AICodingAssistant #DevOps #TechTutorial #CodingTips #AITools

About the Author

Rick Hightower is a technology executive and data engineer with extensive experience at a Fortune 100 financial services organization, where he led the development of advanced Machine Learning and AI solutions to optimize customer experience metrics. His expertise spans both theoretical AI frameworks and practical enterprise implementation.

Rick wrote the skilz universal agent skill installer that works with Gemini, Claude Code, Codex, OpenCode, Github Copilot CLI, Cursor, Aidr, Qwen Code, Kimi Code and about 14 other coding agents as well as the co-founder of the world’s largest agentic skill marketplace.

Connect with Rick Hightower on LinkedIn or Medium for insights on enterprise AI implementation and strategy.

Community Extensions & Resources

The Claude Code community has developed powerful extensions that enhance its capabilities. Here are some valuable resources from Spillwave Solutions (Spillwave Solutions Home Page):

Integration Skills

Notion Uploader/Downloader: Seamlessly upload and download Markdown content and images to Notion for documentation workflows
Confluence Skill: Upload and download Markdown content and images to Confluence for enterprise documentation
JIRA Integration: Create and read JIRA tickets, including handling special required fields

Recently, I wrote a desktop app called Skill Viewer to evaluate Agents skills for safety, usefulness, links and PDA.

Advanced Development Agents

Architect Agent: Puts Claude Code into Architect Mode to manage multiple projects and delegate to other Claude Code instances running as specialized code agents
Project Memory: Store key decisions, recurring bugs, tickets, and critical facts to maintain vital context throughout software development

Visualization & Design Tools

Design Doc Mermaid: Specialized skill for creating professional Mermaid diagrams for architecture documentation
PlantUML Skill: Generate PlantUML diagrams from source code, extract diagrams from Markdown, and create image-linked documentation
Image Generation: Uses Gemini Banana to generate images for documentation and design work
SDD Skill: A comprehensive Claude Code skill for guiding users through GitHub’s Spec-Kit and the Spec-Driven Development methodology.
PR Reviewer Skill: Comprehensive GitHub PR code review skill for Claude Code. Automates data collection via gh CLI, analyzes against industry-standard criteria (security, testing, maintainability), generates structured review files, and posts feedback with approval workflow. Includes inline comments, ticket tracking, and professional review templates.

AI Model Integration

Gemini Skill: Delegate specific tasks to Google’s Gemini AI for multi-model collaboration
Image_gen: Image generation skill that uses Gemini Banana to generate images.

Explore more at Spillwave Solutions — specialists in bespoke software development and AI-powered automation.

Full Skill Markdown file

---
name: project-memory
description: Set up and maintain a structured project memory system in docs/project_notes/ that tracks bugs with solutions, architectural decisions, key project facts, and work history. Use this skill when asked to "set up project memory", "track our decisions", "log a bug fix", "update project memory", or "initialize memory system". Configures both CLAUDE.md and AGENTS.md to maintain memory awareness across different AI coding tools.
---

# Project Memory
 
## Table of Contents

- [Overview](#overview)
- [When to Use This Skill](#when-to-use-this-skill)
- [Core Capabilities](#core-capabilities)
  - [1. Initial Setup - Create Memory Infrastructure](#1-initial-setup---create-memory-infrastructure)
  - [2. Configure CLAUDE.md - Memory-Aware Behavior](#2-configure-claudemd---memory-aware-behavior)
  - [3. Configure AGENTS.md - Multi-Tool Support](#3-configure-agentsmd---multi-tool-support)
  - [4. Searching Memory Files](#4-searching-memory-files)
  - [5. Updating Memory Files](#5-updating-memory-files)
  - [6. Memory File Maintenance](#6-memory-file-maintenance)
- [Templates and References](#templates-and-references)
- [Example Workflows](#example-workflows)
- [Integration with Other Skills](#integration-with-other-skills)
- [Success Criteria](#success-criteria)

## Overview

Maintain institutional knowledge for projects by establishing a structured memory system in `docs/project_notes/`. This skill sets up four key memory files (bugs, decisions, key facts, issues) and configures CLAUDE.md and AGENTS.md to automatically reference and maintain them. The result is a project that remembers past decisions, solutions to problems, and important configuration details across coding sessions and across different AI tools.

## When to Use This Skill

Invoke this skill when:

- Starting a new project that will accumulate knowledge over time
- The project already has recurring bugs or decisions that should be documented
- The user asks to "set up project memory" or "track our decisions"
- The user wants to log a bug fix, architectural decision, or completed work
- Encountering a problem that feels familiar ("didn't we solve this before?")
- Before proposing an architectural change (check existing decisions first)
- Working on projects with multiple developers or AI tools (Claude Code, Cursor, etc.)

## Core Capabilities

### 1. Initial Setup - Create Memory Infrastructure

When invoked for the first time in a project, create the following structure:

```
docs/
└── project_notes/
    ├── bugs.md         # Bug log with solutions
    ├── decisions.md    # Architectural Decision Records
    ├── key_facts.md    # Project configuration and constants
    └── issues.md       # Work log with ticket references
```

**Directory naming rationale:** Using `docs/project_notes/` instead of `memory/` makes it look like standard engineering organization, not AI-specific tooling. This increases adoption and maintenance by human developers.

**Initial file content:** Copy templates from the `references/` directory in this skill:
- Use `references/bugs_template.md` for initial `bugs.md`
- Use `references/decisions_template.md` for initial `decisions.md`
- Use `references/key_facts_template.md` for initial `key_facts.md`
- Use `references/issues_template.md` for initial `issues.md`

Each template includes format examples and usage tips.

### 2. Configure CLAUDE.md - Memory-Aware Behavior

Add or update the following section in the project's `CLAUDE.md` file:

```markdown
## Project Memory System

This project maintains institutional knowledge in `docs/project_notes/` for consistency across sessions.

### Memory Files

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

### Memory-Aware Protocols

**Before proposing architectural changes:**
- Check `docs/project_notes/decisions.md` for existing decisions
- Verify the proposed approach doesn't conflict with past choices
- If it does conflict, acknowledge the existing decision and explain why a change is warranted

**When encountering errors or bugs:**
- Search `docs/project_notes/bugs.md` for similar issues
- Apply known solutions if found
- Document new bugs and solutions when resolved

**When looking up project configuration:**
- Check `docs/project_notes/key_facts.md` for credentials, ports, URLs, service accounts
- Prefer documented facts over assumptions

**When completing work on tickets:**
- Log completed work in `docs/project_notes/issues.md`
- Include ticket ID, date, brief description, and URL

**When user requests memory updates:**
- Update the appropriate memory file (bugs, decisions, key_facts, or issues)
- Follow the established format and style (bullet lists, dates, concise entries)

### Style Guidelines for Memory Files

- **Prefer bullet lists over tables** for simplicity and ease of editing
- **Keep entries concise** (1-3 lines for descriptions)
- **Always include dates** for temporal context
- **Include URLs** for tickets, documentation, monitoring dashboards
- **Manual cleanup** of old entries is expected (not automated)
```

### 3. Configure AGENTS.md - Multi-Tool Support

If the project has an `AGENTS.md` file (used for agent workflows or multi-tool projects), add the same memory protocols. This ensures consistency whether using Claude Code, Cursor, GitHub Copilot, or other AI tools.

**If AGENTS.md exists:** Add the same "Project Memory System" section as above.

**If AGENTS.md doesn't exist:** Ask the user if they want to create it. Many projects use multiple AI tools and benefit from shared memory protocols.

### 4. Searching Memory Files

When encountering problems or making decisions, proactively search memory files:

**Search bugs.md:**
```bash
# Look for similar errors
grep -i "connection refused" docs/project_notes/bugs.md

# Find bugs by date range
grep "2025-01" docs/project_notes/bugs.md
```

**Search decisions.md:**
```bash
# Check for decisions about a technology
grep -i "database" docs/project_notes/decisions.md

# Find all ADRs
grep "^### ADR-" docs/project_notes/decisions.md
```

**Search key_facts.md:**
```bash
# Find database connection info
grep -A 5 "Database" docs/project_notes/key_facts.md

# Look up service accounts
grep -i "service account" docs/project_notes/key_facts.md
```

**Use Grep tool for more complex searches:**
- Search across all memory files: `Grep(pattern="oauth", path="docs/project_notes/")`
- Context-aware search: `Grep(pattern="bug", path="docs/project_notes/bugs.md", -A=3, -B=3)`

### 5. Updating Memory Files

When the user requests updates or when documenting resolved issues, update the appropriate memory file:

**Adding a bug entry:**
```markdown
### YYYY-MM-DD - Brief Bug Description
- **Issue**: What went wrong
- **Root Cause**: Why it happened
- **Solution**: How it was fixed
- **Prevention**: How to avoid it in the future
```

**Adding a decision:**
```markdown
### ADR-XXX: Decision Title (YYYY-MM-DD)

**Context:**
- Why the decision was needed
- What problem it solves

**Decision:**
- What was chosen

**Alternatives Considered:**
- Option 1 -> Why rejected
- Option 2 -> Why rejected

**Consequences:**
- Benefits
- Trade-offs
```

**Adding key facts:**
- Organize by category (GCP Project, Database, API, Local Development, etc.)
- Use bullet lists for clarity
- Include both production and development details
- Add URLs for easy navigation
- See `references/key_facts_template.md` for security guidelines on what NOT to store

**Adding work log entry:**
```markdown
### YYYY-MM-DD - TICKET-ID: Brief Description
- **Status**: Completed / In Progress / Blocked
- **Description**: 1-2 line summary
- **URL**: https://jira.company.com/browse/TICKET-ID
- **Notes**: Any important context
```

### 6. Memory File Maintenance

**Periodically clean old entries:**
- User is responsible for manual cleanup (no automation)
- Remove very old bug entries (6+ months) that are no longer relevant
- Archive completed work from issues.md (3+ months old)
- Keep all decisions (they're lightweight and provide historical context)
- Update key_facts.md when project configuration changes

**Conflict resolution:**
- If proposing something that conflicts with decisions.md, explain why revisiting the decision is warranted
- Update the decision entry if the choice changes
- Add date of revision to show evolution

## Templates and References

This skill includes template files in `references/` that demonstrate proper formatting:

- **references/bugs_template.md** - Bug entry format with examples
- **references/decisions_template.md** - ADR format with examples
- **references/key_facts_template.md** - Key facts organization with examples (includes security guidelines)
- **references/issues_template.md** - Work log format with examples

When creating initial memory files, copy these templates to `docs/project_notes/` and customize them for the project.

## Example Workflows

### Scenario 1: Encountering a Familiar Bug

```
User: "I'm getting a 'connection refused' error from the database"
-> Search docs/project_notes/bugs.md for "connection"
-> Find previous solution: "Use AlloyDB Auth Proxy on port 5432"
-> Apply known fix
```

### Scenario 2: Proposing an Architectural Change

```
Internal: "User might benefit from using SQLAlchemy for migrations"
-> Check docs/project_notes/decisions.md
-> Find ADR-002: Already decided to use Alembic
-> Use Alembic instead, maintaining consistency
```

### Scenario 3: User Requests Memory Update

```
User: "Add that CORS fix to our bug log"
-> Read docs/project_notes/bugs.md
-> Add new entry with date, issue, solution, prevention
-> Confirm addition to user
```

### Scenario 4: Looking Up Project Configuration

```
Internal: "Need to connect to database"
-> Check docs/project_notes/key_facts.md
-> Find Database Configuration section
-> Use documented connection string and credentials
```

## Tips for Effective Memory Management

1. **Be proactive**: Check memory files before proposing solutions
2. **Be concise**: Keep entries brief (1-3 lines for descriptions)
3. **Be dated**: Always include dates for temporal context
4. **Be linked**: Include URLs to tickets, docs, monitoring dashboards
5. **Be selective**: Focus on recurring or instructive issues, not every bug

## Integration with Other Skills

The project-memory skill complements other skills:

- **requirements-documenter**: Requirements -> Decisions (ADRs reference requirements)
- **root-cause-debugger**: Bug diagnosis -> Bug log (document solutions after fixes)
- **code-quality-reviewer**: Quality issues -> Decisions (document quality standards)
- **docs-sync-editor**: Code changes -> Key facts (update when config changes)

When using these skills together, consider updating memory files as a follow-up action.

## Success Criteria

This skill is successfully deployed when:

- `docs/project_notes/` directory exists with all four memory files
- CLAUDE.md includes "Project Memory System" section with protocols
- AGENTS.md includes the same protocols (if file exists or user requested)
- Memory files follow template format and style guidelines
- AI assistant checks memory files before proposing changes
- User can easily request memory updates ("add this to bugs.md")
- Memory files look like standard engineering documentation, not AI artifacts

Subscribe To

Rick

Monday, January 12, 2026