aircana 3.2.1 → 4.0.0.rc1

data/CLAUDE.md

@@ -12,8 +12,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ### Testing and Quality
 - `rake spec` or `bundle exec rspec` - Run all tests
-- `bundle exec rspec spec/aircana/cli/commands/agents_spec.rb` - Run specific test file
-- `bundle exec rspec spec/aircana/cli/commands/agents_spec.rb:15` - Run test at specific line
+- `bundle exec rspec spec/aircana/cli/commands/kb_spec.rb` - Run specific test file
+- `bundle exec rspec spec/aircana/cli/commands/kb_spec.rb:15` - Run test at specific line
 - `bundle exec rspec --format documentation` - Run tests with detailed output
 - `bundle exec rubocop` - Run linter
 - `bundle exec rubocop -a` - Run linter with auto-fix
@@ -36,12 +36,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - `aircana plugin version set` - Set specific version
 - `aircana plugin validate` - Validate plugin structure and manifests
 
-**Agent Management:**
-- `aircana agents create` - Create a new agent interactively
-- `aircana agents list` - List all configured agents
-- `aircana agents refresh <agent>` - Refresh agent knowledge from Confluence and web sources
-- `aircana agents refresh-all` - Refresh knowledge for all configured agents
-- `aircana agents add-url <agent> <url>` - Add a web URL to an agent's knowledge base
+**Knowledge Base Management:**
+- `aircana kb create` - Create a new knowledge base interactively
+- `aircana kb list` - List all configured knowledge bases
+- `aircana kb refresh <kb-name>` - Refresh knowledge base from Confluence and web sources
+- `aircana kb refresh-all` - Refresh knowledge for all configured knowledge bases
+- `aircana kb add-url <kb-name> <url>` - Add a web URL to a knowledge base
 
 **Hook Management:**
 - `aircana hooks list` - List all available hooks
@@ -54,25 +54,25 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - `aircana doctor` - Check system health and dependencies
 - `aircana doctor --verbose` - Show detailed dependency information
 - `aircana generate` - Generate plugin components from templates
-- `aircana dump-context <agent_name>` - Dump context for specified agent
+- `aircana dump-context <kb-name>` - Dump context for specified knowledge base
 
 ## Architecture
 
 ### Core Structure
-Aircana is a Ruby gem that creates and manages Claude Code plugins. The main components:
+Aircana is a Ruby gem that creates and manages Claude Code plugins with knowledge bases. The main components:
 
 - **CLI Layer** (`lib/aircana/cli/`): Thor-based command line interface with subcommands
   - `app.rb`: Main Thor application defining all commands and subcommands
-  - `subcommand.rb`: Base class for subcommands (agents, hooks, plugin)
+  - `subcommand.rb`: Base class for subcommands (kb, hooks, plugin)
   - `shell_command.rb`: Shell command execution utilities
   - `commands/`: Individual command implementations
     - `init.rb`: Plugin initialization
     - `plugin.rb`: Plugin metadata management
-    - `agents.rb`: Agent CRUD operations
+    - `kb.rb`: Knowledge base CRUD operations
     - `hooks.rb`: Hook management
     - `doctor.rb`: System health checks with modular check system
     - `generate.rb`: Generates plugin components from templates
-    - `dump_context.rb`: Outputs agent knowledge for debugging
+    - `dump_context.rb`: Outputs knowledge base content for debugging
 
 - **Plugin Management**:
   - `plugin_manifest.rb`: Manages `.claude-plugin/plugin.json` with validation
@@ -88,25 +88,26 @@ Aircana is a Ruby gem that creates and manages Claude Code plugins. The main com
     - HTML to Markdown conversion (ReverseMarkdown)
     - Main content extraction (removes nav, ads, scripts)
     - Claude API integration for generating meaningful page titles
-  - `manifest.rb`: Per-agent manifest system tracking:
+  - `manifest.rb`: Per-knowledge-base manifest system tracking:
     - Knowledge sources (Confluence, web)
     - Source metadata (page IDs, URLs, timestamps)
+    - KB type (local or remote)
     - Manifest format version (1.0)
   - `local.rb`: File system operations for storing knowledge
 
 - **Generators** (`lib/aircana/generators/`): ERB-based template generation
   - `base_generator.rb`: Base class with ERB rendering and file writing
-  - `agents_generator.rb`: Agent file generation with default agent support
-    - Default agents: planner, jira, sub-agent-coordinator, executor, reviewer, apply_feedback
+  - `skills_generator.rb`: Knowledge base file generation (Markdown format)
   - Command generators: plan, execute, record, review, apply_feedback, ask_expert
   - `hooks_generator.rb`: Hook script generation
   - Templates location: `lib/aircana/templates/`
 
 - **Configuration** (`lib/aircana/configuration.rb`): Path resolution system
   - Plugin root detection via environment variables (AIRCANA_PLUGIN_ROOT, CLAUDE_PLUGIN_ROOT)
-  - Plugin-aware paths (commands, agents, hooks directories)
+  - Plugin-aware paths (commands, skills, hooks directories)
   - Global vs plugin-local knowledge storage
   - Automatic plugin name extraction from plugin.json
+  - Resolves to `~/.claude/skills/<kb-name>/` for knowledge storage
 
 - **LLM Integration**:
   - `llm/claude_client.rb`: Claude API client for web title generation
@@ -118,18 +119,19 @@ Aircana is a Ruby gem that creates and manages Claude Code plugins. The main com
   - `fzf_helper.rb`: Interactive fuzzy selection
 
 ### Key Concepts
-- **Plugins**: Distributable Claude Code extensions with manifests, agents, commands, and hooks
+- **Plugins**: Distributable Claude Code extensions with manifests, skills/knowledge bases, commands, and hooks
 - **Plugin Manifests**: JSON files defining plugin metadata (`.claude-plugin/plugin.json`)
-- **Agents**: Domain-specific experts with dedicated knowledge bases and context windows
-- **Knowledge Bases**: Curated documentation from Confluence and web sources
+- **Knowledge Bases (Skills)**: Curated documentation from Confluence and web sources that provide domain expertise
+- **Manifests**: Per-knowledge-base JSON tracking sources, metadata, and KB type (local/remote)
 - **Hooks**: Event-driven automation through `hooks/hooks.json`
 - **Commands**: Custom slash commands for workflow automation
 
 ### File Organization
 - **Plugin Structure**:
   - `.claude-plugin/plugin.json` - Plugin manifest with metadata and versioning
-  - `agents/` - Agent markdown files (agent definitions)
-  - `agents/<agent_name>/manifest.json` - Tracks knowledge sources per agent
+  - `agents/` - Knowledge base markdown files (skill definitions)
+  - `agents/<kb-name>/manifest.json` - Tracks knowledge sources per KB
+  - `agents/<kb-name>/knowledge/` - Local knowledge base content (if KB type is "local")
   - `commands/` - Slash command markdown files
   - `hooks/` - hooks.json manifest defining hook configurations
   - `scripts/` - Hook scripts and utility scripts
@@ -137,24 +139,31 @@ Aircana is a Ruby gem that creates and manages Claude Code plugins. The main com
 - **Global Configuration**:
   - `~/.aircana/` - Global Aircana configuration directory
   - `~/.aircana/aircana.out/` - Generated templates output directory
+  - `~/.claude/skills/` - Runtime knowledge base storage
 
 - **Knowledge Storage Architecture**:
-  - **Global (not version controlled)**: `~/.claude/agents/<plugin-name>-<agent-name>/knowledge/`
+  - **Remote KBs (not version controlled)**: `~/.claude/skills/<kb-name>/`
     - Actual knowledge base content (Markdown files)
-    - Refreshed via `aircana agents refresh`
+    - Refreshed via `aircana kb refresh`
     - Excluded from version control to avoid bloat/sensitivity
-  - **Plugin-local (version controlled)**: `agents/<agent_name>/manifest.json`
+  - **Local KBs (version controlled)**: `agents/<kb-name>/knowledge/`
+    - Version-controlled knowledge content in plugin repository
+    - Auto-synced to `~/.claude/skills/<kb-name>/` via SessionStart hook
+    - Teams can collaborate on knowledge directly in Git
+  - **Plugin-local manifests (version controlled)**: `agents/<kb-name>/manifest.json`
     - Tracks knowledge sources (Confluence labels, web URLs)
+    - Specifies KB type ("local" or "remote")
     - Team members can refresh knowledge independently
     - Format:
       ```json
       {
         "version": "1.0",
-        "agent": "agent-name",
+        "kb_name": "my-kb",
+        "kb_type": "remote",
         "sources": [
           {
             "type": "confluence",
-            "label": "agent-name",
+            "label": "my-kb",
             "pages": [{"id": "123456"}]
           },
           {
@@ -201,7 +210,7 @@ This pattern keeps each module focused on a single responsibility while composin
 
 **ERB Template Generation**:
 All plugin components are generated from ERB templates in `lib/aircana/templates/`:
-- `agents/` - Agent templates (base_agent.erb, defaults/)
+- `skills/` - Knowledge base templates (skill.md.erb)
 - `commands/` - Slash command templates
 - `hooks/` - Hook script templates
 
@@ -223,10 +232,11 @@ end
 ```
 
 **Manifest-Based Knowledge Tracking**:
