Aircana

Aircana is a CLI for generating Claude Code plugins with specialized knowledge bases. Each knowledge base provides curated documentation synced from Confluence (label-based) or web URLs, yielding more relevant, predictable, and project-specific results than general-purpose AI assistance.

Knowledge bases automatically refresh once daily on session start, keeping content up-to-date without manual intervention. Knowledge sources are tracked in version-controlled manifests, so team members can independently refresh content while keeping actual documentation out of git.

Install the gem:

gem install aircana

Verify installation and dependency setup:

aircana doctor

Create a new Claude Code plugin:

# Create a new plugin directory
mkdir my-plugin
cd my-plugin

# Initialize the plugin
aircana init

# Or initialize with a custom name
aircana init --plugin-name my-custom-plugin

This creates a plugin structure with:

• .claude-plugin/plugin.json - Plugin manifest
• agents/ - Knowledge base definitions
• commands/ - Slash commands
• hooks/ - Hook configurations (hooks.json)
• scripts/ - Hook scripts and utilities

1. Create a specialized knowledge base:

aircana kb create

2. Add knowledge sources:

# From Confluence (requires configuration)
aircana kb refresh my-kb

# From web URLs
aircana kb add-url my-kb https://docs.example.com

3. Manage your plugin:

# View plugin information
aircana plugin info

# Update plugin metadata
aircana plugin update

# Bump version
aircana plugin version bump patch

# Validate plugin structure
aircana plugin validate

4. Install plugin in Claude Code:

• Copy your plugin directory to a location Claude Code can access
• Use Claude Code's plugin installation commands to enable your plugin

• Follow the Getting Started tutorial to create knowledge bases—Aircana's key differentiator

• Configure the Confluence integration and create domain-specific knowledge bases

• Use the /ask-expert command to consult multiple specialized experts

• Use the /plan command to create strategic implementation plans with expert consultation

• Explore other tools by running aircana --help

This tutorial walks through creating a complete Claude Code plugin with knowledge bases backed by Confluence, then publishing it to a marketplace for team distribution.

1. Install Aircana:

gem install aircana
aircana doctor  # Verify dependencies

2. Configure Confluence (optional but recommended):

Add to your shell profile (.bashrc, .zshrc, etc.):

export CONFLUENCE_BASE_URL="https://your-company.atlassian.net"
export CONFLUENCE_USERNAME="your.email@company.com"
export CONFLUENCE_API_TOKEN="your-generated-token"

To generate a Confluence API token:

1. Go to your Confluence instance
2. Click profile picture → Account Settings → Security
3. Select Create and manage API tokens → Create API token
4. Copy the token and add to your environment variables

Reload your shell: source ~/.zshrc (or your shell config file)

# Create a new directory for your plugin
mkdir my-team-plugin
cd my-team-plugin

# Initialize the plugin
aircana init --plugin-name my-team

# Verify the structure was created
ls -la

This creates:

• .claude-plugin/plugin.json - Plugin manifest with metadata
• agents/ - Directory for knowledge base definitions
• commands/ - Custom slash commands
• hooks/hooks.json - Hook configurations
• scripts/ - Hook scripts and utilities

aircana kb create

You'll be prompted for:

• Knowledge base name: e.g., "backend-api" (use kebab-case)
• Description: e.g., "Expert in backend API development and best practices"
• Model: Choose sonnet (smarter), haiku (faster), or inherit (uses default)
• Color: Pick an interface color for visual identification

The knowledge base file is created at agents/backend-api.md with:

• Configuration (name, description, model)
• Knowledge base path reference
• Custom instructions

In Confluence, label pages you want the knowledge base to access:

1. Open a relevant Confluence page (e.g., "API Design Guidelines")
2. Click ... → Edit labels
3. Add label: backend-api (must match your knowledge base name)
4. Click Save

Repeat for all documentation pages relevant to this knowledge base. Aircana will discover pages by label during the refresh process.

Tip: Use a consistent labeling strategy. For example, label all backend documentation with backend-api, all frontend docs with frontend-expert, etc.

aircana kb refresh backend-api

This will:

1. Search Confluence for pages labeled backend-api
2. Download page content via Confluence REST API
3. Convert HTML to Markdown using ReverseMarkdown
4. Store content in the knowledge base directory
5. Update agents/backend-api/manifest.json with source metadata

Output: Knowledge files are created in ~/.claude/skills/backend-api/

Note: The actual knowledge content is stored globally (not in your plugin directory) to avoid version control bloat and potential sensitive information leaks. Only the manifest (source tracking) is version controlled.

You can also add public web documentation to your knowledge base:

aircana kb add-url backend-api https://docs.example.com/api-guide
aircana kb add-url backend-api https://restfulapi.net/rest-architectural-constraints/

