# How to Set Up Custom Patterns in Fabric: Complete Configuration Guide

> Learn to set up custom patterns in Fabric easily. Use the `fabric --setup` command to create your private, update-safe prompts that override defaults.

- Repository: [Daniel Miessler 🛡️/fabric](https://github.com/danielmiessler/fabric)
- Tags: how-to-guide
- Published: 2026-02-28

---

**Run `fabric --setup` to configure a custom patterns directory, then create subfolders containing a [`system.md`](https://github.com/danielmiessler/fabric/blob/main/system.md) file to extend Fabric with private, update-safe prompts that take precedence over built-in patterns.**

Fabric treats a **pattern** as a reusable prompt package comprising system, user, and optional configuration files. While the tool ships with a built-in collection stored in `data/patterns`, you can create a **custom patterns directory** to store private prompts that persist across application updates. Setting up custom patterns in Fabric involves configuring a directory path via the interactive setup or environment variables, then populating it with standard Fabric pattern structures.

## How Custom Patterns Work in Fabric

Fabric’s architecture uses three core components to enable custom pattern support without modifying the core codebase.

### The CustomPatterns Plugin

Located in [`internal/tools/custom_patterns/custom_patterns.go`](https://github.com/danielmiessler/fabric/blob/main/internal/tools/custom_patterns/custom_patterns.go), the **CustomPatterns plugin** registers an interactive setup question that prompts for your custom directory path. It automatically expands the `~` character to your home directory, resolves the absolute path, and creates the folder if it does not exist. The plugin exposes an `IsConfigured()` method that checks whether a valid custom directory has been set.

### The PatternsLoader

The **PatternsLoader** in [`internal/tools/patterns_loader.go`](https://github.com/danielmiessler/fabric/blob/main/internal/tools/patterns_loader.go) handles the actual pattern discovery. When loading patterns, it always scans the built-in folder (`o.Patterns.Dir`) **and** the path stored in `CustomPatterns.CustomPatternsDir`. It merges both sets into a unified map, adding custom entries **after** built-in ones. This merge order ensures that custom patterns take precedence when names collide.

### The PluginRegistry

The **PluginRegistry** in [`internal/core/plugin_registry.go`](https://github.com/danielmiessler/fabric/blob/main/internal/core/plugin_registry.go) wires the CustomPatterns plugin into the global registry. This integration ensures the plugin participates in the interactive `fabric --setup` flow and writes its configuration values into the generated `.env` file.

## Step-by-Step: Configure Your Custom Patterns Directory

### Run the Interactive Setup

Execute the setup command and select the Custom Patterns option:

```bash
fabric --setup

```

When prompted, enter an absolute or relative path (e.g., `~/my-custom-patterns`). Fabric expands the tilde to your home directory, resolves the full absolute path, and creates the directory if it is missing. This path is then written to your `.env` configuration file.

### Verify the Configuration

After setup, your `.env` file contains the `CUSTOM_PATTERNS_DIRECTORY` variable (derived from the plugin's `EnvNamePrefix`). The `CustomPatterns.IsConfigured()` method returns `true` when this variable points to a valid directory, signaling the PatternsLoader to include it in subsequent scans.

## Creating Custom Pattern Files

Once the directory is configured, populate it with pattern folders following the same structure as built-in patterns.

### Required and Optional Files

Each subfolder inside your custom directory represents a single pattern identified by its folder name:

- **Required:** [`system.md`](https://github.com/danielmiessler/fabric/blob/main/system.md) — Contains the system prompt instructions.
- **Optional:** [`user.md`](https://github.com/danielmiessler/fabric/blob/main/user.md) — Contains default user prompt content.
- **Optional:** [`config.json`](https://github.com/danielmiessler/fabric/blob/main/config.json) — Contains pattern-specific configuration parameters.

### Example Pattern Creation

Create a custom pattern named `my-analyzer`:

```bash
mkdir -p ~/my-custom-patterns/my-analyzer

cat > ~/my-custom-patterns/my-analyzer/system.md <<'EOF'
You are an expert security analyst. Provide concise, factual answers focusing on vulnerabilities and mitigation strategies.
EOF

cat > ~/my-custom-patterns/my-analyzer/user.md <<'EOF'
Analyze the following input for security risks:
EOF

```

Invoke the pattern using the standard flag:

```bash
fabric --pattern my-analyzer "Open ports 22, 80, and 443 detected on the server"

```

## Pattern Resolution and Precedence

### Runtime Merging Behavior

When you execute `fabric --listpatterns`, the loader displays both built-in and custom pattern names. During execution, the loader in [`internal/tools/patterns_loader.go`](https://github.com/danielmiessler/fabric/blob/main/internal/tools/patterns_loader.go) populates the pattern map in two phases:

1. **Built-in patterns** are loaded from the default `data/patterns` directory.
2. **Custom patterns** are loaded from `CustomPatterns.CustomPatternsDir` and added to the same map.

Because custom entries are added after built-in ones, **custom patterns automatically override built-in patterns** when sharing the same identifier. This precedence mechanism ensures your private definitions always take priority without deleting or modifying the original built-in files.

### Environment Variable Configuration

Instead of using interactive setup, you can manually define the directory in your `.env` file:

```env
CUSTOM_PATTERNS_DIRECTORY=/home/user/fabric-patterns

```

Fabric reads this variable on startup. The PatternsLoader merges this directory automatically whenever `IsConfigured()` returns true, ensuring your custom prompts persist across application upgrades.

## Summary

- **Custom patterns** in Fabric are stored in a user-defined directory separate from the built-in `data/patterns` collection to prevent update overwrites.
- Configure the directory via `fabric --setup` or by setting the `CUSTOM_PATTERNS_DIRECTORY` environment variable in your `.env` file.
- The **CustomPatterns plugin** ([`internal/tools/custom_patterns/custom_patterns.go`](https://github.com/danielmiessler/fabric/blob/main/internal/tools/custom_patterns/custom_patterns.go)) handles path resolution and directory creation.
- The **PatternsLoader** ([`internal/tools/patterns_loader.go`](https://github.com/danielmiessler/fabric/blob/main/internal/tools/patterns_loader.go)) merges built-in and custom directories, with custom patterns taking precedence due to later insertion into the pattern map.
- Each pattern requires at least a [`system.md`](https://github.com/danielmiessler/fabric/blob/main/system.md) file inside a named subfolder; optional [`user.md`](https://github.com/danielmiessler/fabric/blob/main/user.md) and [`config.json`](https://github.com/danielmiessler/fabric/blob/main/config.json) files follow the same conventions as built-in patterns.

## Frequently Asked Questions

### Where does Fabric store the custom patterns directory configuration?

Fabric stores the path in your `.env` file using the variable `CUSTOM_PATTERNS_DIRECTORY`. The **CustomPatterns plugin** writes this value during interactive setup (`fabric --setup`) and the **PluginRegistry** ensures it persists across sessions.

### What happens if a custom pattern has the same name as a built-in pattern?

The custom pattern takes precedence. In [`internal/tools/patterns_loader.go`](https://github.com/danielmiessler/fabric/blob/main/internal/tools/patterns_loader.go), the loader adds custom patterns to the map **after** built-in patterns. When duplicate keys exist, the later entry (your custom version) overwrites the earlier one, ensuring your private definitions are always used.

### Can I use environment variables instead of running `fabric --setup`?

Yes. Manually add `CUSTOM_PATTERNS_DIRECTORY=/path/to/folder` to your `.env` file. The **PatternsLoader** checks `IsConfigured()` from the CustomPatterns plugin; if the directory exists and is readable, Fabric automatically merges it with the built-in pattern set without requiring interactive setup.

### What files are required to create a valid custom pattern?

You must include a [`system.md`](https://github.com/danielmiessler/fabric/blob/main/system.md) file inside a subfolder of your custom patterns directory. The subfolder name becomes the pattern identifier. Optional files include [`user.md`](https://github.com/danielmiessler/fabric/blob/main/user.md) for default user prompts and [`config.json`](https://github.com/danielmiessler/fabric/blob/main/config.json) for pattern-specific settings, mirroring the structure found in the built-in `data/patterns` directory.