Code Tools Bootstrap

A centralized repository for managing AI coding tool configurations across development teams. Share rules, skills, memories, and workflows consistently across Claude Code, Cursor, Windsurf, Kiro, Antigravity, and other AI-powered development environments.

Why This Exists

AI coding tools are powerful, but their effectiveness depends heavily on configuration:

Rules define coding standards, conventions, and constraints
Skills/Workflows package reusable expertise and multi-step procedures
Memories persist project context across sessions
MCP Servers extend AI capabilities with external tools

Without centralized management, teams end up with:

Inconsistent AI behavior across developers
Duplicated effort configuring each tool
Lost knowledge when configurations aren't shared
Difficulty onboarding new team members

This repository solves these problems by providing a single source of truth for AI tool configurations that can be shared, versioned, and deployed across your team.

Repository Structure

code-tools-bootstrap/
│
├── rules/                       # Shareable rule definitions
│   ├── _base/                   # Foundation rules (always include)
│   │   ├── ai-behavior.md       # AI assistant guidelines
│   │   ├── code-quality.md      # Code quality standards
│   │   ├── configuration.md     # Configuration patterns
│   │   ├── documentation.md     # Documentation standards
│   │   ├── error-handling.md    # Error handling patterns
│   │   ├── git-conventions.md   # Git usage standards
│   │   ├── observability.md     # Logging and monitoring
│   │   ├── security.md          # Security guidelines
│   │   └── testing.md           # Testing standards
│   ├── languages/               # Language-specific rules
│   │   └── python.md            # Python + uv standards
│   ├── frameworks/              # Framework-specific rules
│   ├── domains/                 # Domain-specific rules
│   └── optional/                # Environment-specific rules
│       └── mcp-usage.md         # MCP server guidelines
│
├── skills/                      # Cross-tool skill/workflow definitions
│   ├── _source/                 # Canonical source (author here)
│   │   └── {skill-name}/
│   │       ├── meta.yaml        # Metadata and configuration
│   │       ├── instructions.md  # Core instructions (portable)
│   │       ├── scripts/         # Executable scripts (Claude only)
│   │       └── references/      # Reference docs (Claude only)
│   │
│   └── generated/               # Tool-specific outputs (built)
│       ├── claude-code/         # SKILL.md format
│       ├── windsurf/            # Workflow markdown
│       ├── cursor/              # MDC rule format
│       ├── kiro/                # Steering files
│       └── antigravity/         # Workflow markdown
│
├── guides/                      # User-facing documentation
│   └── ide-setup.md             # IDE configuration tips
│
├── _docs/                       # Internal design documentation
│   ├── tool-comparison.md       # Detailed tool feature comparison
│   ├── existing-solutions.md    # Analysis of other approaches
│   └── skill-format-spec.md     # Canonical format specification
│
├── src/                         # CLI tool source code
│   └── skills_cli/              # Skills CLI package
│
├── README.md                    # This file
├── pyproject.toml               # Python dependencies (uv)
├── LICENSE                      # Repository license
└── AGENTS.md                    # [Internal] Repo maintenance

Note: AGENTS.md, .beads/, and _docs/ are for repository development. rules/, skills/, and guides/ contain distributable content.

Tool Configuration Reference

Each AI tool has its own configuration locations and formats. See _docs/tool-comparison.md for detailed research.

Rules

Tool	Project Location	User Location	Format
Claude Code	`CLAUDE.md`, `.claude/rules/*.md`	`~/.claude/CLAUDE.md`	Markdown
Cursor	`.cursor/rules/*/RULE.md`	Settings > Rules	MDC (frontmatter)
Windsurf	`.windsurf/rules/*.md`	`~/.codeium/windsurf/memories/global_rules.md`	Markdown
Kiro	`.kiro/steering/*.md`	`~/.kiro/steering/*.md`	YAML frontmatter
Antigravity	`.antigravity/rules.md`	`~/.gemini/GEMINI.md`	Markdown

Skills / Workflows

Tool	Project Location	User Location	Invocation	Format
Claude Code	`.claude/skills/{name}/`	`~/.claude/skills/{name}/`	`/name`	YAML frontmatter + scripts
Cursor	`.cursor/rules/{name}/RULE.md`	(settings only)	`@name`	MDC
Windsurf	`.windsurf/workflows/{name}.md`	`~/.codeium/windsurf/global_workflows/`	`/name`	Pure markdown
Kiro	`.kiro/steering/{name}.md`	`~/.kiro/steering/{name}.md`	`#name`	YAML frontmatter
Antigravity	`.agent/workflows/{name}.md`	`/name`	Pure markdown