This downloads the web page, extracts main content (removes nav/ads/scripts), converts to Markdown, and adds it to the knowledge base.

Refresh to sync web URLs:

aircana kb refresh backend-api

Your knowledge base is now ready! Claude Code will automatically use it when appropriate based on the description. You can also explicitly invoke it:

Ask backend-api to review this API endpoint design
Ask backend-api how to implement authentication

Claude has access to all Confluence pages and web URLs you've synced to the knowledge base.

For detailed instructions on distributing your plugin via Git repositories or Claude Code plugin marketplaces, see the official Claude Code Plugin Marketplaces documentation.

Quick summary:

• Share via Git repository: Team members clone the plugin, configure Confluence credentials, and run aircana kb refresh-all
• Publish to a marketplace: Create a marketplace.json file in a separate repository, add your plugin metadata, and team members install via the marketplace UI

As your Confluence documentation evolves:

# Refresh a specific knowledge base
aircana kb refresh backend-api

# Or refresh all knowledge bases at once
aircana kb refresh-all

Knowledge sources are tracked in agents/<kb-name>/manifest.json, so team members can independently refresh without manual coordination.

Aircana creates Claude Code plugins - portable, distributable packages that extend Claude Code with custom functionality. Each plugin includes:

• Manifest: Metadata describing the plugin (name, version, author, etc.)
• Knowledge Bases: Specialized domain expertise from curated documentation
• Commands: Custom slash commands
• Hooks: Event-driven automation

Plugins can be shared with teams or published to plugin marketplaces for broader distribution.

The .claude-plugin/plugin.json file defines plugin metadata:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "[email protected]",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"]
}

Optional path overrides (for non-standard layouts):

{
  "commands": "./custom/commands/",
  "agents": "./custom/skills/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json"
}

Aircana creates human-curated knowledge bases that provide Claude Code with domain-specific expertise. Each knowledge base:

• Provides focused documentation: Access to curated domain-specific content
• Stays up-to-date: Refreshable sources from Confluence and web URLs
• Improves responses: More relevant, predictable results with less back-and-forth
• Custom configuration: Model, color, and behavior settings

Knowledge bases support multiple source types and can be refreshed to pull the latest content. Aircana-generated plugins automatically refresh all knowledge bases once daily on session start via the SessionStart hook, keeping content up-to-date without manual intervention.

To add a Confluence page to a knowledge base, label the desired page in Confluence, then run aircana kb refresh <KB-NAME>.

Aircana will also pull any Confluence pages labeled with a matching knowledge base name during initial creation (aircana kb create).

See the Confluence setup guide or run aircana doctor for instructions on setting up Confluence integration.

In addition to Confluence sources, Aircana allows adding arbitrary public websites to a knowledge base.

Websites are also refreshed when aircana kb refresh <KB-NAME> is used.

Knowledge bases are stored within the plugin's agents directory. For example:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── agents/
│   ├── backend-expert.md
│   └── backend-expert/
│       ├── knowledge/          # (optional, for local KBs)
│       │   ├── API-Design.md
│       │   └── Authentication.md
│       └── manifest.json
├── commands/
│   └── ask-expert.md
├── hooks/
│   └── hooks.json
└── scripts/
    ├── pre_tool_use.sh
    └── session_start.sh

Knowledge base files and manifests are co-located in the plugin's agents/ directory.

Version Control Considerations:

In many cases, adding the actual knowledge base to version control is undesirable because:

• Knowledge bases may contain numerous files, bloating repository size
• Content may include sensitive information not suitable for public repos
• Knowledge refreshes would create frequent, large commits

Aircana manages a per-knowledge-base manifest.json file to track knowledge sources without committing the actual content. Team members can refresh knowledge bases using aircana kb refresh.

For remote knowledge bases, actual content is stored in ~/.claude/skills/<kb-name>/. For local knowledge bases, content is version-controlled in agents/<kb-name>/knowledge/ and synced to the runtime location.

Aircana uses ERB templates to generate plugin components consistently:

• Knowledge Bases (Skills): Domain expertise with curated documentation
• Commands: Slash commands with parameter handling
• Hooks: Event handlers for automation

These templates promote best practices and help create effective plugin components without extensive trial and error.

Aircana uses the "Notification" Claude Code hook to send messages to SQS.

At Instructure this means you can easily configure Claude Code to send you slack messages when it needs your attention via Aircana

(Instructions coming soon, send a message if you want help with this)

Design knowledge bases as narrow domain experts, not generalists. More granular knowledge bases with focused content generally perform better than broad, general-purpose ones.

Examples:

✅ Good - Narrow domains:

• database-schema-expert - Database design, migrations, indexing strategies
• api-authentication-expert - OAuth, JWT, session management
• frontend-styling-expert - CSS, design systems, responsive layouts

❌ Avoid - Too broad:

• backend-engineer - Too many domains, knowledge becomes unfocused
• full-stack-developer - Overlapping responsibilities with unclear boundaries

Why narrow domains work better:

• Focused content: Each knowledge base contains highly relevant documentation for a specific domain
• Better results: More accurate, detailed responses within the area of expertise
• Less context pollution: Smaller, focused content prevents information overload
• Clear boundaries: Non-overlapping domains reduce confusion

Tips:

• Break large domains into smaller, specialized areas
• Each knowledge base should have a clear, distinct purpose
• Knowledge bases should contain 5-20 highly relevant documents, not 100+ loosely related ones
• Use descriptions to clearly define boundaries and expertise areas

Aircana provides two powerful slash commands that leverage your expert knowledge bases:

Consults multiple specialized knowledge bases to answer questions by:

• Using a coordinator to identify relevant expert agents
• Running expert consultations in parallel for efficiency
• Synthesizing responses into a comprehensive answer
• Citing which experts contributed specific insights
• Providing follow-up guidance when needed

Example usage:

/ask-expert How should I implement caching for our API?
/ask-expert What are the best practices for database migrations?

The command automatically selects the most relevant experts based on your question and the knowledge bases available in your plugin.

Creates strategic implementation plans by consulting domain experts. This command:

• Verifies you're in Claude Code planning mode
• Uses a coordinator to identify relevant expert agents
• Consults experts in parallel for their domain-specific insights
• Synthesizes expert input into a unified strategic plan
• Presents the plan as numbered implementation steps
• Focuses on high-level guidance (not exhaustive code implementations)

Example usage:

# First, put Claude Code into planning mode, then:
/plan Add authentication to the user API

# Or provide task as argument:
/plan "Refactor the database layer for better performance"

The plan focuses on strategic decisions, architecture considerations, and approach—leveraging the collective expertise of your knowledge bases to create well-informed implementation guidance.

To use agent knowledge sync features, you'll need to configure Confluence integration:

1. Go to your Confluence instance
2. Click your profile picture → Account Settings
3. Select Security → Create and manage API tokens
4. Click Create API token
5. Give it a descriptive name (e.g., "Aircana Integration")
6. Copy the generated token

Add these to your shell profile (.bashrc, .zshrc, etc.):

export CONFLUENCE_BASE_URL="https://your-company.atlassian.net"
export CONFLUENCE_USERNAME="your.email@company.com"
export CONFLUENCE_API_TOKEN="your-generated-token"

To enable SQS notifications for Claude Code events (useful for Slack/Teams integration):

Make sure you have the AWS CLI installed:

# macOS
brew install awscli

# Ubuntu/Debian
apt install awscli

# Configure AWS credentials
aws configure

Add these to your shell profile (.bashrc, .zshrc, etc.):

export AIRCANA_SQS_QUEUE_URL="https://sqs.us-east-1.amazonaws.com/your-account/your-queue"
export AIRCANA_SQS_MESSAGE_TEMPLATE='{"channel":"changelog","username":"Aircana","text":"{{message}}"}'
export AWS_REGION="us-east-1"

The message template supports {{message}} placeholder which gets replaced with the Claude Code notification text.

The notification_sqs hook is automatically generated when you initialize your plugin:

aircana init

The hook will be automatically enabled and ready to use.

aircana doctor

This will check if Confluence and other integrations are properly configured.

aircana init [DIRECTORY]           # Initialize a new plugin (defaults to current directory)
aircana init --plugin-name NAME    # Initialize with custom plugin name
aircana plugin info                # Display plugin information
aircana plugin update              # Update plugin metadata
aircana plugin version             # Show current version
aircana plugin version bump [TYPE] # Bump version (major, minor, or patch)
aircana plugin version set         # Set specific version
aircana plugin validate            # Validate plugin structure

aircana kb create                  # Create new knowledge base interactively
aircana kb refresh [KB-NAME]       # Sync knowledge base from Confluence and web sources
aircana kb refresh-all             # Refresh all knowledge bases
aircana kb add-url [KB-NAME] [URL] # Add a web URL to a knowledge base
aircana kb list                    # List all configured knowledge bases

aircana generate                   # Generate plugin components from templates
aircana doctor                     # Check system health and dependencies
aircana doctor --verbose           # Show detailed dependency information
aircana dump-context [KB-NAME]     # View current context for knowledge base

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Run commands in development with bundle exec exe/aircana <command>

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/westonkd/aircana.

The gem is available as open source under the terms of the MIT License.