-Each agent has a `manifest.json` that tracks knowledge sources without storing content:
-- Version controlled: manifest.json (sources metadata)
-- Not version controlled: actual knowledge content in ~/.claude/agents/
-- Team members run `aircana agents refresh` to sync knowledge locally
+Each knowledge base has a `manifest.json` that tracks knowledge sources:
+- Version controlled: `agents/<kb-name>/manifest.json` (sources metadata, KB type)
+- Remote KBs: Content stored in `~/.claude/skills/<kb-name>/` (not version controlled)
+- Local KBs: Content stored in `agents/<kb-name>/knowledge/` (version controlled), synced to `~/.claude/skills/`
+- Team members run `aircana kb refresh` to sync remote knowledge locally
 
 **Plugin-Aware Path Resolution**:
 Configuration class detects plugin mode and resolves paths accordingly:
@@ -242,12 +252,12 @@ Configuration class detects plugin mode and resolves paths accordingly:
 - Run specific test: `bundle exec rspec spec/path/to/file_spec.rb:15`
 
 ### Knowledge Sources
-Agents can sync knowledge from multiple sources:
+Knowledge bases can sync content from multiple sources:
 
 **Confluence Integration:**
 - Environment variables: `CONFLUENCE_BASE_URL`, `CONFLUENCE_USERNAME`, `CONFLUENCE_API_TOKEN`
 - Pages fetched via Confluence REST API v2 using HTTParty
-- Label-based discovery: searches for pages labeled with agent name under "global" prefix
+- Label-based discovery: searches for pages labeled with KB name under "global" prefix
 - Pagination support for large result sets
 - HTML content converted to Markdown via ReverseMarkdown
 - Page metadata (ID) tracked in manifest for refresh operations
@@ -265,9 +275,10 @@ Agents can sync knowledge from multiple sources:
 - URL metadata tracked in manifest
 
 **Unified Management:**
-- Both source types tracked in manifest.json per agent
+- Both source types tracked in manifest.json per knowledge base
 - Manifest schema version 1.0
-- `aircana agents refresh <agent>` refreshes all sources (Confluence + web)
-- `aircana agents refresh-all` refreshes all configured agents
-- Content stored as Markdown in `~/.claude/agents/<plugin-name>-<agent-name>/knowledge/`
-- Knowledge paths referenced in agent files use tilde notation: `~/.claude/agents/.../knowledge/`
+- `aircana kb refresh <kb-name>` refreshes all sources (Confluence + web) for remote KBs
+- `aircana kb refresh-all` refreshes all configured remote knowledge bases
+- Remote KB content stored as Markdown in `~/.claude/skills/<kb-name>/`
+- Local KB content stored in `agents/<kb-name>/knowledge/`, synced to `~/.claude/skills/<kb-name>/`
+- Knowledge paths referenced in skill files use tilde notation: `~/.claude/skills/.../`

data/README.md

@@ -5,9 +5,9 @@
 
 ## Intro
 
