aircana 3.2.1 → 4.0.0.rc2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. checksums.yaml +4 -4
  2. data/.rspec_status +168 -153
  3. data/CHANGELOG.md +55 -0
  4. data/CLAUDE.md +50 -39
  5. data/README.md +70 -76
  6. data/lib/aircana/cli/app.rb +16 -21
  7. data/lib/aircana/cli/commands/generate.rb +0 -12
  8. data/lib/aircana/cli/commands/kb.rb +590 -0
  9. data/lib/aircana/cli/help_formatter.rb +5 -4
  10. data/lib/aircana/configuration.rb +13 -28
  11. data/lib/aircana/contexts/confluence.rb +55 -24
  12. data/lib/aircana/contexts/confluence_content.rb +48 -5
  13. data/lib/aircana/contexts/local.rb +8 -9
  14. data/lib/aircana/contexts/manifest.rb +46 -34
  15. data/lib/aircana/contexts/web.rb +47 -17
  16. data/lib/aircana/generators/skills_generator.rb +194 -0
  17. data/lib/aircana/templates/skills/base_skill.erb +12 -0
  18. data/lib/aircana/version.rb +1 -1
  19. metadata +4 -18
  20. data/lib/aircana/cli/commands/agents.rb +0 -733
  21. data/lib/aircana/generators/agents_generator.rb +0 -79
  22. data/lib/aircana/templates/agents/base_agent.erb +0 -31
  23. data/lib/aircana/templates/agents/defaults/apply_feedback.erb +0 -91
  24. data/lib/aircana/templates/agents/defaults/executor.erb +0 -84
  25. data/lib/aircana/templates/agents/defaults/jira.erb +0 -45
  26. data/lib/aircana/templates/agents/defaults/planner.erb +0 -63
  27. data/lib/aircana/templates/agents/defaults/reviewer.erb +0 -94
  28. data/lib/aircana/templates/agents/defaults/sub-agent-coordinator.erb +0 -90
  29. data/lib/aircana/templates/hooks/refresh_agents.erb +0 -66
  30. data/lib/aircana/templates/hooks/sync_local_knowledge.erb +0 -86
  31. data/spec_target_1760656566_428/agents/test-agent/manifest.json +0 -16
  32. data/spec_target_1760656588_38/agents/test-agent/manifest.json +0 -16
  33. data/spec_target_1760656647_612/agents/test-agent/manifest.json +0 -16
  34. data/spec_target_1760656660_113/agents/test-agent/manifest.json +0 -16
  35. data/spec_target_1760656689_268/agents/test-agent/manifest.json +0 -16
  36. data/spec_target_1760656710_387/agents/test-agent/manifest.json +0 -16
data/CLAUDE.md CHANGED
@@ -12,8 +12,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
12
12
 
13
13
  ### Testing and Quality
14
14
  - `rake spec` or `bundle exec rspec` - Run all tests
15
- - `bundle exec rspec spec/aircana/cli/commands/agents_spec.rb` - Run specific test file
16
- - `bundle exec rspec spec/aircana/cli/commands/agents_spec.rb:15` - Run test at specific line
15
+ - `bundle exec rspec spec/aircana/cli/commands/kb_spec.rb` - Run specific test file
16
+ - `bundle exec rspec spec/aircana/cli/commands/kb_spec.rb:15` - Run test at specific line
17
17
  - `bundle exec rspec --format documentation` - Run tests with detailed output
18
18
  - `bundle exec rubocop` - Run linter
19
19
  - `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
36
36
  - `aircana plugin version set` - Set specific version
37
37
  - `aircana plugin validate` - Validate plugin structure and manifests
38
38
 
39
- **Agent Management:**
40
- - `aircana agents create` - Create a new agent interactively
41
- - `aircana agents list` - List all configured agents
42
- - `aircana agents refresh <agent>` - Refresh agent knowledge from Confluence and web sources
43
- - `aircana agents refresh-all` - Refresh knowledge for all configured agents
44
- - `aircana agents add-url <agent> <url>` - Add a web URL to an agent's knowledge base
39
+ **Knowledge Base Management:**
40
+ - `aircana kb create` - Create a new knowledge base interactively
41
+ - `aircana kb list` - List all configured knowledge bases
42
+ - `aircana kb refresh <kb-name>` - Refresh knowledge base from Confluence and web sources
43
+ - `aircana kb refresh-all` - Refresh knowledge for all configured knowledge bases
44
+ - `aircana kb add-url <kb-name> <url>` - Add a web URL to a knowledge base
45
45
 
46
46
  **Hook Management:**
47
47
  - `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
