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 workflows, rules, prompts, and skills
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)
        ├── workflows/         ← Optional: Workflow files
        ├── rules/             ← Optional: Rule files
        ├── skills/            ← Optional: Skill files
        └── prompts/           ← Optional: Prompt 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: workflows/, rules/, skills/, prompts/
All files must be text-based (see File Requirements below)

File Requirements & Restrictions

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

Maximum file size is 500KB. Files larger than this will be rejected during sync.

Encoding Requirement

All files must be valid UTF-8 text. Binary files are automatically rejected.

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

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 all resources
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 code examples with executable extensions

For Registry Users

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

Why These Restrictions?

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! Use Markdown code blocks (.md files) to include code examples safely. Don't upload actual .js, .py, or other executable files. 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?

Paste the script content into a Markdown file with proper code fencing. Users can copy and save it locally if needed. This keeps the registry safe while still allowing script sharing.

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.