Own a shelf of AI resources, accessible to your team, right in your IDE

AIShelf registries enforce security policies to protect your team. This guide covers registry structure, file requirements, security validation, and best practices.

What is an AIShelf Registry?

A GitHub repository with a specific structure that stores AI resources for your team:

Centralized storage for AI skills, prompts, rules, and workflows
Version control through Git and GitHub
Team collaboration with access control via GitHub permissions
Automatic syncing across all team members' IDEs

Structure Requirements

Registry Structure

your-registry/
├── ai_shelf_registry.json    ← Required: Registry metadata
└── packages/                  ← Required: Contains all packages
    └── package-name/          ← Package folder (any name)
        ├── skills/            ← Optional: Skill folders
        │   └── skill-name/    ← Each skill is a folder
        │       ├── SKILL.md   ← Required: Skill documentation
        │       └── ...        ← Optional: Scripts, configs, etc.
        ├── prompts/           ← Optional: Prompt files
        ├── rules/             ← Optional: Rule files
        └── workflows/         ← Optional: Workflow files

Required: ai_shelf_registry.json

This file contains metadata about your registry:

ai_shelf_registry.json

{
  "name": "Your Registry Name",
  "description": "What this registry contains",
  "version": "1.0.0",
  "created": "2026-03-12"
}

Package Structure

No package.json required - organize however you want
Create folders for resource types: skills/ (folders containing SKILL.md + other files), prompts/, rules/, and workflows/ (single files)
Skills have no file restrictions. Prompts, rules, and workflows must be text-based files (see File Requirements below).

Skills vs Other Resources

Skills

Folders containing multiple files
Must include SKILL.md documentation
Can include scripts, configs, etc.
Example: skills/pytest-helper/SKILL.md

Prompts, Rules, Workflows

Single Markdown files
Stored directly in resource folder
Example: prompts/explain-code.md

Why Folders for Skills?

Skills often need supporting files (scripts, configurations, templates) alongside documentation. The folder structure keeps everything organized together.

File Requirements & Restrictions

Applies to Prompts, Rules, and Workflows Only

The file type restrictions below apply to prompts/, rules/, and workflows/ folders. Skills folders have no file type restrictions — you can include any files (scripts, configs, binaries, etc.) inside skill folders.

Allowed File Types

Markdown files (.md) - Recommended
Text files (.txt)
JSON files (.json)
YAML files (.yaml, .yml)
XML files (.xml)
CSV files (.csv)
Any other text-based formats

Blocked File Types

Shell scripts:

.sh, .bash, .zsh, .fish, .ksh, .csh

Windows scripts:

.bat, .cmd, .ps1, .vbs, .vbe, .wsf, .wsh, .msc, .reg

Executables:

.exe, .com, .msi, .deb, .rpm, .pkg, .dmg, .app, .run, .bin

Language runtimes:

.py, .pyw, .rb, .rake, .pl, .php, .js, .mjs, .cjs, .ts, .jar, .war, .ear, .lua

Binary/compiled:

.so, .dll, .dylib, .class, .o, .a

macOS automation:

.applescript, .scpt

Size Limit (Prompts, Rules, Workflows)

Maximum file size is 500KB for prompts, rules, and workflows. Files larger than this will be rejected during sync. Skills have no size limit.

Encoding Requirement (Prompts, Rules, Workflows)

Prompts, rules, and workflows must be valid UTF-8 text. Binary files are automatically rejected. Skills can contain any file type, including binaries.

File Naming Best Practices

Use descriptive names: pr-review-checklist.md not workflow1.md
Use hyphens for spaces: code-review-helper.md
Include version in name if needed: api-docs-v2.md

Repository Access Model

AIShelf operates with a read-focused approach to protect your repositories:

Read Operations (Automatic)

When you connect to a registry, AIShelf performs these operations automatically:

Clone: Creates a local copy of your registry on your machine
Pull: Syncs the latest changes from GitHub to your local copy
Read: Displays registry content in your IDE

Write Operations (User-Initiated Only)

AIShelf only writes to repositories when you explicitly request it:

Create New Registry: When you choose to create a new repository through AIShelf
Publish Changes: When you explicitly publish your local changes to GitHub

Local-Only Operations

All registry operations happen locally on your machine. AIShelf never automatically pushes changes to your GitHub repositories.

What This Means for You

Your repositories are safe from accidental modifications
You maintain full control over what gets pushed to GitHub
All changes are reviewed by you before publishing
We recommend maintaining regular backups of your repositories as a best practice

Security Validation System

Applies to Prompts, Rules, and Workflows Only

The security validations below apply to prompts/, rules/, and workflows/ folders. Skills folders are not validated — you have full control over skill contents.

AIShelf uses multiple layers of security to protect you:

1. File Extension Validation

Blocks 40+ dangerous file types to prevent executable code.

2. UTF-8 Encoding Check

Ensures all files are text-based and catches binary files.

3. File Size Validation

500KB limit per file prevents repository bloat.

4. Path Traversal Protection

Blocks ../ and absolute paths.

5. OS-Level Permission Stripping (Linux/macOS)

Removes execute permissions from all files. On Windows, relies on extension blocklist.

User Control

Violations prompt you to Continue or Abort. All operations are atomic. See detailed reports in the output channel.

Your Responsibility

Bypassing security warnings means you accept responsibility for any issues. Review violations carefully before connecting.

Best Practices

For Registry Creators

Use Markdown (.md) for prompts, rules, and workflows
Keep files under 100KB for best performance
Organize packages by team/project
Include descriptive ai_shelf_registry.json
Use meaningful package names
Don't upload executable files to prompts/rules/workflows folders (use skills for scripts)

For Registry Users

Review registry contents before connecting
Sync regularly to get team updates
Report suspicious registries to support

Why These Restrictions for Prompts, Rules, and Workflows?

Security First

Protects users from malicious code execution
Prevents supply chain attacks via registries
Ensures team safety when sharing resources

Performance

Text files load instantly
Small files sync quickly
No bandwidth waste on large binaries

Compatibility

UTF-8 text works everywhere
Markdown renders beautifully in all IDEs
No platform-specific issues

Frequently Asked Questions

Can I store code examples in my registry?

Yes! For prompts, rules, and workflows, use Markdown code blocks (.md files) to include code examples safely. For skills, you can include actual script files in the skill folder. For example:

# Python Testing Workflow

```python
def test_example():
    assert 1 + 1 == 2
```

Use this pattern for all your tests.

What if I need to share a script with my team?

Option 1 (Recommended): Create a skill folder and include the actual script file. Skills have no file restrictions.

Option 2: For prompts/rules/workflows, paste the script content into a Markdown file with proper code fencing. Users can copy and save it locally if needed.

Can I use my existing GitHub repo as a registry?

Yes, if it has the required ai_shelf_registry.json file and follows the structure requirements. AIShelf will validate it when you connect.

What happens if my registry has violations?

You'll see a detailed report and can choose to continue (accept risk) or abort (disconnect). We recommend fixing violations for team safety. Check the Output panel (View → Output → AIShelf) for detailed information.