# System Skills Pattern Template

A GitHub repository template for building **System Skills** - self-contained personal data systems that Claude can animate via CLI + SKILL.md + SQLite.

## The Pattern

**CLI + SKILL.md + Database**

Give Claude a command-line tool to run, instructions on how to operate a system, and a database to remember things. Watch it turn the crank, running its own OODA loop (Observe, Orient, Decide, Act) - building context that compounds across sessions.

```
┌─────────────────────────────────────────────────────────────────┐
│                    THE SYSTEM SKILL PATTERN                      │
│                                                                  │
│  ┌──────────┐     ┌──────────────┐     ┌──────────────────┐     │
│  │   CLI    │ ←── │   SKILL.md   │ ──→ │  SQLite Database │     │
│  │  Binary  │     │  (Tutorial)  │     │   (Persistence)  │     │
│  └──────────┘     └──────────────┘     └──────────────────┘     │
│       │                  │                      │                │
│       ▼                  ▼                      ▼                │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                      CLAUDE                               │   │
│  │  Observe → Orient → Decide → Act (OODA Loop)             │   │
│  │  Context compounds over time as data accumulates         │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
```

## Quick Start

1. **Use this template** - Click "Use this template" on GitHub to create your own repo
2. **Customize placeholders** - Replace `{{SKILL_NAME}}` with your skill name throughout
3. **Design your schema** - Edit `src/cli/db.ts` with your data model
4. **Build your CLI** - Implement commands in `src/cli/main.ts`
5. **Write SKILL.md** - Document how Claude should operate your system
6. **Build & Install** - Run `./build.sh` then `./install.sh`

## Repository Structure

```
your-skill/
├── .claude-plugin/
│   ├── plugin.json          # Plugin manifest
│   └── marketplace.json     # Marketplace configuration
├── src/
│   ├── SKILL.md             # Claude's operating instructions
│   └── cli/
│       ├── main.ts          # CLI entry point
│       ├── db.ts            # Database operations
│       └── deno.json        # Deno dependencies
├── dist/
│   └── skills/
│       └── {{skill-name}}/  # Built output (binary + SKILL.md)
├── build.sh                 # Compiles TypeScript to binary
├── install.sh               # Copies to ~/.claude/skills/
├── .gitignore
└── README.md
```

## The Three Components

### 1. CLI Binary

A standalone executable that provides handles for Claude to operate your system:

```bash
./your-skill add --item "Something to track"
./your-skill list --filter recent
./your-skill stats --period week
```

**Key attributes:**
- Self-contained (no runtime dependencies)
- Helpful `--help` documentation
- JSON output option (`--json`) for programmatic use
- Built with Deno for easy compilation

### 2. SKILL.md

The tutorial that teaches Claude how to think about and operate your system:

- What the system is and when to use it
- Which commands to run in different situations
- How to interpret output and look for patterns
- The mental model and decision flow

This is where you share the operating procedure. Claude uses this to run its OODA loop.

### 3. SQLite Database

Persistent storage that accumulates value over time. Keep it simple:

```sql
CREATE TABLE items (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  content TEXT NOT NULL,
  created_at TEXT NOT NULL,
  metadata TEXT  -- JSON for flexible fields
);
```

**Why SQLite:**
- Self-contained (just a file)
- Zero configuration
- Easy to backup
- Claude can query directly if needed

## Customization Guide

### Step 1: Replace Placeholders

Search and replace these placeholders throughout the template:

| Placeholder | Description | Example |
|------------|-------------|---------|
| `{{SKILL_NAME}}` | Display name | "Task Manager" |
| `{{skill-name}}` | Lowercase with dashes | "task-manager" |
| `{{skill_name}}` | Lowercase with underscores | "task_manager" |
| `{{SKILL_DESCRIPTION}}` | One-line description | "Personal task tracking with priorities" |
| `{{AUTHOR_NAME}}` | Your name | "Your Name" |
| `{{AUTHOR_EMAIL}}` | Your email | "you@example.com" |
| `{{GITHUB_USERNAME}}` | GitHub username | "yourusername" |

### Step 2: Design Your Data Model

Edit `src/cli/db.ts`:

1. Define your TypeScript interfaces
2. Create your SQLite schema
3. Implement CRUD operations
4. Add any analytics/aggregation queries

### Step 3: Build Your CLI Commands

Edit `src/cli/main.ts`:

1. Define your command structure
2. Implement each command handler
3. Add proper `--help` documentation
4. Support `--json` output for all commands

### Step 4: Write Your SKILL.md

Your SKILL.md should include:

- **Overview**: What the skill does
- **Mental Model**: How Claude should think about the system
- **Decision Tree**: Quick reference for which commands to use
- **Core Commands**: Detailed documentation for each command
- **Workflows**: Common multi-step operations
- **Pattern Recognition**: How to derive insights as data accumulates
- **Best Practices**: Tips for effective use

## Building & Installing

### Requirements

- [Deno](https://deno.land/) 2.5 or later

### Build

```bash
./build.sh
```

This compiles your TypeScript to a standalone binary with baked-in security permissions:
- No network access
- No environment variable access (except HOME)
- Can read/write files on disk

### Install

```bash
./install.sh
```

Copies the built skill to `~/.claude/skills/{{skill-name}}/`

## Example Ideas

**Personal Finance Manager**
- CLI: `money tx list`, `money note abc-123 "unexpected!"`, `money cat abc-123 "vacation"`
- Database: Transactions with amounts, categories, notes
- Result: Claude watches spending trends and asks about anomalies

**Project Management**
- CLI: `task new "rake leaves"`, `task update T-123 --status=done`, `task kanban`
- Database: Tasks with status, due date, priority
- Result: "What are my top 3 priorities for the week?"

**Gratitude Journal**
- CLI: `thankful "for my cat"`, `thankful trends`, `thankful search`
- Database: Entries with message and timestamp
- Result: A journal that talks back and lifts you up

**Morning Briefing**
- CLI: `pulse topic add "AI safety"`, `pulse generate`, `pulse feedback <id> --helpful`
- Database: Topics, generated briefings, feedback
- Result: Personalized morning briefing that learns what's useful

**Note Taker with Memory**
- CLI: `note add "API design thoughts"`, `note search "auth"`, `note tag T-123 "urgent"`
- Database: Notes with tags and full-text search
- Result: Claude recalls and connects ideas across sessions

## Why This Matters

Most Claude Skills are stateless - they run and forget. The System Skill Pattern enables:

- **Memory**: Every interaction saved, building context over time
- **Learning**: Patterns emerge from accumulated data
- **Compounding value**: The tool gets more useful with use
- **Autonomy**: Claude animates the system rather than just responding

When you give Claude the handles to operate a system - a CLI to run commands, a database to remember things, and a tutorial on how it all works - it runs its own OODA loop, building context that compounds over time.

## License

MIT

## Credits

Based on [The System Skill Pattern](https://www.shruggingface.com/blog/the-system-skill-pattern) by Jake Dahn.
Reference implementation: [github.com/jakedahn/pomodoro](https://github.com/jakedahn/pomodoro)