Feature Support by Tool

Feature	Claude	Windsurf	Cursor	Kiro	Antigravity
Script bundling	✅	❌	❌	❌	❌
Reference files	✅	❌	❌	❌	❌
Auto-detection	✅	❌	✅	❌	❌
Tool restrictions	✅	❌	❌	❌	❌
Glob patterns	❌	❌	✅	✅	❌
Workflow chaining	❌	✅	❌	❌	❌

Quick Start

Installation

cd code-tools-bootstrap
uv sync

This installs the skills CLI tool.

Using Rules

The skills CLI deploys rules with tool-specific formatting:

# List available rules
skills rules list

# Deploy base rules to a project for Windsurf
skills rules deploy windsurf --target ~/myproject --category _base

# Deploy language-specific rules
skills rules deploy windsurf --target . --category languages

# Deploy a specific rule
skills rules deploy cursor --target . --rule python

# Deploy all rules
skills rules deploy kiro --target ~/myproject

# Preview without changes
skills rules deploy windsurf --target . --dry-run

Rules are automatically formatted with tool-specific frontmatter:

Claude Code: Pure markdown (no frontmatter needed)
Windsurf: trigger: always|model_decision|manual
Cursor: alwaysApply: bool, description, globs
Kiro: inclusion: always|fileMatch|manual
Antigravity: Concatenated into single rules.md file

Using Skills/Workflows

The skills CLI handles building and deploying skills to your IDE:

# Build all skills for all tools
skills build

# List available skills
skills list

# Deploy to your current project
skills deploy windsurf

# Deploy to a specific project
skills deploy cursor --target ~/projects/my-app

# Deploy to global user location (where supported)
skills deploy claude-code --global

# Deploy a single skill
skills deploy kiro --skill commit

# Preview without making changes
skills deploy windsurf --dry-run

CLI Commands

Command	Description
`skills build`	Generate tool-specific formats from source skills
`skills deploy <tool>`	Copy generated skills to IDE locations
`skills list`	Show available skills
`skills status`	Show installed skills in current project
`skills rules list`	Show available rules by category
`skills rules deploy <tool>`	Deploy rules with tool-specific formatting

Use skills <command> --help for detailed options.

Creating Skills

Canonical Format

Skills are authored once in skills/_source/ and generated for all tools:

skills/_source/my-skill/
├── meta.yaml           # Required: Metadata
├── instructions.md     # Required: Instructions
├── scripts/            # Optional: Claude Code only
└── references/         # Optional: Claude Code only

meta.yaml

name: my-skill
description: |
  What this skill does and when to use it.
  Include trigger phrases for auto-detection.

type: skill  # skill | workflow | rule

triggers:    # Optional: Auto-detection phrases
  - "trigger phrase"

allowed_tools:  # Optional: Claude Code only
  - Bash
  - Read

globs: []       # Optional: File patterns

always_apply: false

overrides:      # Optional: Tool-specific settings
  cursor:
    apply_mode: manual  # always | intelligent | manual
  kiro:
    inclusion: manual   # always | fileMatch | manual

instructions.md

Pure markdown with step-by-step instructions. This content is portable across all tools.

See _docs/skill-format-spec.md for the complete specification and _docs/authoring-guide.md for step-by-step authoring instructions.

Architecture Decisions

Why Build Instead of Using vibe-rules?

We evaluated vibe-rules and other existing solutions. Key findings:

Aspect	vibe-rules	Our Approach
Rules	✅ Handles well	✅ Static markdown
Skills/Workflows	❌ Not supported	✅ Build generator
Script bundling	❌ N/A	✅ Claude Code support
Metadata preservation	⚠️ Lossy	✅ Lossless with warnings
Maintenance	⚠️ Stale (5mo)	✅ We control

See _docs/existing-solutions.md for detailed analysis.

Design Principles

Single source of truth: Author once, deploy everywhere with tool-specific formatting
Rules and skills: Rules get tool-specific frontmatter on deploy. Skills are pre-built.
Lossless where possible: Preserve metadata, warn when features unavailable
Tool-agnostic core: Instructions are portable, metadata is mapped per tool

Configuration Patterns