54
54
  - `aircana doctor` - Check system health and dependencies
55
55
  - `aircana doctor --verbose` - Show detailed dependency information
56
56
  - `aircana generate` - Generate plugin components from templates
57
- - `aircana dump-context <agent_name>` - Dump context for specified agent
57
+ - `aircana dump-context <kb-name>` - Dump context for specified knowledge base
58
58
 
59
59
  ## Architecture
60
60
 
61
61
  ### Core Structure
62
- Aircana is a Ruby gem that creates and manages Claude Code plugins. The main components:
62
+ Aircana is a Ruby gem that creates and manages Claude Code plugins with knowledge bases. The main components:
63
63
 
64
64
  - **CLI Layer** (`lib/aircana/cli/`): Thor-based command line interface with subcommands
65
65
  - `app.rb`: Main Thor application defining all commands and subcommands
66
- - `subcommand.rb`: Base class for subcommands (agents, hooks, plugin)
66
+ - `subcommand.rb`: Base class for subcommands (kb, hooks, plugin)
67
67
  - `shell_command.rb`: Shell command execution utilities
68
68
  - `commands/`: Individual command implementations
69
69
  - `init.rb`: Plugin initialization
70
70
  - `plugin.rb`: Plugin metadata management
71
- - `agents.rb`: Agent CRUD operations
71
+ - `kb.rb`: Knowledge base CRUD operations
72
72
  - `hooks.rb`: Hook management
73
73
  - `doctor.rb`: System health checks with modular check system
74
74
  - `generate.rb`: Generates plugin components from templates
75
- - `dump_context.rb`: Outputs agent knowledge for debugging
75
+ - `dump_context.rb`: Outputs knowledge base content for debugging
76
76
 
77
77
  - **Plugin Management**:
78
78
  - `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
88
88
  - HTML to Markdown conversion (ReverseMarkdown)
89
89
  - Main content extraction (removes nav, ads, scripts)
90
90
  - Claude API integration for generating meaningful page titles
91
- - `manifest.rb`: Per-agent manifest system tracking:
91
+ - `manifest.rb`: Per-knowledge-base manifest system tracking:
92
92
  - Knowledge sources (Confluence, web)
93
93
  - Source metadata (page IDs, URLs, timestamps)
94
+ - KB type (local or remote)
94
95
  - Manifest format version (1.0)
95
96
  - `local.rb`: File system operations for storing knowledge
96
97
 
97
98
  - **Generators** (`lib/aircana/generators/`): ERB-based template generation
98
99
  - `base_generator.rb`: Base class with ERB rendering and file writing
99
- - `agents_generator.rb`: Agent file generation with default agent support
100
- - Default agents: planner, jira, sub-agent-coordinator, executor, reviewer, apply_feedback
100
+ - `skills_generator.rb`: Knowledge base file generation (Markdown format)
101
101
  - Command generators: plan, execute, record, review, apply_feedback, ask_expert
102
102
  - `hooks_generator.rb`: Hook script generation
103
103
  - Templates location: `lib/aircana/templates/`
104
104
 
105
105
  - **Configuration** (`lib/aircana/configuration.rb`): Path resolution system
106
106
  - Plugin root detection via environment variables (AIRCANA_PLUGIN_ROOT, CLAUDE_PLUGIN_ROOT)
107
- - Plugin-aware paths (commands, agents, hooks directories)
107
+ - Plugin-aware paths (commands, skills, hooks directories)
108
108
  - Global vs plugin-local knowledge storage
109
109
  - Automatic plugin name extraction from plugin.json
110
+ - Resolves to `~/.claude/skills/<kb-name>/` for knowledge storage
110
111
 
111
112
  - **LLM Integration**:
112
113
  - `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
118
119
  - `fzf_helper.rb`: Interactive fuzzy selection
119
120
 
120
121
  ### Key Concepts
121
- - **Plugins**: Distributable Claude Code extensions with manifests, agents, commands, and hooks
122
+ - **Plugins**: Distributable Claude Code extensions with manifests, skills/knowledge bases, commands, and hooks
122
123
  - **Plugin Manifests**: JSON files defining plugin metadata (`.claude-plugin/plugin.json`)
123
- - **Agents**: Domain-specific experts with dedicated knowledge bases and context windows
124
- - **Knowledge Bases**: Curated documentation from Confluence and web sources
124
+ - **Knowledge Bases (Skills)**: Curated documentation from Confluence and web sources that provide domain expertise
125
+ - **Manifests**: Per-knowledge-base JSON tracking sources, metadata, and KB type (local/remote)
125
126
  - **Hooks**: Event-driven automation through `hooks/hooks.json`
126
127
  - **Commands**: Custom slash commands for workflow automation
127
128
 
128
129
  ### File Organization
129
130
  - **Plugin Structure**:
130
131
  - `.claude-plugin/plugin.json` - Plugin manifest with metadata and versioning
131
- - `agents/` - Agent markdown files (agent definitions)
132
- - `agents/<agent_name>/manifest.json` - Tracks knowledge sources per agent
132
+ - `agents/` - Knowledge base markdown files (skill definitions)
133
+ - `agents/<kb-name>/manifest.json` - Tracks knowledge sources per KB
134
+ - `agents/<kb-name>/knowledge/` - Local knowledge base content (if KB type is "local")
133
135
  - `commands/` - Slash command markdown files
134
136
  - `hooks/` - hooks.json manifest defining hook configurations
135
137
  - `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
137
139
  - **Global Configuration**:
138
140
  - `~/.aircana/` - Global Aircana configuration directory
139
141
  - `~/.aircana/aircana.out/` - Generated templates output directory
142
+ - `~/.claude/skills/` - Runtime knowledge base storage
140
143
 
141
144
  - **Knowledge Storage Architecture**:
142
- - **Global (not version controlled)**: `~/.claude/agents/<plugin-name>-<agent-name>/knowledge/`
145
+ - **Remote KBs (not version controlled)**: `~/.claude/skills/<kb-name>/`
143
146
  - Actual knowledge base content (Markdown files)
144
- - Refreshed via `aircana agents refresh`
147
+ - Refreshed via `aircana kb refresh`
145
148
  - Excluded from version control to avoid bloat/sensitivity
146
- - **Plugin-local (version controlled)**: `agents/<agent_name>/manifest.json`
149
+ - **Local KBs (version controlled)**: `agents/<kb-name>/knowledge/`
150
+ - Version-controlled knowledge content in plugin repository
151
+ - Auto-synced to `~/.claude/skills/<kb-name>/` via SessionStart hook
152
+ - Teams can collaborate on knowledge directly in Git
153
+ - **Plugin-local manifests (version controlled)**: `agents/<kb-name>/manifest.json`
147
154
  - Tracks knowledge sources (Confluence labels, web URLs)
155
+ - Specifies KB type ("local" or "remote")
148
156
  - Team members can refresh knowledge independently
149
157
  - Format:
150
158
  ```json
