Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

refactor: move plugin skills to standard `skills/` location (#997)

Maximilian Roos800b2afa8277
diff --git a/.claude-plugin/CLAUDE.md b/.claude-plugin/CLAUDE.md
index 3aed7e795..351783758 100644
--- a/.claude-plugin/CLAUDE.md
+++ b/.claude-plugin/CLAUDE.md
@@ -1,35 +1,20 @@
# Claude Code Plugin Guidelines
-## Skills Directory Location
+## Directory Layout
-**Working solution**: Using `source: "./.claude-plugin"` in `marketplace.json` allows skills to remain in `.claude-plugin/skills/` ✅
+Skills are at the repo root (`skills/worktrunk/`) — the standard plugin location.
+Hooks remain in `.claude-plugin/hooks/` for now.
-Configuration in `marketplace.json`:
-```json
-{
- "source": "./.claude-plugin",
- "skills": ["./skills/worktrunk"]
-}
```
-
-Configuration in `plugin.json`:
-```json
-{
- "hooks": "./hooks/hooks.json",
- "skills": ["./skills/worktrunk"]
-}
+worktrunk.skills/ ← plugin root
+├── .claude-plugin/
+│ ├── plugin.json ← manifest
+│ └── hooks/hooks.json ← activity tracking hooks
+└── skills/
+ └── worktrunk/ ← main skill + reference docs
```
-**Path resolution**:
-- Source base: `./.claude-plugin`
-- Skills: `./.claude-plugin + ./skills/worktrunk = ./.claude-plugin/skills/worktrunk` ✅
-- Hooks: `./.claude-plugin + ./hooks/hooks.json = ./.claude-plugin/hooks/hooks.json` ✅
-
-This approach keeps all Claude Code components organized together in `.claude-plugin/` and avoids root directory clutter.
-
-**Note**: The official Claude Code documentation states "All other directories (commands/, agents/, skills/, hooks/) must be at the plugin root" but using the `source` field to point to `./.claude-plugin` makes paths relative to that directory, allowing this organizational structure.
-
-**Why this works**: The `source` field in `marketplace.json` changes the base directory for path resolution. When `source: "./"` (the default), skills paths are resolved from the plugin root. When `source: "./.claude-plugin"`, skills paths are resolved from `.claude-plugin/`, allowing the entire plugin to be self-contained in one directory.
+Paths in `plugin.json` and `marketplace.json` resolve from the plugin root (repo root).
## Known Limitations
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 7118fac7b..fdca8ad12 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -12,7 +12,7 @@
{
"name": "worktrunk",
"description": "Worktrunk is a git worktree management CLI that streamlines multi-branch development. This plugin provides Claude Code integration with two features: (1) A configuration skill guiding you through LLM-powered commit message generation, project automation hooks (post-create, pre-merge), and worktree path customization. (2) Automatic activity tracking that displays 🤖 (working) and 💬 (waiting) indicators in `wt list`, showing which branches have active Claude sessions. Use when setting up Worktrunk configuration, automating project workflows, or monitoring AI activity across branches.",
- "source": "./.claude-plugin",
+ "source": ".",
"strict": false,
"skills": [
"./skills/worktrunk"
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index f68cad3d1..dcfb71e2d 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -5,7 +5,7 @@
"author": {
"name": "Worktrunk"
},
- "hooks": "./hooks/hooks.json",
+ "hooks": "./.claude-plugin/hooks/hooks.json",
"skills": [
"./skills/worktrunk"
]
diff --git a/.claude-plugin/skills/worktrunk/reference/README.md b/.claude-plugin/skills/worktrunk/reference/README.md
deleted file mode 120000
index ff5c79602..000000000
--- a/.claude-plugin/skills/worktrunk/reference/README.md
+++ /dev/null
@@ -1 +0,0 @@
-../../../../README.md
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
index 78dce5c46..381907cd9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -123,7 +123,7 @@ Documentation has three categories:
```
src/cli/mod.rs (PRIMARY SOURCE)
↓ test_command_pages_and_skill_files_are_in_sync
- docs/content/{command}.md → .claude-plugin/skills/worktrunk/reference/{command}.md
+ docs/content/{command}.md → skills/worktrunk/reference/{command}.md
```
Edit `src/cli/mod.rs` (`after_long_help` attributes), never the docs directly.
@@ -131,12 +131,12 @@ Documentation has three categories:
```
docs/content/*.md (PRIMARY SOURCE)
↓ test_command_pages_and_skill_files_are_in_sync
- .claude-plugin/skills/worktrunk/reference/*.md
+ skills/worktrunk/reference/*.md
```
Edit the docs file directly. Skill reference is auto-synced.
3. **Skill-only files** (shell-integration.md, troubleshooting.md):
- Edit `.claude-plugin/skills/worktrunk/reference/` directly — no docs equivalent.
+ Edit `skills/worktrunk/reference/` directly — no docs equivalent.
After any doc changes, run tests to sync:
diff --git a/Cargo.toml b/Cargo.toml
index 36cee7c73..e5059c504 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -21,7 +21,7 @@ allow-branch = ["*"]
consolidate-commits = true
pre-release-replacements = [
# Update skill version marker
- { file = ".claude-plugin/skills/worktrunk/SKILL.md", search = "worktrunk-skill-version: [0-9.]+", replace = "worktrunk-skill-version: {{version}}" },
+ { file = "skills/worktrunk/SKILL.md", search = "worktrunk-skill-version: [0-9.]+", replace = "worktrunk-skill-version: {{version}}" },
]
[package.metadata.cargo-udeps.ignore]
diff --git a/.claude-plugin/skills/worktrunk/SKILL.md b/skills/worktrunk/SKILL.md
similarity index 100%
rename from .claude-plugin/skills/worktrunk/SKILL.md
rename to skills/worktrunk/SKILL.md
diff --git a/skills/worktrunk/reference/README.md b/skills/worktrunk/reference/README.md
new file mode 120000
index 000000000..8a33348c7
--- /dev/null
+++ b/skills/worktrunk/reference/README.md
@@ -0,0 +1 @@
+../../../README.md
\ No newline at end of file
diff --git a/.claude-plugin/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.md
similarity index 100%
rename from .claude-plugin/skills/worktrunk/reference/claude-code.md
rename to skills/worktrunk/reference/claude-code.md
diff --git a/.claude-plugin/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
similarity index 100%
rename from .claude-plugin/skills/worktrunk/reference/config.md
rename to skills/worktrunk/reference/config.md
diff --git a/.claude-plugin/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.md
similarity index 100%
rename from .claude-plugin/skills/worktrunk/reference/faq.md
rename to skills/worktrunk/reference/faq.md
diff --git a/.claude-plugin/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
similarity index 100%
rename from .claude-plugin/skills/worktrunk/reference/hook.md
rename to skills/worktrunk/reference/hook.md
diff --git a/.claude-plugin/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.md
similarity index 100%
rename from .claude-plugin/skills/worktrunk/reference/list.md
rename to skills/worktrunk/reference/list.md
diff --git a/.claude-plugin/skills/worktrunk/reference/llm-commits.md b/skills/worktrunk/reference/llm-commits.md
similarity index 100%
rename from .claude-plugin/skills/worktrunk/reference/llm-commits.md
rename to skills/worktrunk/reference/llm-commits.md
diff --git a/.claude-plugin/skills/worktrunk/reference/merge.md b/skills/worktrunk/reference/merge.md
similarity index 100%
rename from .claude-plugin/skills/worktrunk/reference/merge.md
rename to skills/worktrunk/reference/merge.md
diff --git a/.claude-plugin/skills/worktrunk/reference/remove.md b/skills/worktrunk/reference/remove.md
similarity index 100%
rename from .claude-plugin/skills/worktrunk/reference/remove.md
rename to skills/worktrunk/reference/remove.md
diff --git a/.claude-plugin/skills/worktrunk/reference/shell-integration.md b/skills/worktrunk/reference/shell-integration.md
similarity index 100%
rename from .claude-plugin/skills/worktrunk/reference/shell-integration.md
rename to skills/worktrunk/reference/shell-integration.md
diff --git a/.claude-plugin/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
similarity index 100%
rename from .claude-plugin/skills/worktrunk/reference/step.md
rename to skills/worktrunk/reference/step.md
diff --git a/.claude-plugin/skills/worktrunk/reference/switch.md b/skills/worktrunk/reference/switch.md
similarity index 100%
rename from .claude-plugin/skills/worktrunk/reference/switch.md
rename to skills/worktrunk/reference/switch.md
diff --git a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.md
similarity index 100%
rename from .claude-plugin/skills/worktrunk/reference/tips-patterns.md
rename to skills/worktrunk/reference/tips-patterns.md
diff --git a/.claude-plugin/skills/worktrunk/reference/troubleshooting.md b/skills/worktrunk/reference/troubleshooting.md
similarity index 100%
rename from .claude-plugin/skills/worktrunk/reference/troubleshooting.md
rename to skills/worktrunk/reference/troubleshooting.md
diff --git a/.claude-plugin/skills/worktrunk/reference/worktrunk.md b/skills/worktrunk/reference/worktrunk.md
similarity index 100%
rename from .claude-plugin/skills/worktrunk/reference/worktrunk.md
rename to skills/worktrunk/reference/worktrunk.md
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index 78d0fa372..b3989ceeb 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -1527,70 +1527,33 @@ fn remove_section(content: &str, heading: &str) -> String {
}
}
-/// Skill files to sync from docs
-/// Format: (docs_path, skill_path)
-/// Files are synced with content transformed for skill consumption
-const SKILL_SYNC_FILES: &[(&str, &str)] = &[
- (
- "docs/content/hook.md",
- ".claude-plugin/skills/worktrunk/reference/hook.md",
- ),
- (
- "docs/content/config.md",
- ".claude-plugin/skills/worktrunk/reference/config.md",
- ),
- (
- "docs/content/switch.md",
- ".claude-plugin/skills/worktrunk/reference/switch.md",
- ),
- (
- "docs/content/merge.md",
- ".claude-plugin/skills/worktrunk/reference/merge.md",
- ),
- (
- "docs/content/list.md",
- ".claude-plugin/skills/worktrunk/reference/list.md",
- ),
- // Note: select.md removed - it's a deprecated hidden alias for `wt switch`
- (
- "docs/content/step.md",
- ".claude-plugin/skills/worktrunk/reference/step.md",
- ),
- (
- "docs/content/remove.md",
- ".claude-plugin/skills/worktrunk/reference/remove.md",
- ),
- (
- "docs/content/llm-commits.md",
- ".claude-plugin/skills/worktrunk/reference/llm-commits.md",
- ),
- (
- "docs/content/tips-patterns.md",
- ".claude-plugin/skills/worktrunk/reference/tips-patterns.md",
- ),
- (
- "docs/content/worktrunk.md",
- ".claude-plugin/skills/worktrunk/reference/worktrunk.md",
- ),
- (
- "docs/content/faq.md",
- ".claude-plugin/skills/worktrunk/reference/faq.md",
- ),
- (
- "docs/content/claude-code.md",
- ".claude-plugin/skills/worktrunk/reference/claude-code.md",
- ),
-];
-
-/// Sync skill files from docs/content/*.md to .claude-plugin/skills/worktrunk/reference/*.md
+/// Sync all docs/content/*.md files to skills/worktrunk/reference/*.md
+/// (excluding _index.md which is a Zola template)
/// Returns (errors, updated_files)
fn sync_skill_files(project_root: &Path) -> (Vec<String>, Vec<String>) {
let mut errors = Vec::new();
let mut updated_files = Vec::new();
- for (docs_path, skill_path) in SKILL_SYNC_FILES {
- let docs_file = project_root.join(docs_path);
- let skill_file = project_root.join(skill_path);
+ let docs_dir = project_root.join("docs/content");
+ let skill_dir = project_root.join("skills/worktrunk/reference");
+
+ let mut entries: Vec<_> = fs::read_dir(&docs_dir)
+ .unwrap_or_else(|e| panic!("Failed to read {}: {}", docs_dir.display(), e))
+ .filter_map(|entry| {
+ let entry = entry.ok()?;
+ let name = entry.file_name().to_string_lossy().to_string();
+ if name.ends_with(".md") && !name.starts_with('_') {
+ Some(name)
+ } else {
+ None
+ }
+ })
+ .collect();
+ entries.sort();
+
+ for name in &entries {
+ let docs_file = docs_dir.join(name);
+ let skill_file = skill_dir.join(name);
if !docs_file.exists() {
errors.push(format!("Missing docs file: {}", docs_file.display()));
@@ -1621,7 +1584,7 @@ fn sync_skill_files(project_root: &Path) -> (Vec<String>, Vec<String>) {
}
fs::write(&skill_file, format!("{}\n", expected))
.unwrap_or_else(|e| panic!("Failed to write {}: {}", skill_file.display(), e));
- updated_files.push(skill_path.to_string());
+ updated_files.push(format!("skills/worktrunk/reference/{name}"));
}
}
@@ -1637,7 +1600,7 @@ fn test_command_pages_and_skill_files_are_in_sync() {
// Step 1: Sync command pages (mod.rs → docs/content/*.md)
let (cmd_errors, cmd_files) = sync_command_pages(project_root);
- // Step 2: Sync skill files (docs/content/*.md → .claude-plugin/skills/*)
+ // Step 2: Sync skill files (docs/content/*.md → skills/*)
// This reads the freshly-written docs from step 1
let (skill_errors, skill_files) = sync_skill_files(project_root);