Layered Rules Architecture

┌─────────────────────────────────────────┐
│          Project-Specific Rules          │  ← Highest priority
│     (checked into your project repo)     │
├─────────────────────────────────────────┤
│          Team/Org Standards              │  ← From this repo
│    (symlinked or copied from here)       │
├─────────────────────────────────────────┤
│          User Preferences                │  ← Personal settings
│        (~/.claude/CLAUDE.md, etc.)       │
├─────────────────────────────────────────┤
│          Tool Defaults                   │  ← Lowest priority
└─────────────────────────────────────────┘

Character Limits

Tool	Limit	Notes
Claude Code	~5000 words	Recommended for skills
Windsurf	12,000 chars	Hard limit per file
Cursor	Token-based	Context-dependent
Kiro	Context-based	No hard limit

Contributing

Adding Rules

Choose category: _base/, languages/, frameworks/, or domains/
Create focused markdown file
Test with at least one tool

Adding Skills

Create skills/_source/{name}/ directory
Add meta.yaml and instructions.md
Run skills build --skill {name}
Test with skills deploy <tool> --skill {name} --dry-run

Adding Tool Support

Research tool's format (document in _docs/)
Add generator in src/skills_cli/core/generators.py
Add tool config in src/skills_cli/core/config.py
Update feature matrix tables

Development

This repository uses uv for Python dependencies.

# Setup
uv sync

# Skills CLI
skills build                    # Build all skills
skills list                     # List source skills
skills list --tool windsurf     # List generated skills for a tool
skills deploy windsurf          # Deploy to current project
skills status                   # Show installed skills

# Rules CLI
skills rules list               # List available rules
skills rules list -c _base      # List rules in a category
skills rules deploy windsurf --target .  # Deploy rules to project

Deploy Command Options

The deploy command supports several safety features:

Flag	Description
`--target PATH`	Deploy to a specific project directory
`--global`	Deploy to user-level location (Claude Code, Kiro, Antigravity)
`--skill NAME`	Deploy only a specific skill
`--dry-run`	Preview changes without writing files
`--force`	Overwrite existing files without prompting
`--backup`	Backup existing files before overwriting

When conflicts are detected, you'll be prompted to:

Overwrite: Replace the existing file
Skip: Keep the existing file
Diff: View differences between files
All: Overwrite all remaining conflicts
Quit: Cancel the deployment

Rules Deploy Command Options

The rules deploy command formats rules for your target IDE:

Flag	Description
`--target PATH`	Target project directory (required)
`--category CAT`	Deploy only rules from specific categories (repeatable)
`--rule NAME`	Deploy a specific rule only
`--dry-run`	Preview changes without writing files
`--force`	Overwrite existing files without prompting
`--backup`	Backup existing files before overwriting

Default modes by category:

_base rules → always (applied to every interaction)
languages rules → model_decision (AI decides based on context)
optional rules → manual (explicitly invoked)

Resources

Official Documentation

Community Resources

awesome-cursorrules - Curated Cursor rules
anthropics/skills - Official Claude skills
awesome-claude-skills - Community skills
vibe-rules - Cross-tool rules CLI

Internal Documentation

Authoring Guide - How to create rules, skills, and workflows
Tool Comparison - Detailed feature research
Existing Solutions - Analysis of other approaches
Skill Format Spec - Canonical format specification

License

See LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
_docs		_docs
guides		guides
rules		rules
skills		skills
src/skills_cli		src/skills_cli
.gitignore		.gitignore
.python-version		.python-version
LICENSE		LICENSE
README.md		README.md
main.py		main.py
pyproject.toml		pyproject.toml
uv.lock		uv.lock

License

osocode/code-tools-bootstrap

Folders and files

Latest commit

History

Repository files navigation

Code Tools Bootstrap

Why This Exists

Repository Structure

Tool Configuration Reference

Rules

Skills / Workflows

Feature Support by Tool

Quick Start

Installation

Using Rules

Using Skills/Workflows

CLI Commands

Creating Skills

Canonical Format

meta.yaml

instructions.md

Architecture Decisions

Why Build Instead of Using vibe-rules?

Design Principles

Configuration Patterns

Layered Rules Architecture

Character Limits

Contributing

Adding Rules

Adding Skills

Adding Tool Support

Development

Deploy Command Options

Rules Deploy Command Options

Resources

Official Documentation

Community Resources

Internal Documentation

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages