ππΌββοΈ The blackboard for coding agents - agentic development environment for claude code, codex, cursor, opencode, grok and more.
Rust adeai-agentsclaudeclaude-codecodexcursorgeminigrokopencodespec-driven-developmentvibe-codingvim
//! Default skill content for agtx phases, and the per-agent skill/command
//! plumbing that deploys and discovers it.
//!
//! Skills follow the Agent Skills spec (SKILL.md with YAML frontmatter +
//! markdown). Content is loaded from .md files at compile time via
//! `include_str!()`. Agent-specific paths and syntax are read from the agent's
//! [`AgentSpec`](crate::agent::AgentSpec) rather than matched on its name.
use crate::agent::{CommandSyntax, SkillLayout};
pub const RESEARCH_SKILL: &str = include_str!("../plugins/agtx/skills/research.md");
pub const PLAN_SKILL: &str = include_str!("../plugins/agtx/skills/plan.md");
pub const EXECUTE_SKILL: &str = include_str!("../plugins/agtx/skills/execute.md");
pub const REVIEW_SKILL: &str = include_str!("../plugins/agtx/skills/review.md");
pub const ORCHESTRATE_SKILL: &str = include_str!("../plugins/agtx/skills/orchestrate.md");
pub const MERGE_CONFLICTS_SKILL: &str = include_str!("../plugins/agtx/skills/merge-conflicts.md");
/// Default built-in skills: (directory_name, SKILL.md content)
/// Used for worktree phases (Research, Planning, Running, Review)
pub const BUILTIN_SKILLS: &[(&str, &str)] = &[
("agtx-research", RESEARCH_SKILL),
("agtx-plan", PLAN_SKILL),
("agtx-execute", EXECUTE_SKILL),
("agtx-review", REVIEW_SKILL),
("agtx-orchestrate", ORCHESTRATE_SKILL),
("agtx-merge-conflicts", MERGE_CONFLICTS_SKILL),
];
/// Load a bundled plugin by name from compile-time embedded TOML.
pub fn load_bundled_plugin(name: &str) -> Option<crate::config::WorkflowPlugin> {
BUNDLED_PLUGINS
.iter()
.find(|(n, _, _)| *n == name)
.and_then(|(_, _, content)| toml::from_str(content).ok())
}
/// A custom (on-disk) workflow plugin discovered in a plugins directory.
pub struct CustomPlugin {
pub name: String,
pub description: String,
pub plugin: crate::config::WorkflowPlugin,
}
/// Discover custom plugins on disk that are not shipped as bundled plugins.
///
/// Scans the global plugins directory (`~/.config/agtx/plugins/`) then the
/// project-local one (`{project}/.agtx/plugins/`). A project-local plugin
/// shadows a global one of the same name, matching [`crate::config::WorkflowPlugin::load`].
/// Names matching a bundled plugin are skipped: the bundled entry already
/// represents them in pickers, and `load` resolves the on-disk copy transparently.
pub fn discover_custom_plugins(project_path: Option<&std::path::Path>) -> Vec<CustomPlugin> {
use crate::config::WorkflowPlugin;
let mut dirs: Vec<std::path::PathBuf> = Vec::new();
if let Some(dir) = WorkflowPlugin::global_plugins_dir() {
dirs.push(dir);
}
if let Some(pp) = project_path {
dirs.push(WorkflowPlugin::project_plugins_dir(pp));
}
discover_custom_plugins_in(&dirs)
}
/// Discover custom plugins across the given plugins directories, in order of
/// increasing precedence (later directories shadow earlier ones by name).
fn discover_custom_plugins_in(dirs: &[std::path::PathBuf]) -> Vec<CustomPlugin> {
use std::collections::BTreeMap;
let mut found: BTreeMap<String, CustomPlugin> = BTreeMap::new();
for dir in dirs {
let Ok(entries) = std::fs::read_dir(dir) else {
continue;
};
for entry in entries.flatten() {
let path = entry.path();
if !path.is_dir() {
continue;
}
let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
continue;
};
if BUNDLED_PLUGINS.iter().any(|(n, _, _)| *n == name) {
continue;
}
if crate::config::WorkflowPlugin::validate_plugin_name(name).is_err() {
continue;
}
let Ok(content) = std::fs::read_to_string(path.join("plugin.toml")) else {
continue;
};
let Ok(plugin) = toml::from_str::<crate::config::WorkflowPlugin>(&content) else {
continue;
};
let description = plugin
.description
.clone()
.unwrap_or_else(|| "Custom workflow plugin".to_string());
found.insert(
name.to_string(),
CustomPlugin {
name: name.to_string(),
description,
plugin,
},
);
}
}
found.into_values().collect()
}
/// Agent-native command/skill directory paths.
/// Returns (base_dir_relative_to_worktree, namespace_subdir), or None for an
/// agent with no native discovery. The namespace is empty for layouts that carry
/// the `agtx-` prefix in the file or directory name instead (Codex, Cursor,
/// Grok, Antigravity, OpenCode).
pub fn agent_native_skill_dir(agent_name: &str) -> Option<(&'static str, &'static str)> {
crate::agent::spec(agent_name).and_then(|s| s.skill_dir)
}
/// Transform SKILL.md frontmatter `name: agtx-plan` to command name `agtx:plan`.
/// Replaces the first hyphen with `:`.
pub fn skill_name_to_command(skill_name: &str) -> String {
if let Some(pos) = skill_name.find('-') {
format!("{}:{}", &skill_name[..pos], &skill_name[pos + 1..])
} else {
skill_name.to_string()
}
}
/// Map internal skill directory name to agent-native command file name,
/// according to the agent's [`SkillLayout`](crate::agent::SkillLayout):
/// - `CommandFile` / `SkillDir`: "agtx-plan" β "plan.md" (the namespace subdir
/// or the skill directory itself carries the prefix)
/// - `GeminiToml`: "agtx-plan" β "plan.toml"
/// - `OpenCodeFlat`: "agtx-plan" β "agtx-plan.md" (flat directory, full name)
pub fn skill_dir_to_filename(skill_dir_name: &str, agent_name: &str) -> String {
let short = || {
skill_dir_name
.strip_prefix("agtx-")
.unwrap_or(skill_dir_name)
};
match crate::agent::spec(agent_name).map(|s| s.skill_layout) {
Some(SkillLayout::GeminiToml) => format!("{}.toml", short()),
Some(SkillLayout::OpenCodeFlat) => format!("{}.md", skill_dir_name),
_ => format!("{}.md", short()),
}
}
/// Transform a canonical plugin command (Claude/Gemini format) for a specific agent.
///
/// Plugin commands in plugin.toml are stored in canonical form: `/namespace:command args`
/// This transforms them for each agent's [`CommandSyntax`](crate::agent::CommandSyntax):
/// - `Colon` (Claude, Gemini): unchanged (`/gsd:plan-phase 1`)
/// - `Hyphen` (OpenCode, Cursor, Grok, Antigravity): colon β hyphen (`/gsd-plan-phase 1`)
/// - `Dollar` (Codex): slash β dollar, colon β hyphen (`$gsd-plan-phase 1`)
/// - `PiSkill` (pi): colon β hyphen, then re-namespaced under `skill:`
/// (`/skill:gsd-plan-phase 1`)
/// - `None` (Copilot, unknown agents): None β callers fall back to a file-path reference
///
/// Only the first colon is rewritten; arguments may legitimately contain more.
pub fn transform_plugin_command(canonical_cmd: &str, agent_name: &str) -> Option<String> {
match crate::agent::spec(agent_name).map(|s| s.command_syntax) {
Some(CommandSyntax::Colon) => Some(canonical_cmd.to_string()),
Some(CommandSyntax::Hyphen) => Some(canonical_cmd.replacen(':', "-", 1)),
Some(CommandSyntax::Dollar) => {
let transformed = canonical_cmd.replacen(':', "-", 1);
Some(match transformed.strip_prefix('/') {
Some(rest) => format!("${}", rest),
None => transformed,
})
}
// pi registers every skill as `/skill:<skill-name>`, and the skill name
// is the hyphenated form the SKILL.md frontmatter carries. So the
// namespace does not survive as a prefix β it is folded into the name.
Some(CommandSyntax::PiSkill) => {
let transformed = canonical_cmd.replacen(':', "-", 1);
Some(match transformed.strip_prefix('/') {
Some(rest) => format!("/skill:{}", rest),
None => transformed,
})
}
Some(CommandSyntax::None) | None => None,
}
}
/// Strip YAML frontmatter from a skill file, returning just the body content.
pub fn strip_frontmatter(content: &str) -> &str {
if content.starts_with("---") {
if let Some(end) = content[3..].find("---") {
let after = &content[3 + end + 3..];
return after.trim_start_matches('\n');
}
}
content
}
/// Convert skill content to Gemini TOML command format.
/// Gemini commands are .toml files with `description` and `prompt` fields.
pub fn skill_to_gemini_toml(description: &str, skill_content: &str) -> String {
let body = strip_frontmatter(skill_content);
// Escape backslashes and triple-quotes for TOML multi-line strings
let escaped = body.replace('\\', "\\\\").replace("\"\"\"", "\\\"\\\"\\\"");
format!(
"description = \"{}\"\n\nprompt = \"\"\"\n{}\n\"\"\"\n",
description.replace('"', "\\\""),
escaped
)
}
/// Bundled plugin configurations: (name, description, plugin.toml content)
/// These are embedded at compile time so the TUI can install them without external files.
pub const BUNDLED_PLUGINS: &[(&str, &str, &str)] = &[
(
"agtx",
"Built-in workflow with skills and prompts",
include_str!("../plugins/agtx/plugin.toml"),
),
(
"agtx-terse",
"Token-efficient workflow - same workflow with compressed output and minimal tokens",
include_str!("../plugins/agtx-terse/plugin.toml"),
),
(
"gsd",
"Get Shit Done - structured spec-driven development",
include_str!("../plugins/gsd/plugin.toml"),
),
(
"spec-kit",
"Spec-Driven Development by GitHub",
include_str!("../plugins/spec-kit/plugin.toml"),
),
(
"openspec",
"OpenSpec - lightweight AI-guided specification framework",
include_str!("../plugins/openspec/plugin.toml"),
),
(
"void",
"Plain agent session - no prompting or skills",
include_str!("../plugins/void/plugin.toml"),
),
(
"bmad",
"BMAD Method - AI-driven agile development",
include_str!("../plugins/bmad/plugin.toml"),
),
(
"superpowers",
"Superpowers - brainstorming, plans, TDD, subagent-driven development",
include_str!("../plugins/superpowers/plugin.toml"),
),
(
"oh-my-claudecode",
"oh-my-claudecode - Multi-agent orchestration",
include_str!("../plugins/oh-my-claudecode/plugin.toml"),
),
(
"agent-skills",
"Agent Skills - production-grade engineering skills for the full spec-to-ship lifecycle",
include_str!("../plugins/agent-skills/plugin.toml"),
),
];
/// Extract the description from YAML frontmatter.
pub fn extract_description(content: &str) -> Option<String> {
if content.starts_with("---") {
if let Some(end) = content[3..].find("---") {
let frontmatter = &content[3..3 + end];
for line in frontmatter.lines() {
if let Some(desc) = line.strip_prefix("description:") {
return Some(desc.trim().to_string());
}
}
}
}
None
}
/// Enumerate built-in skills as agent-native `(command, description)` pairs.
/// Uses compile-time embedded `BUILTIN_SKILLS` β no filesystem access needed.
pub fn enumerate_available_skills(agent_name: &str) -> Vec<(String, String)> {
let mut results = Vec::new();
for (skill_name, skill_content) in BUILTIN_SKILLS {
let canonical = format!("/{}", skill_name_to_command(skill_name));
let command = match transform_plugin_command(&canonical, agent_name) {
Some(cmd) => cmd,
None => canonical,
};
let description =
extract_description(skill_content).unwrap_or_else(|| skill_name.replace('-', " "));
results.push((command, description));
}
results
}
/// Extract description from a markdown file with YAML frontmatter on disk.
fn extract_description_from_file(path: &std::path::Path) -> Option<String> {
let mut buf = vec![0u8; 512];
let mut file = std::fs::File::open(path).ok()?;
let n = std::io::Read::read(&mut file, &mut buf).ok()?;
let content = std::str::from_utf8(&buf[..n]).ok()?;
extract_description(content)
}
/// Extract description from a Gemini TOML command file on disk.
fn extract_description_from_toml(path: &std::path::Path) -> Option<String> {
let mut buf = vec![0u8; 512];
let mut file = std::fs::File::open(path).ok()?;
let n = std::io::Read::read(&mut file, &mut buf).ok()?;
let content = std::str::from_utf8(&buf[..n]).ok()?;
for line in content.lines() {
let trimmed = line.trim();
if let Some(rest) = trimmed.strip_prefix("description") {
let rest = rest.trim_start();
if let Some(rest) = rest.strip_prefix('=') {
let rest = rest.trim();
let rest = rest.trim_start_matches('"').trim_end_matches('"');
if !rest.is_empty() {
return Some(rest.to_string());
}
}
}
}
None
}
/// Scan the active agent's native command directory for available skills.
/// Returns `(command, description)` tuples in agent-native invocation format.
///
/// Driven by the agent's [`SkillLayout`](crate::agent::SkillLayout), so an agent
/// reusing an existing layout needs nothing here.
pub fn scan_agent_skills(
agent_name: &str,
project_path: &std::path::Path,
) -> Vec<(String, String)> {
let Some(spec) = crate::agent::spec(agent_name) else {
return Vec::new();
};
let Some(scan_dir) = spec.skill_scan_dir else {
return Vec::new();
};
let base = project_path.join(scan_dir);
let mut results = match spec.skill_layout {
// Namespaced subdirectories of command files, invoked as `/namespace:name`.
// Gemini's are TOML with a `description` key; the rest are markdown with
// YAML frontmatter.
SkillLayout::CommandFile | SkillLayout::GeminiToml => {
let toml = spec.skill_layout == SkillLayout::GeminiToml;
let ext = if toml { "toml" } else { "md" };
scan_namespaced_commands(&base, ext, toml)
}
// Skill subdirectories each holding a SKILL.md, invoked by directory name.
SkillLayout::SkillDir => {
// The directory name is the skill name; the prefix is how the
// agent's TUI invokes it. pi namespaces every skill under `skill:`,
// so the directory `agtx-plan` is typed as `/skill:agtx-plan`.
let prefix = match spec.command_syntax {
CommandSyntax::Dollar => "$",
CommandSyntax::PiSkill => "/skill:",
_ => "/",
};
scan_skill_dirs(&base, prefix)
}
// Flat directory of command files, invoked as `/name`.
SkillLayout::OpenCodeFlat => scan_flat_commands(&base),
};
results.sort_by(|a, b| a.0.cmp(&b.0));
results
}
/// `{base}/{namespace}/{name}.{ext}` β `/namespace:name`.
fn scan_namespaced_commands(
base: &std::path::Path,
ext: &str,
description_from_toml: bool,
) -> Vec<(String, String)> {
let mut results = Vec::new();
let Ok(entries) = std::fs::read_dir(base) else {
return results;
};
for ns_entry in entries.flatten() {
if !ns_entry.path().is_dir() {
continue;
}
let namespace = ns_entry.file_name().to_string_lossy().to_string();
let Ok(files) = std::fs::read_dir(ns_entry.path()) else {
continue;
};
for file_entry in files.flatten() {
let path = file_entry.path();
if path.extension().and_then(|e| e.to_str()) != Some(ext) {
continue;
}
let Some(stem) = path.file_stem().and_then(|s| s.to_str()) else {
continue;
};
let description = if description_from_toml {
extract_description_from_toml(&path)
} else {
extract_description_from_file(&path)
}
.unwrap_or_else(|| stem.replace('-', " "));
results.push((format!("/{}:{}", namespace, stem), description));
}
}
results
}
/// `{base}/{name}/SKILL.md` β `{prefix}{name}`.
fn scan_skill_dirs(base: &std::path::Path, prefix: &str) -> Vec<(String, String)> {
let mut results = Vec::new();
let Ok(entries) = std::fs::read_dir(base) else {
return results;
};
for dir_entry in entries.flatten() {
if !dir_entry.path().is_dir() {
continue;
}
let dirname = dir_entry.file_name().to_string_lossy().to_string();
let skill_file = dir_entry.path().join("SKILL.md");
if !skill_file.exists() {
continue;
}
let description =
extract_description_from_file(&skill_file).unwrap_or_else(|| dirname.replace('-', " "));
results.push((format!("{}{}", prefix, dirname), description));
}
results
}
/// `{base}/{name}.md` β `/name`. No frontmatter is read: OpenCode commands are
/// deployed with theirs stripped.
fn scan_flat_commands(base: &std::path::Path) -> Vec<(String, String)> {
let mut results = Vec::new();
let Ok(entries) = std::fs::read_dir(base) else {
return results;
};
for file_entry in entries.flatten() {
let path = file_entry.path();
if path.extension().and_then(|e| e.to_str()) != Some("md") {
continue;
}
let Some(stem) = path.file_stem().and_then(|s| s.to_str()) else {
continue;
};
results.push((format!("/{}", stem), stem.replace('-', " ")));
}
results
}
#[cfg(test)]
mod tests {
use super::*;
use std::fs;
use std::path::PathBuf;
fn write_plugin(dir: &std::path::Path, name: &str, body: &str) {
let plugin_dir = dir.join(name);
fs::create_dir_all(&plugin_dir).unwrap();
let content = format!("name = \"{}\"\n{}", name, body);
fs::write(plugin_dir.join("plugin.toml"), content).unwrap();
}
#[test]
fn discovers_custom_plugin_with_description() {
let tmp = tempfile::tempdir().unwrap();
write_plugin(tmp.path(), "my-flow", "description = \"My custom flow\"\n");
let found = discover_custom_plugins_in(&[tmp.path().to_path_buf()]);
assert_eq!(found.len(), 1);
assert_eq!(found[0].name, "my-flow");
assert_eq!(found[0].description, "My custom flow");
}
#[test]
fn falls_back_to_default_description_when_missing() {
let tmp = tempfile::tempdir().unwrap();
write_plugin(tmp.path(), "no-desc", "");
let found = discover_custom_plugins_in(&[tmp.path().to_path_buf()]);
assert_eq!(found.len(), 1);
assert_eq!(found[0].description, "Custom workflow plugin");
}
#[test]
fn skips_names_colliding_with_bundled_plugins() {
let tmp = tempfile::tempdir().unwrap();
write_plugin(tmp.path(), "gsd", "description = \"shadow\"\n");
write_plugin(tmp.path(), "mine", "description = \"mine\"\n");
let found = discover_custom_plugins_in(&[tmp.path().to_path_buf()]);
let names: Vec<&str> = found.iter().map(|p| p.name.as_str()).collect();
assert_eq!(names, vec!["mine"]);
}
#[test]
fn ignores_dirs_without_plugin_toml_and_invalid_names() {
let tmp = tempfile::tempdir().unwrap();
fs::create_dir_all(tmp.path().join("empty-dir")).unwrap();
fs::write(tmp.path().join("loose-file.toml"), "x").unwrap();
write_plugin(tmp.path(), "valid", "description = \"ok\"\n");
let found = discover_custom_plugins_in(&[tmp.path().to_path_buf()]);
let names: Vec<&str> = found.iter().map(|p| p.name.as_str()).collect();
assert_eq!(names, vec!["valid"]);
}
#[test]
fn project_local_shadows_global_by_name() {
let global = tempfile::tempdir().unwrap();
let local = tempfile::tempdir().unwrap();
write_plugin(global.path(), "shared", "description = \"global\"\n");
write_plugin(local.path(), "shared", "description = \"local\"\n");
let dirs: Vec<PathBuf> = vec![global.path().to_path_buf(), local.path().to_path_buf()];
let found = discover_custom_plugins_in(&dirs);
assert_eq!(found.len(), 1);
assert_eq!(found[0].description, "local");
}
#[test]
fn skips_bundled_name_in_global_keeps_local_custom() {
let global = tempfile::tempdir().unwrap();
let local = tempfile::tempdir().unwrap();
write_plugin(global.path(), "gsd", "description = \"shadow\"\n");
write_plugin(local.path(), "mine", "description = \"mine\"\n");
let dirs: Vec<PathBuf> = vec![global.path().to_path_buf(), local.path().to_path_buf()];
let found = discover_custom_plugins_in(&dirs);
let names: Vec<&str> = found.iter().map(|p| p.name.as_str()).collect();
assert_eq!(names, vec!["mine"]);
}
#[test]
fn discovered_plugin_carries_supported_agents_for_wizard_filter() {
let tmp = tempfile::tempdir().unwrap();
write_plugin(
tmp.path(),
"claude-only",
"description = \"c\"\nsupported_agents = [\"claude\"]\n",
);
let found = discover_custom_plugins_in(&[tmp.path().to_path_buf()]);
assert_eq!(found.len(), 1);
assert!(found[0].plugin.supports_agent("claude"));
assert!(!found[0].plugin.supports_agent("codex"));
}
}