instructionkit 0.3.0

CLI tool for managing AI coding tool instructions

🎯 InstructionKit

Get your AI coding assistant following best practices in under 2 minutes

Supports: Cursor • GitHub Copilot • Windsurf • Claude Code

---

🚀 Get Started in 60 Seconds

# 1. Install
pip install instructionkit

# 2. Download instruction repository (with optional version control)
inskit download --repo https://github.com/troylar/instructionkit-examples
# Or pin to a specific version:
# inskit download --repo https://github.com/user/repo --ref v1.0.0

# 3. Browse & install with interactive TUI
inskit install

✨ What you just got:

• 🐍 Python best practices (type hints, async patterns)
• ⚛️ React & TypeScript patterns
• 🧪 Testing with pytest
• 🔐 Security (OWASP Top 10)
• 🐳 Docker optimization
• 📝 Documentation standards
• ...and more!

Your AI assistant now follows these guidelines automatically when you code. No configuration needed.

👉 Browse all 12 examples or keep reading to use your own instructions.

---

🌟 What is InstructionKit?

A powerful CLI tool that enables developers to browse, install, and manage instructions for AI coding assistants. Download instruction repositories to your local library, browse them with an interactive TUI, and install exactly what you need.

Perfect for:

• ⚡️ Getting started fast with curated examples
• 🏢 Standardizing team practices across projects
• 📚 Building personal libraries of coding patterns
• 🔄 Sharing knowledge across your organization

CLI name: Commands use inskit (short for InstructionKit)

✨ Features

🎨 Interactive TUI Browser Browse your instruction library with a beautiful terminal UI Search and filter instructions by name, description, or repository Select multiple instructions with checkboxes Choose installation location and target tools interactively See exactly where files will be installed before confirming	📚 Local Library Management Download instruction repositories to your local library Keep multiple repositories organized in one place Update repositories to get the latest instructions List and delete repositories from your library Fast offline browsing once downloaded
🎯 Project-Level Installation All installations are project-specific Automatic project root detection Organized in tool-specific directories (.cursor/rules/, .claude/rules/, etc.) Clean, versioned alongside your code Portable tracking with relative paths (works across teams and machines)	📦 Flexible Sources & Versioning Download from Git repositories (GitHub, GitLab, Bitbucket, self-hosted) Version Control: Pin to tags, track branches, or lock to commits Download from local folders (perfect for testing and development) Support for private repositories with standard Git authentication Bundle support for installing multiple instructions at once Automatic updates for branch-based installations
🎯 Smart Management Auto-detect installed AI coding tools Track all installed instructions with metadata Smart conflict resolution (skip, rename, overwrite) Easy uninstall functionality	🔐 Enterprise Ready Works with private repositories No external dependencies beyond Git Secure, local-only storage Cross-platform support (macOS, Linux, Windows)

📚 Using Your Own Instructions

Want to use company or custom instructions instead? It's just as easy:

# Download from your GitHub repo
inskit download --from https://github.com/yourcompany/instructions

# Browse and install with the TUI
inskit install

The interactive TUI lets you:

• 🔍 Search and filter by tags
• ☑️ Select multiple instructions
• 🎯 Choose which AI tools to install to
• 📦 See exactly what gets installed

Managing your library:

inskit list library              # See what's downloaded
inskit update --all              # Get latest updates
inskit delete <repo-namespace>   # Remove a repository

Alternative: Direct Installation

For quick one-off installs without using the library:

# Direct install (bypasses library)
inskit install python-best-practices --from https://github.com/company/instructions

# See what's available from a repo
inskit list available --from https://github.com/company/instructions

📖 Usage

Library Management

Download Instructions to Your Library

Build your local library of instruction repositories with version control:

# Download from Git repository (default branch)
inskit download --repo https://github.com/company/instructions

# Download specific version by tag (pinned, won't auto-update)
inskit download --repo https://github.com/company/instructions --ref v1.0.0

# Download specific branch (will auto-update)
inskit download --repo https://github.com/company/instructions --ref main

# Download specific commit (pinned, won't auto-update)
inskit download --repo https://github.com/company/instructions --ref abc123def

# Download from local folder (no version control)
inskit download --repo ./my-instructions

# Re-download to get latest updates
inskit download --repo https://github.com/company/instructions --force