151
159
  {
152
160
  "version": "1.0",
153
- "agent": "agent-name",
161
+ "kb_name": "my-kb",
162
+ "kb_type": "remote",
154
163
  "sources": [
155
164
  {
156
165
  "type": "confluence",
157
- "label": "agent-name",
166
+ "label": "my-kb",
158
167
  "pages": [{"id": "123456"}]
159
168
  },
160
169
  {
@@ -201,7 +210,7 @@ This pattern keeps each module focused on a single responsibility while composin
201
210
 
202
211
  **ERB Template Generation**:
203
212
  All plugin components are generated from ERB templates in `lib/aircana/templates/`:
204
- - `agents/` - Agent templates (base_agent.erb, defaults/)
213
+ - `skills/` - Knowledge base templates (skill.md.erb)
205
214
  - `commands/` - Slash command templates
206
215
  - `hooks/` - Hook script templates
207
216
 
@@ -223,10 +232,11 @@ end
223
232
  ```
224
233
 
225
234
  **Manifest-Based Knowledge Tracking**:
226
- Each agent has a `manifest.json` that tracks knowledge sources without storing content:
227
- - Version controlled: manifest.json (sources metadata)
228
- - Not version controlled: actual knowledge content in ~/.claude/agents/
229
- - Team members run `aircana agents refresh` to sync knowledge locally
235
+ Each knowledge base has a `manifest.json` that tracks knowledge sources:
236
+ - Version controlled: `agents/<kb-name>/manifest.json` (sources metadata, KB type)
237
+ - Remote KBs: Content stored in `~/.claude/skills/<kb-name>/` (not version controlled)
238
+ - Local KBs: Content stored in `agents/<kb-name>/knowledge/` (version controlled), synced to `~/.claude/skills/`
239
+ - Team members run `aircana kb refresh` to sync remote knowledge locally
230
240
 
231
241
  **Plugin-Aware Path Resolution**:
232
242
  Configuration class detects plugin mode and resolves paths accordingly:
@@ -242,12 +252,12 @@ Configuration class detects plugin mode and resolves paths accordingly:
242
252
  - Run specific test: `bundle exec rspec spec/path/to/file_spec.rb:15`
243
253
 
244
254
  ### Knowledge Sources
245
- Agents can sync knowledge from multiple sources:
255
+ Knowledge bases can sync content from multiple sources:
246
256
 
247
257
  **Confluence Integration:**
248
258
  - Environment variables: `CONFLUENCE_BASE_URL`, `CONFLUENCE_USERNAME`, `CONFLUENCE_API_TOKEN`
249
259
  - Pages fetched via Confluence REST API v2 using HTTParty
250
- - Label-based discovery: searches for pages labeled with agent name under "global" prefix
260
+ - Label-based discovery: searches for pages labeled with KB name under "global" prefix
251
261
  - Pagination support for large result sets
252
262
  - HTML content converted to Markdown via ReverseMarkdown
253
263
  - Page metadata (ID) tracked in manifest for refresh operations
@@ -265,9 +275,10 @@ Agents can sync knowledge from multiple sources:
265
275
  - URL metadata tracked in manifest
266
276
 
267
277
  **Unified Management:**
268
- - Both source types tracked in manifest.json per agent
278
+ - Both source types tracked in manifest.json per knowledge base
269
279
  - Manifest schema version 1.0
270
- - `aircana agents refresh <agent>` refreshes all sources (Confluence + web)
271
- - `aircana agents refresh-all` refreshes all configured agents
272
- - Content stored as Markdown in `~/.claude/agents/<plugin-name>-<agent-name>/knowledge/`
273
- - Knowledge paths referenced in agent files use tilde notation: `~/.claude/agents/.../knowledge/`
280
+ - `aircana kb refresh <kb-name>` refreshes all sources (Confluence + web) for remote KBs
281
+ - `aircana kb refresh-all` refreshes all configured remote knowledge bases
282
+ - Remote KB content stored as Markdown in `~/.claude/skills/<kb-name>/`
283
+ - Local KB content stored in `agents/<kb-name>/knowledge/`, synced to `~/.claude/skills/<kb-name>/`
284
+ - Knowledge paths referenced in skill files use tilde notation: `~/.claude/skills/.../`
data/README.md CHANGED
@@ -5,9 +5,9 @@
5
5
 
6
6
  ## Intro
7
7
 
8
- 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.
8
+ 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.
9
9
 
10
- 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.
10
+ 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.
11
11
 
12
12
  ## How can I try it?
13
13
 
@@ -43,25 +43,25 @@ aircana init --plugin-name my-custom-plugin
43
43
 
44
44
  This creates a plugin structure with:
45
45
  - `.claude-plugin/plugin.json` - Plugin manifest
46
- - `agents/` - Specialized agents
46
+ - `agents/` - Knowledge base definitions
47
47
  - `commands/` - Slash commands
48
48
  - `hooks/` - Hook configurations (hooks.json)
49
49
  - `scripts/` - Hook scripts and utilities
50
50
 
51
51
  ### Next Steps
52
52
 
53
- **1. Create a specialized agent:**
53
+ **1. Create a specialized knowledge base:**
54
54
  ```bash
55
- aircana agents create
55
+ aircana kb create
56
56
  ```
57
57
 
58
58
  **2. Add knowledge sources:**
59
59
  ```bash
60
60
  # From Confluence (requires configuration)
61
- aircana agents refresh my-agent
61
+ aircana kb refresh my-kb
62
62
 
63
63
  # From web URLs
64
- aircana agents add-url my-agent https://docs.example.com
64
+ aircana kb add-url my-kb https://docs.example.com
65
65
  ```
66
66
 
67
67
  **3. Manage your plugin:**
@@ -85,11 +85,11 @@ aircana plugin validate
85
85
 
86
86
  ### Things to try
87
87
 
88
- - Follow the [Getting Started](#getting-started) tutorial to create agents with knowledge bases—Aircana's key differentiator
88
+ - Follow the [Getting Started](#getting-started) tutorial to create knowledge bases—Aircana's key differentiator
89
89
 
90
- - Configure the Confluence integration and create domain-specific agents
90
+ - Configure the Confluence integration and create domain-specific knowledge bases
91
91
 
92
- - Use the `/ask-expert` command to consult multiple specialized agents
92
+ - Use the `/ask-expert` command to consult multiple specialized experts
93
93
 
94
94
  - Set up the development workflow with plan, execute, review, and apply-feedback commands
95
95
 
@@ -97,7 +97,7 @@ aircana plugin validate
97
97
 
98
98
  ## Getting Started
99
99
 
100
- 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.
100
+ 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.
101
101
 
102
102
  ### Prerequisites
103
103
 
@@ -140,45 +140,45 @@ ls -la
140
140
 
141
141
  This creates:
142
142
  - `.claude-plugin/plugin.json` - Plugin manifest with metadata
143
- - `agents/` - Directory for specialized agents
143
+ - `agents/` - Directory for knowledge base definitions
144
144
  - `commands/` - Custom slash commands
145
145
  - `hooks/hooks.json` - Hook configurations
146
146
  - `scripts/` - Hook scripts and utilities
147
147
 
148
- ### Step 2: Create an Agent Backed by Confluence
148
+ ### Step 2: Create a Knowledge Base Backed by Confluence
149
149
 
150
150
  ```bash
151
- aircana agents create
151
+ aircana kb create
152
152
  ```
153
153
 
154
154
  You'll be prompted for:
155
- - **Agent name**: e.g., "backend-api" (use kebab-case)
155
+ - **Knowledge base name**: e.g., "backend-api" (use kebab-case)
156
156
  - **Description**: e.g., "Expert in backend API development and best practices"
157
157
  - **Model**: Choose sonnet (smarter), haiku (faster), or inherit (uses default)
158
158
  - **Color**: Pick an interface color for visual identification
159
159
 
160
- The agent file is created at `agents/backend-api.md` with:
161
- - Agent configuration (name, description, model)
160
+ The knowledge base file is created at `agents/backend-api.md` with:
161
+ - Configuration (name, description, model)
162
162
  - Knowledge base path reference
163
163
  - Custom instructions
164
164
 
165
165
  ### Step 3: Tag Confluence Pages
166
166
 
167
- In Confluence, label pages you want the agent to access:
167
+ In Confluence, label pages you want the knowledge base to access:
168
168
 
169
169
  1. Open a relevant Confluence page (e.g., "API Design Guidelines")
170
170
  2. Click **...** → **Edit labels**
171
- 3. Add label: `backend-api` (must match your agent name)
171
+ 3. Add label: `backend-api` (must match your knowledge base name)
172
172
  4. Click **Save**
173
173
 
174
- Repeat for all documentation pages relevant to this agent. Aircana will discover pages by label during the refresh process.
174
+ Repeat for all documentation pages relevant to this knowledge base. Aircana will discover pages by label during the refresh process.
175
175
 
176
176
  **Tip:** Use a consistent labeling strategy. For example, label all backend documentation with `backend-api`, all frontend docs with `frontend-expert`, etc.
177
177
 
178
- ### Step 4: Refresh Agent Knowledge
178
+ ### Step 4: Refresh Knowledge Base
179
179
 
180
180
  ```bash
181
- aircana agents refresh backend-api
181
+ aircana kb refresh backend-api
182
182
  ```
183
183
 
184
184
  This will:
@@ -188,43 +188,43 @@ This will:
188
188
  4. Store content in the knowledge base directory
189
189
  5. Update `agents/backend-api/manifest.json` with source metadata
190
190
 
191
- **Output:** Knowledge files are created in `~/.claude/agents/my-team-backend-api/knowledge/`
191
+ **Output:** Knowledge files are created in `~/.claude/skills/backend-api/`
192
192
 
193
193
  **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.
194
194
 
195
195
  ### Step 5: Add Web URLs (Optional)
196
196
 
197
- You can also add public web documentation to your agent's knowledge base:
197
+ You can also add public web documentation to your knowledge base:
198
198
 
199
199
  ```bash
200
- aircana agents add-url backend-api https://docs.example.com/api-guide
201
- aircana agents add-url backend-api https://restfulapi.net/rest-architectural-constraints/
200
+ aircana kb add-url backend-api https://docs.example.com/api-guide
201
+ aircana kb add-url backend-api https://restfulapi.net/rest-architectural-constraints/
202
202
  ```
203
203
 
204
204
  This downloads the web page, extracts main content (removes nav/ads/scripts), converts to Markdown, and adds it to the knowledge base.
205
205
 
206
206
  Refresh to sync web URLs:
207
207
  ```bash
208
- aircana agents refresh backend-api
208
+ aircana kb refresh backend-api
209
209
  ```
210
210
 
211
- ### Step 6: Use Your Agent
211
+ ### Step 6: Use Your Knowledge Base
212
212
 
213
- 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:
213
+ Your knowledge base is now ready! Claude Code will automatically use it when appropriate based on the description. You can also explicitly invoke it:
214
214
 
215
215
  ```
216
216
  Ask backend-api to review this API endpoint design
217
217
  Ask backend-api how to implement authentication
218
218
  ```
219
219
 
220
- The agent has access to all Confluence pages and web URLs you've synced to its knowledge base.
220
+ Claude has access to all Confluence pages and web URLs you've synced to the knowledge base.
221
221
 
222
222
  ### Step 7: Share Your Plugin with Your Team
223
223
 
224
224
  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).
225
225
 
226
226
  **Quick summary:**
227
- - Share via Git repository: Team members clone the plugin, configure Confluence credentials, and run `aircana agents refresh-all`
227
+ - Share via Git repository: Team members clone the plugin, configure Confluence credentials, and run `aircana kb refresh-all`
228
228
  - 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
229
229
 
230
230
  ### Next: Keep Knowledge Up-to-Date
@@ -232,14 +232,14 @@ For detailed instructions on distributing your plugin via Git repositories or Cl
232
232
  As your Confluence documentation evolves:
233
233
 
234
234
  ```bash
235
- # Refresh a specific agent's knowledge
236
- aircana agents refresh backend-api
235
+ # Refresh a specific knowledge base
236
+ aircana kb refresh backend-api
237
237
 
238
- # Or refresh all agents at once
239
- aircana agents refresh-all
238
+ # Or refresh all knowledge bases at once
239
+ aircana kb refresh-all
240
240
  ```
241
241
 
242
- Knowledge sources are tracked in `agents/<agent-name>/manifest.json`, so team members can independently refresh without manual coordination.
242
+ Knowledge sources are tracked in `agents/<kb-name>/manifest.json`, so team members can independently refresh without manual coordination.
243
243
 
244
244
  ## Key Concepts
245
245
 
@@ -247,7 +247,7 @@ Knowledge sources are tracked in `agents/<agent-name>/manifest.json`, so team me
247
247
 
248
248
  Aircana creates Claude Code plugins - portable, distributable packages that extend Claude Code with custom functionality. Each plugin includes:
249
249
  - **Manifest**: Metadata describing the plugin (name, version, author, etc.)
250
- - **Agents**: Specialized domain experts
250
+ - **Knowledge Bases**: Specialized domain expertise from curated documentation
251
251
  - **Commands**: Custom slash commands
252
252
  - **Hooks**: Event-driven automation
253
253
 
@@ -278,35 +278,27 @@ Optional path overrides (for non-standard layouts):
278
278
  ```json
279
279
  {
280
280
  "commands": "./custom/commands/",
281
- "agents": "./custom/agents/",
281
+ "agents": "./custom/skills/",
282
282
  "hooks": "./config/hooks.json",
283
283
  "mcpServers": "./mcp-config.json"
284
284
  }
285
285
  ```
286
286
 
287
- ### Specialized Agents
288
-
289
- Agents are domain-specific experts to whom Claude Code can delegate tasks and questions. Each agent has:
290
- - **Dedicated context window**: Prevents context pollution and maintains focus
291
- - **Knowledge base**: Access to curated domain-specific documentation
292
- - **Custom configuration**: Model, color, and behavior settings
293
-
294
- Claude Code can run agents in parallel, creating a "swarm" of experts that can expedite planning and execution while considering broader context.
295
-
296
287
  ### Knowledge Bases
297
288
 
298
- Aircana provides each agent with a human-curated knowledge base stored within the plugin structure. This enables agents to:
299
- - Access domain-specific documentation automatically
300
- - Stay up-to-date with refreshable sources
301
- - Provide more relevant responses with less back-and-forth
289
+ Aircana creates human-curated knowledge bases that provide Claude Code with domain-specific expertise. Each knowledge base:
290
+ - **Provides focused documentation**: Access to curated domain-specific content
291
+ - **Stays up-to-date**: Refreshable sources from Confluence and web URLs
292
+ - **Improves responses**: More relevant, predictable results with less back-and-forth
293
+ - **Custom configuration**: Model, color, and behavior settings
302
294
 
303
- 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.
295
+ 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.
304
296
 
305
297
  #### Confluence
306
298
 
307
- To add a Confluence page to an agent's knowledge base, label the desired page in Confluence, then run `aircana agent refresh <AGENT>`.
299
+ To add a Confluence page to a knowledge base, label the desired page in Confluence, then run `aircana kb refresh <KB-NAME>`.
308
300
 
309
- Aircana will also pull any Confluence pages labeled with a matching agent name during initial agent creation (`aircana agent create`).
301
+ Aircana will also pull any Confluence pages labeled with a matching knowledge base name during initial creation (`aircana kb create`).
310
302
 
311
303
  See the Confluence setup guide or run `aircana doctor` for instructions on setting up Confluence integration.
312
304
 
@@ -314,11 +306,11 @@ See the Confluence setup guide or run `aircana doctor` for instructions on setti
314
306
 
315
307
  In addition to Confluence sources, Aircana allows adding arbitrary public websites to a knowledge base.
316
308
 
317
- Websites are also refreshed when `aircana agent refresh <AGENT>` is used.
309
+ Websites are also refreshed when `aircana kb refresh <KB-NAME>` is used.
318
310
 
319
311
  #### Structure
320
312
 
321
- Knowledge bases are stored within the plugin's agent directory. For example:
313
+ Knowledge bases are stored within the plugin's agents directory. For example:
322
314
 
323
315
  ```
324
316
  my-plugin/
@@ -327,7 +319,7 @@ my-plugin/
327
319
  ├── agents/
328
320
  │ ├── backend-expert.md
329
321
  │ └── backend-expert/
330
- │ ├── knowledge/
322
+ │ ├── knowledge/ # (optional, for local KBs)
331
323
  │ │ ├── API-Design.md
332
324
  │ │ └── Authentication.md
333
325
  │ └── manifest.json
@@ -340,7 +332,7 @@ my-plugin/
340
332
  └── session_start.sh
341
333
  ```
342
334
 
343
- Agent files and their knowledge bases are co-located in the plugin's `agents/` directory.
335
+ Knowledge base files and manifests are co-located in the plugin's `agents/` directory.
344
336
 
345
337
  **Version Control Considerations:**
346
338
 
@@ -349,12 +341,14 @@ In many cases, adding the actual knowledge base to version control is undesirabl
349
341
  - Content may include sensitive information not suitable for public repos
350
342
  - Knowledge refreshes would create frequent, large commits
351
343
 
352
- 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`.
344
+ 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`.
345
+
346
+ 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.
353
347
 
354
348
  ### Plugin Artifacts
355
349
 
356
350
  Aircana uses ERB templates to generate plugin components consistently:
357
- - **Agents**: Domain experts with knowledge base integration
351
+ - **Knowledge Bases (Skills)**: Domain expertise with curated documentation
358
352
  - **Commands**: Slash commands with parameter handling
359
353
  - **Hooks**: Event handlers for automation
360
354
 
@@ -370,9 +364,9 @@ At Instructure this means you can easily configure Claude Code to send you slack
370
364
 
371
365
  ## Best Practices
372
366
 
373
- ### Designing Effective Agents
367
+ ### Designing Effective Knowledge Bases
374
368
 
375
- **Design agents as narrow domain experts, not generalists.** More granular agents with focused knowledge bases generally perform better than broad, general-purpose agents.
369
+ **Design knowledge bases as narrow domain experts, not generalists.** More granular knowledge bases with focused content generally perform better than broad, general-purpose ones.
376
370
 
377
371
  **Examples:**
378
372
 
@@ -382,20 +376,20 @@ At Instructure this means you can easily configure Claude Code to send you slack
382
376
  - `frontend-styling-expert` - CSS, design systems, responsive layouts
383
377
 
384
378
  ❌ **Avoid - Too broad:**
385
- - `backend-engineer` - Too many domains, knowledge base becomes unfocused
379
+ - `backend-engineer` - Too many domains, knowledge becomes unfocused
386
380
  - `full-stack-developer` - Overlapping responsibilities with unclear boundaries
387
381
 
388
382
  **Why narrow domains work better:**
389
- - **Focused knowledge bases**: Each agent gets highly relevant documentation for their specific domain
390
- - **Better results**: Agents can provide more accurate, detailed answers within their expertise
391
- - **Less context pollution**: Smaller, focused context windows prevent information overload
392
- - **Non-overlapping responsibilities**: Clear delegation boundaries reduce confusion
383
+ - **Focused content**: Each knowledge base contains highly relevant documentation for a specific domain
384
+ - **Better results**: More accurate, detailed responses within the area of expertise
385
+ - **Less context pollution**: Smaller, focused content prevents information overload
386
+ - **Clear boundaries**: Non-overlapping domains reduce confusion
393
387
 
394
388
  **Tips:**
395
389
  - Break large domains into smaller, specialized areas
396
- - Each agent should have a clear, distinct purpose
390
+ - Each knowledge base should have a clear, distinct purpose
397
391
  - Knowledge bases should contain 5-20 highly relevant documents, not 100+ loosely related ones
398
- - Use agent descriptions to clearly define boundaries and expertise areas
392
+ - Use descriptions to clearly define boundaries and expertise areas
399
393
 
400
394
  ## Development Workflow
401
395
 
@@ -587,13 +581,13 @@ aircana plugin version set # Set specific version
587
581
  aircana plugin validate # Validate plugin structure
588
582
  ```
589
583
 
590
- ### Agent Management
584
+ ### Knowledge Base Management
591
585
  ```bash
592
- aircana agents create # Create new agent interactively
593
- aircana agents refresh [AGENT] # Sync agent knowledge from Confluence and web sources
594
- aircana agents refresh-all # Refresh knowledge for all agents
595
- aircana agents add-url [AGENT] [URL] # Add a web URL to an agent's knowledge base
596
- aircana agents list # List all configured agents
586
+ aircana kb create # Create new knowledge base interactively
587
+ aircana kb refresh [KB-NAME] # Sync knowledge base from Confluence and web sources
588
+ aircana kb refresh-all # Refresh all knowledge bases
589
+ aircana kb add-url [KB-NAME] [URL] # Add a web URL to a knowledge base
590
+ aircana kb list # List all configured knowledge bases
597
591
  ```
598
592
 
599
593
  ### Hook Management
@@ -610,7 +604,7 @@ aircana hooks status # Show hook configuration status
610
604
  aircana generate # Generate plugin components from templates
611
605
  aircana doctor # Check system health and dependencies
612
606
  aircana doctor --verbose # Show detailed dependency information
613
- aircana dump-context [AGENT] # View current context for agent
607
+ aircana dump-context [KB-NAME] # View current context for knowledge base
614
608
  ```
615
609
 
616
610
  ## Development
@@ -9,7 +9,7 @@ require_relative "commands/init"
9
9
 
10
10
  require_relative "subcommand"
11
11
  require_relative "help_formatter"
12
- require_relative "commands/agents"
12
+ require_relative "commands/kb"
13
13
  require_relative "commands/hooks"
14
14
  require_relative "commands/plugin"
15
15
 
@@ -47,35 +47,30 @@ module Aircana
47
47
  Init.run(directory: directory, plugin_name: options[:plugin_name])
48
48
  end
49
49
 
50
- class AgentsSubcommand < Subcommand
51
- desc "create", "Create a new agent"
50
+ class KBSubcommand < Subcommand
51
+ desc "create", "Create a new knowledge base"
52
52
  def create
53
- Agents.create
53
+ KB.create
54
54
  end
55
55
 
56
- desc "refresh AGENT", "Refresh agent knowledge from Confluence pages with matching labels"
57
- def refresh(agent)
58
- Agents.refresh(agent)
56
+ desc "refresh KB_NAME", "Refresh knowledge base from Confluence/web sources"
57
+ def refresh(kb_name)
58
+ KB.refresh(kb_name)
59
59
  end
60
60
 
61
- desc "list", "List all configured agents"
61
+ desc "list", "List all configured knowledge bases"
62
62
  def list
63
- Agents.list
63
+ KB.list
64
64
  end
65
65
 
66
- desc "add-url AGENT URL", "Add a web URL to an agent's knowledge base"
67
- def add_url(agent, url)
68
- Agents.add_url(agent, url)
66
+ desc "add-url KB_NAME URL", "Add a web URL to a knowledge base"
67
+ def add_url(kb_name, url)
68
+ KB.add_url(kb_name, url)
69
69
  end
70
70
 
71
- desc "refresh-all", "Refresh knowledge for all configured agents"
71
+ desc "refresh-all", "Refresh all remote knowledge bases"
72
72
  def refresh_all
73
- Agents.refresh_all
74
- end
75
-
76
- desc "migrate-to-local", "Migrate remote knowledge bases to local (version-controlled)"
77
- def migrate_to_local
78
- Agents.migrate_to_local
73
+ KB.refresh_all
79
74
  end
80
75
  end
81
76
 
@@ -106,8 +101,8 @@ module Aircana
106
101
  end
107
102
  end
108
103
 
109
- desc "agents", "Create and manage agents and their knowledgebases"
110
- subcommand "agents", AgentsSubcommand
104
+ desc "kb", "Create and manage knowledge bases for Claude Code skills"
105
+ subcommand "kb", KBSubcommand
111
106
 
112
107
  desc "hooks", "Manage Claude Code hooks"
113
108
  subcommand "hooks", HooksSubcommand