-Aircana is a CLI for generating [Claude Code plugins](https://docs.claude.com/en/docs/claude-code/plugins) with per-agent knowledge bases. Each agent gets a curated knowledge base synced from Confluence (label-based) or web URLs, yielding more relevant, predictable, and project-specific results than general-purpose agents.
+Aircana is a CLI for generating [Claude Code plugins](https://docs.claude.com/en/docs/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 agents 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.
+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.
 
 ## How can I try it?
 
@@ -43,25 +43,25 @@ aircana init --plugin-name my-custom-plugin
 
 This creates a plugin structure with:
 - `.claude-plugin/plugin.json` - Plugin manifest
-- `agents/` - Specialized agents
+- `agents/` - Knowledge base definitions
 - `commands/` - Slash commands
 - `hooks/` - Hook configurations (hooks.json)
 - `scripts/` - Hook scripts and utilities
 
 ### Next Steps
 
-**1. Create a specialized agent:**
+**1. Create a specialized knowledge base:**
 ```bash
-aircana agents create
+aircana kb create
 ```
 
 **2. Add knowledge sources:**
 ```bash
 # From Confluence (requires configuration)
-aircana agents refresh my-agent
+aircana kb refresh my-kb
 
 # From web URLs
-aircana agents add-url my-agent https://docs.example.com
+aircana kb add-url my-kb https://docs.example.com
 ```
 
 **3. Manage your plugin:**
@@ -85,11 +85,11 @@ aircana plugin validate
 
 ### Things to try
 
-- Follow the [Getting Started](#getting-started) tutorial to create agents with knowledge bases—Aircana's key differentiator
+- Follow the [Getting Started](#getting-started) tutorial to create knowledge bases—Aircana's key differentiator
 
-- Configure the Confluence integration and create domain-specific agents
+- Configure the Confluence integration and create domain-specific knowledge bases
 
-- Use the `/ask-expert` command to consult multiple specialized agents
+- Use the `/ask-expert` command to consult multiple specialized experts
 
 - Set up the development workflow with plan, execute, review, and apply-feedback commands
 
@@ -97,7 +97,7 @@ aircana plugin validate
 
 ## Getting Started
 
-This tutorial walks through creating a complete Claude Code plugin with agents backed by Confluence knowledge bases, then publishing it to a marketplace for team distribution.
+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.
 
 ### Prerequisites
 
@@ -140,45 +140,45 @@ ls -la
 
 This creates:
 - `.claude-plugin/plugin.json` - Plugin manifest with metadata
-- `agents/` - Directory for specialized agents
+- `agents/` - Directory for knowledge base definitions
 - `commands/` - Custom slash commands
 - `hooks/hooks.json` - Hook configurations
 - `scripts/` - Hook scripts and utilities
 
-### Step 2: Create an Agent Backed by Confluence
+### Step 2: Create a Knowledge Base Backed by Confluence
 
 ```bash
-aircana agents create
+aircana kb create
 ```
 
 You'll be prompted for:
-- **Agent name**: e.g., "backend-api" (use kebab-case)
+- **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 agent file is created at `agents/backend-api.md` with:
-- Agent configuration (name, description, model)
+The knowledge base file is created at `agents/backend-api.md` with:
+- Configuration (name, description, model)
 - Knowledge base path reference
 - Custom instructions
 
 ### Step 3: Tag Confluence Pages
 
-In Confluence, label pages you want the agent to access:
+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 agent name)
+3. Add label: `backend-api` (must match your knowledge base name)
 4. Click **Save**
 
-Repeat for all documentation pages relevant to this agent. Aircana will discover pages by label during the refresh process.
+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.
 
-### Step 4: Refresh Agent Knowledge
+### Step 4: Refresh Knowledge Base
 
 ```bash
-aircana agents refresh backend-api
+aircana kb refresh backend-api
 ```
 
 This will:
@@ -188,43 +188,43 @@ This will:
 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/agents/my-team-backend-api/knowledge/`
+**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.
 
 ### Step 5: Add Web URLs (Optional)
 
-You can also add public web documentation to your agent's knowledge base:
+You can also add public web documentation to your knowledge base:
 
 ```bash
-aircana agents add-url backend-api https://docs.example.com/api-guide
-aircana agents add-url backend-api https://restfulapi.net/rest-architectural-constraints/
+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:
 ```bash
-aircana agents refresh backend-api
+aircana kb refresh backend-api
 ```
 
-### Step 6: Use Your Agent
+### Step 6: Use Your Knowledge Base
 
-Your agent is now ready! Claude Code will automatically consult your agent when appropriate based on the agent's description. You can also explicitly request the agent:
+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
 ```
 
-The agent has access to all Confluence pages and web URLs you've synced to its knowledge base.
+Claude has access to all Confluence pages and web URLs you've synced to the knowledge base.
 
 ### Step 7: Share Your Plugin with Your Team
 
 For detailed instructions on distributing your plugin via Git repositories or Claude Code plugin marketplaces, see the official [Claude Code Plugin Marketplaces documentation](https://docs.claude.com/en/docs/claude-code/plugin-marketplaces).
 
 **Quick summary:**
-- Share via Git repository: Team members clone the plugin, configure Confluence credentials, and run `aircana agents refresh-all`
+- 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
 
 ### Next: Keep Knowledge Up-to-Date
@@ -232,14 +232,14 @@ For detailed instructions on distributing your plugin via Git repositories or Cl
 As your Confluence documentation evolves:
 
 ```bash
-# Refresh a specific agent's knowledge
-aircana agents refresh backend-api
+# Refresh a specific knowledge base
+aircana kb refresh backend-api
 
-# Or refresh all agents at once
-aircana agents refresh-all
+# Or refresh all knowledge bases at once
+aircana kb refresh-all
 ```
 
-Knowledge sources are tracked in `agents/<agent-name>/manifest.json`, so team members can independently refresh without manual coordination.
+Knowledge sources are tracked in `agents/<kb-name>/manifest.json`, so team members can independently refresh without manual coordination.
 
 ## Key Concepts
 
@@ -247,7 +247,7 @@ Knowledge sources are tracked in `agents/<agent-name>/manifest.json`, so team me
 
 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.)
-- **Agents**: Specialized domain experts
+- **Knowledge Bases**: Specialized domain expertise from curated documentation
 - **Commands**: Custom slash commands
 - **Hooks**: Event-driven automation
 
@@ -278,35 +278,27 @@ Optional path overrides (for non-standard layouts):
 ```json
 {
   "commands": "./custom/commands/",
-  "agents": "./custom/agents/",
+  "agents": "./custom/skills/",
   "hooks": "./config/hooks.json",
   "mcpServers": "./mcp-config.json"
 }
 ```
 
-### Specialized Agents
-
-Agents are domain-specific experts to whom Claude Code can delegate tasks and questions. Each agent has:
-- **Dedicated context window**: Prevents context pollution and maintains focus
-- **Knowledge base**: Access to curated domain-specific documentation
-- **Custom configuration**: Model, color, and behavior settings
-
-Claude Code can run agents in parallel, creating a "swarm" of experts that can expedite planning and execution while considering broader context.
-
 ### Knowledge Bases
 
-Aircana provides each agent with a human-curated knowledge base stored within the plugin structure. This enables agents to:
-- Access domain-specific documentation automatically
-- Stay up-to-date with refreshable sources
-- Provide more relevant responses with less back-and-forth
+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 agent knowledge bases once daily on session start** via the SessionStart hook, keeping agents up-to-date without manual intervention.
+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.
 
 #### Confluence
 
-To add a Confluence page to an agent's knowledge base, label the desired page in Confluence, then run `aircana agent refresh <AGENT>`.
+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 agent name during initial agent creation (`aircana agent create`).
+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.
 
@@ -314,11 +306,11 @@ See the Confluence setup guide or run `aircana doctor` for instructions on setti
 
 In addition to Confluence sources, Aircana allows adding arbitrary public websites to a knowledge base.
 
-Websites are also refreshed when `aircana agent refresh <AGENT>` is used.
+Websites are also refreshed when `aircana kb refresh <KB-NAME>` is used.
 
 #### Structure
 
-Knowledge bases are stored within the plugin's agent directory. For example:
+Knowledge bases are stored within the plugin's agents directory. For example:
 
 ```
 my-plugin/
@@ -327,7 +319,7 @@ my-plugin/
 ├── agents/
 │   ├── backend-expert.md
 │   └── backend-expert/
-│       ├── knowledge/
+│       ├── knowledge/          # (optional, for local KBs)
 │       │   ├── API-Design.md
 │       │   └── Authentication.md
 │       └── manifest.json
@@ -340,7 +332,7 @@ my-plugin/
     └── session_start.sh
 ```
 
-Agent files and their knowledge bases are co-located in the plugin's `agents/` directory.
+Knowledge base files and manifests are co-located in the plugin's `agents/` directory.
 
 **Version Control Considerations:**
 
@@ -349,12 +341,14 @@ In many cases, adding the actual knowledge base to version control is undesirabl
 - Content may include sensitive information not suitable for public repos
 - Knowledge refreshes would create frequent, large commits
 
-Aircana manages a per-agent `manifest.json` file to track knowledge sources without committing the actual content. Team members can refresh knowledge bases using `aircana agents refresh`.
+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.
 
 ### Plugin Artifacts
 
 Aircana uses ERB templates to generate plugin components consistently:
-- **Agents**: Domain experts with knowledge base integration
+- **Knowledge Bases (Skills)**: Domain expertise with curated documentation
 - **Commands**: Slash commands with parameter handling
 - **Hooks**: Event handlers for automation
 
@@ -370,9 +364,9 @@ At Instructure this means you can easily configure Claude Code to send you slack
 
 ## Best Practices
 
-### Designing Effective Agents
+### Designing Effective Knowledge Bases
 
-**Design agents as narrow domain experts, not generalists.** More granular agents with focused knowledge bases generally perform better than broad, general-purpose agents.
+**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:**
 
@@ -382,20 +376,20 @@ At Instructure this means you can easily configure Claude Code to send you slack
 - `frontend-styling-expert` - CSS, design systems, responsive layouts
 
 ❌ **Avoid - Too broad:**
-- `backend-engineer` - Too many domains, knowledge base becomes unfocused
+- `backend-engineer` - Too many domains, knowledge becomes unfocused
 - `full-stack-developer` - Overlapping responsibilities with unclear boundaries
 
 **Why narrow domains work better:**
-- **Focused knowledge bases**: Each agent gets highly relevant documentation for their specific domain
-- **Better results**: Agents can provide more accurate, detailed answers within their expertise
-- **Less context pollution**: Smaller, focused context windows prevent information overload
-- **Non-overlapping responsibilities**: Clear delegation boundaries reduce confusion
+- **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 agent should have a clear, distinct purpose
+- Each knowledge base should have a clear, distinct purpose
 - Knowledge bases should contain 5-20 highly relevant documents, not 100+ loosely related ones
-- Use agent descriptions to clearly define boundaries and expertise areas
+- Use descriptions to clearly define boundaries and expertise areas
 
 ## Development Workflow
 
@@ -587,13 +581,13 @@ aircana plugin version set         # Set specific version
 aircana plugin validate            # Validate plugin structure
 ```
 
-### Agent Management
+### Knowledge Base Management
 ```bash
-aircana agents create              # Create new agent interactively
-aircana agents refresh [AGENT]     # Sync agent knowledge from Confluence and web sources
-aircana agents refresh-all         # Refresh knowledge for all agents
-aircana agents add-url [AGENT] [URL] # Add a web URL to an agent's knowledge base
-aircana agents list                # List all configured agents
+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
 ```
 
 ### Hook Management
@@ -610,7 +604,7 @@ aircana hooks status               # Show hook configuration status
 aircana generate                   # Generate plugin components from templates
 aircana doctor                     # Check system health and dependencies
 aircana doctor --verbose           # Show detailed dependency information
-aircana dump-context [AGENT]       # View current context for agent
+aircana dump-context [KB-NAME]     # View current context for knowledge base
 ```
 
 ## Development

data/lib/aircana/cli/app.rb

@@ -9,7 +9,7 @@ require_relative "commands/init"
 
 require_relative "subcommand"
 require_relative "help_formatter"
-require_relative "commands/agents"
+require_relative "commands/kb"
 require_relative "commands/hooks"
 require_relative "commands/plugin"
 
@@ -47,35 +47,30 @@ module Aircana
         Init.run(directory: directory, plugin_name: options[:plugin_name])
       end
 
-      class AgentsSubcommand < Subcommand
-        desc "create", "Create a new agent"
+      class KBSubcommand < Subcommand
+        desc "create", "Create a new knowledge base"
         def create
-          Agents.create
+          KB.create
         end
 
-        desc "refresh AGENT", "Refresh agent knowledge from Confluence pages with matching labels"
-        def refresh(agent)
-          Agents.refresh(agent)
+        desc "refresh KB_NAME", "Refresh knowledge base from Confluence/web sources"
+        def refresh(kb_name)
+          KB.refresh(kb_name)
         end
 
-        desc "list", "List all configured agents"
+        desc "list", "List all configured knowledge bases"
         def list
-          Agents.list
+          KB.list
         end
 
-        desc "add-url AGENT URL", "Add a web URL to an agent's knowledge base"
-        def add_url(agent, url)
-          Agents.add_url(agent, url)
+        desc "add-url KB_NAME URL", "Add a web URL to a knowledge base"
+        def add_url(kb_name, url)
+          KB.add_url(kb_name, url)
         end
 
-        desc "refresh-all", "Refresh knowledge for all configured agents"
+        desc "refresh-all", "Refresh all remote knowledge bases"
         def refresh_all
-          Agents.refresh_all
-        end
-
-        desc "migrate-to-local", "Migrate remote knowledge bases to local (version-controlled)"
-        def migrate_to_local
-          Agents.migrate_to_local
+          KB.refresh_all
         end
       end
 
@@ -106,8 +101,8 @@ module Aircana
         end
       end
 
-      desc "agents", "Create and manage agents and their knowledgebases"
-      subcommand "agents", AgentsSubcommand
+      desc "kb", "Create and manage knowledge bases for Claude Code skills"
+      subcommand "kb", KBSubcommand
 
       desc "hooks", "Manage Claude Code hooks"
       subcommand "hooks", HooksSubcommand