Version Control Benefits:

• 📌 Tags: Pin to specific releases (e.g., v1.0.0) - won't auto-update
• 🌿 Branches: Track latest changes (e.g., main, develop) - auto-updates
• 📍 Commits: Lock to exact state (e.g., abc123) - won't auto-update
• 📦 Multiple Versions: Install different versions of same repo side-by-side

Your library is stored in ~/.instructionkit/library/ and organized by repository namespace and version.

List Your Library Contents

# Show all repositories in library
inskit list library

# Show individual instructions
inskit list library --instructions

# Filter by repository alias
inskit list library --source company

Update Library Repositories

# Update a specific repository
inskit update --namespace github.com_company_instructions

# Update all repositories in library
inskit update --all

Smart Update Behavior:

• 🌿 Branches: Automatically pull latest changes from remote
• 📌 Tags: Skipped (immutable - won't update)
• 📍 Commits: Skipped (immutable - won't update)
• 🔄 Installed Files: Automatically updated after pulling changes

Example Output:

Updating 3 repository(ies)...

⊘ Skipped: python-standards (tag v1.0.0 is immutable)
✓ Updated: react-patterns (branch main)
✓ Updated: api-guidelines (branch develop)

✓ Updated: 2 repository(ies)
⊘ Skipped: 1 immutable reference(s)

Delete from Library

# Delete a repository (keeps installed instructions)
inskit delete github.com_company_instructions

# Skip confirmation
inskit delete github.com_company_instructions --force

Note: Deleting from library doesn't uninstall instructions. Use inskit uninstall for that.

Interactive TUI Browser

Using the TUI to Browse and Install

Launch the interactive browser:

inskit install

TUI Features:

• Search: Type / to search by name or description
• Filter: Select repository from dropdown
• Select: Use Space or Enter to toggle instruction selection
• Select All: Press Ctrl+A or click "Select All" button
• Target Tools: Check boxes for Cursor, Windsurf, Claude Code, etc.
• Install: Review summary and click "📦 Install Selected"

The TUI shows exactly where files will be installed in your project before you confirm.

Install Specific Instruction by Name

Install directly from library without TUI:

# Install by name (opens selection if multiple matches)
inskit install python-style

# The command will:
# 1. Search your library for "python-style"
# 2. If found in multiple repos, ask which one
# 3. Install the selected instruction

Installing Instructions

Project-Level Installation

InstructionKit installs all instructions at the project level:

How it works:

• All instructions are installed to your current project
• Stored in tool-specific directories in your project root:
  • Claude Code: .claude/rules/*.md
  • Cursor: .cursor/rules/*.mdc
  • Windsurf: .windsurf/rules/*.md
  • GitHub Copilot: .github/instructions/*.md
• Tracked in <project-root>/.instructionkit/installations.json
• Automatically detects project root (looks for .git, pyproject.toml, package.json, etc.)
• Can be run from any directory within the project

# Install to current project
inskit install python-best-practices --from https://github.com/company/instructions

# All installations are project-level
inskit install python-style

# List shows project installations
inskit list installed

Why project-level?

• Instructions stay with your code (version controlled)
• Team members get the same instructions automatically
• Different projects can have different instructions
• Clean, organized structure per tool
• Portable across machines - uses relative paths in tracking
• No setup needed when cloning - instructions just work

Advanced: Direct Installation (Bypasses Library)

Install Directly from Repository

For one-off installs without downloading to library first:

# Basic install (to current project)
inskit install python-best-practices --from https://github.com/company/instructions

# Install to specific tool
inskit install python-best-practices --from https://github.com/company/instructions --tool cursor

# Handle conflicts by renaming
inskit install python-best-practices --from https://github.com/company/instructions --conflict rename

# Overwrite existing
inskit install python-best-practices --from https://github.com/company/instructions --conflict overwrite

Install from Local Folder

# Relative path
inskit install python-best-practices --from ./my-instructions

# Absolute path
inskit install python-best-practices --from /path/to/instructions

# Great for testing before committing to Git
inskit install my-new-instruction --from ~/Documents/instruction-drafts

Install Bundles

# Install a bundle of related instructions
inskit install python-backend --bundle --from https://github.com/company/instructions

# This might install: python-style, testing-practices, api-design, etc.

Listing & Viewing

List Installed Instructions

# Show all installed instructions in current project
inskit list installed

# Filter by AI tool
inskit list installed --tool cursor

# Filter by source repository
inskit list installed --repo https://github.com/company/instructions

Shows comprehensive information:

• Instruction name and AI tool
• Source repository URL
• Version information with visual badges:
  • 📌 v1.0.0 (tag - pinned version)
  • 🌿 main (branch - tracking latest)
  • 📍 abc123 (commit - locked to specific state)
• Installation date
• Project scope

Example Output:

Installed Instructions
────────────────────────────────────────────────────────────
AI Tool    Instruction       Scope    Source         Version      Installed
Claude     python-style      Project  company/...    📌 v1.0.0   2025-10-26
Cursor     react-patterns    Project  company/...    🌿 main     2025-10-26
Claude     api-guidelines    Project  company/...    📍 abc123   2025-10-26

List Available Instructions (Without Library)

Directly query a repository without downloading it:

# From Git repository
inskit list available --from https://github.com/company/instructions

# From local folder
inskit list available --from ./my-instructions

# Filter by tag
inskit list available --from https://github.com/company/instructions --tag python

# Show only bundles
inskit list available --from https://github.com/company/instructions --bundles-only

Tip: For regular use, it's better to download the repo to your library and browse with the TUI!

Uninstalling Instructions

# Uninstall from all tools in current project
inskit uninstall python-best-practices

# Uninstall from specific tool
inskit uninstall python-best-practices --tool cursor

# Skip confirmation
inskit uninstall python-best-practices --force

Viewing Detected Tools

# See which AI coding tools are installed
inskit tools

📂 Storage & Tracking

InstructionKit stores everything locally:

Library Storage:

• Downloaded repositories: ~/.instructionkit/library/
• Organized by repository namespace (e.g., github.com_company_instructions/)
• Browse offline after downloading

Installation Tracking:

• Tracked in <project-root>/.instructionkit/installations.json
• Contains metadata for all installed instructions in the project
• Created automatically when you install instructions
• Uses relative paths - portable across different machines and users
• Version control friendly - no absolute paths with usernames
• Recommended: Commit to Git so team members get the same setup automatically
• Alternative: Add to .gitignore if instructions should be personal

Why commit installations.json?

• Team members automatically see which instructions are installed
• Works seamlessly when cloned to different machines
• No manual setup needed - everyone gets the same configuration
• Changes to installed instructions are tracked in version control

The list installed command shows all instructions in the current project.

📁 Creating Your Own Instructions

InstructionKit works with simple folder structures - no Git repository required!

Minimal Structure

my-instructions/
├── instructionkit.yaml          # Required: Metadata file
└── instructions/
    └── my-instruction.md        # Your instruction files

instructionkit.yaml Format

name: My Instructions Repository
description: A collection of my coding instructions
version: 1.0.0

instructions:
  - name: my-instruction
    description: What this instruction does
    file: instructions/my-instruction.md
    tags:
      - tag1
      - tag2

Full Example with Bundles

my-instructions/
├── instructionkit.yaml
├── instructions/
│   ├── python-style.md
│   ├── testing.md
│   └── api-design.md
└── README.md                    # Optional

instructionkit.yaml:

name: My Instructions
description: Personal coding standards
version: 1.0.0

instructions:
  - name: python-style
    description: Python coding standards
    file: instructions/python-style.md
    tags: [python, style]

  - name: testing
    description: Testing best practices
    file: instructions/testing.md
    tags: [testing, quality]

  - name: api-design
    description: API design guidelines
    file: instructions/api-design.md
    tags: [api, backend]

bundles:
  - name: python-stack
    description: Complete Python development setup
    instructions:
      - python-style
      - testing
    tags: [python]

💡 Use Cases

For Enterprise Teams

# Step 1: Download company instruction repository
inskit download --from [e-mail]:company/instructions

# Step 2: In your project, browse and install with TUI
cd /path/to/project
inskit install
# - Select company standards or project-specific guidelines
# - Choose which AI tools to install to
# - Install to current project
# - Commit .instructionkit/ and tool directories to Git
# - Team members automatically get the same setup!

For Open Source Projects

# Maintainers: Set up project guidelines
cd your-project
inskit download --from https://github.com/project/instructions
inskit install
# Select "contributing", "code-style", etc.
# Commit to Git so all contributors get them

# Contributors: Clone and get instructions automatically
git clone https://github.com/project/repo
cd repo
# Instructions are already there in .cursor/rules/, .claude/rules/, etc.
# Just start coding with AI assistance!

For Personal Productivity

# Build your personal library
inskit download --from ~/Documents/my-instructions
inskit download --from https://github.com/awesome/prompts

# In each project, pick what you need
cd my-project
inskit install
# Search, filter, and install what's relevant for this project

# Test new instructions locally before publishing
inskit download --from ./instruction-drafts --force
inskit install  # test them out in your current project

For Education

# Instructors: Set up course template
inskit download --from https://github.com/university/course-materials
cd course-template
inskit install
# Select course-wide coding standards
# Commit and share template repo with students

# Students: Assignment-specific guidance
cd assignment-1
inskit install
# Select assignment-specific instructions
# AI assistants now follow assignment requirements

🛠 Requirements

• Python: 3.10 or higher
• Git: Installed and accessible from command line (only for Git repository sources)
• AI Tool: At least one of: Cursor, GitHub Copilot, Windsurf, or Claude Code

📋 Supported AI Tools

All tools use project-level installation with tool-specific directories:

Tool	Project Path	File Extension	Status
Claude Code	.claude/rules/	.md	✅ Fully Supported
Cursor	.cursor/rules/	.mdc	✅ Fully Supported
Windsurf	.windsurf/rules/	.md	✅ Fully Supported
GitHub Copilot	.github/instructions/	.md	✅ Fully Supported

Note: All paths are relative to your project root. InstructionKit automatically detects the project root by looking for .git/, pyproject.toml, package.json, etc.

🤝 Contributing

We welcome community contributions of all sizes. Before you get started:

• 📘 Read the Contributing Guide for setup, coding standards, and PR expectations
• 🤝 Review the Code of Conduct to keep our community respectful and inclusive
• 🐛 Report a bug using the guided template
• 💡 Request a feature and tell us how it helps your workflow

When you're ready to contribute code:

1. Fork the repo or create a feature branch
2. Run invoke quality and invoke test locally
3. Open a pull request using the template and link any related issues
4. Expect an automatic review request thanks to CODEOWNERS—feedback is collaborative and friendly

Curious where to start? Check out good first issues or start a discussion to explore ideas.

📬 Contact

• Author: Troy Larson
• Email: [e-mail]

Development Setup

# Clone repository
git clone https://github.com/troylar/instructionkit.git
cd instructionkit

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install in development mode with all dependencies
pip install -e .[dev]

Common Development Tasks

# List all available tasks
invoke --list

# Run tests
invoke test                    # Run all tests
invoke test --verbose          # Verbose output
invoke test --coverage         # With coverage report
invoke test-unit               # Unit tests only
invoke test-integration        # Integration tests only

# Code quality
invoke quality                 # Run all checks
invoke quality --fix           # Auto-fix issues
invoke lint --fix              # Fix linting issues
invoke format                  # Format code
invoke typecheck               # Type checking

# Build and install
invoke clean                   # Clean build artifacts
invoke build                   # Build package
invoke install                 # Install package

# Utilities
invoke count                   # Count lines of code
invoke version                 # Show version
invoke tree                    # Show project structure

Manual Testing

# Run all tests manually
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/unit/test_models.py

# Run with coverage
pytest --cov=instructionkit --cov-report=html

See DEVELOPMENT.md for complete development guide including:

• Detailed task documentation
• Testing strategies
• Code style guidelines
• Debugging tips
• Release process
• Contributing guidelines

🗺 Roadmap

• Version Control: Pin to tags, track branches, or lock to commits ✅ v0.2.0
• Template Variables: Support for dynamic instruction content with variables
• Instruction Search: Search across all available instructions by content
• Dependency Management: Automatic installation of instruction dependencies
• Remote Catalogs: Centralized instruction catalogs for discovery
• Instruction Validation: Lint and validate instruction content
• Export/Backup: Export installed instructions for backup or migration

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with:

• Typer - CLI framework
• Rich - Terminal formatting
• Textual - Interactive TUI
• PyYAML - YAML parsing

---

Made with ❤️ for the AI coding community

Report Bug • Request Feature