Initial public release
Luxe 0.1.0: a coding agent harness for the terminal. See README.md to get started and CHANGELOG.md for releases.
This commit is contained in:
237
crates/luxe-core/src/skills.rs
Normal file
237
crates/luxe-core/src/skills.rs
Normal file
@@ -0,0 +1,237 @@
|
||||
//! Skills — discoverable `SKILL.md` playbooks (shared by the prompt builder and the `skill` tool).
|
||||
//!
|
||||
//! A skill is a directory containing a `SKILL.md` with YAML-ish frontmatter (`name`, `description`)
|
||||
//! and a markdown body of instructions. Discovery surfaces the index in the system prompt; the
|
||||
//! `skill` tool loads a body on demand so heavy instructions only cost context when actually used.
|
||||
//!
|
||||
//! # Where skills live
|
||||
//!
|
||||
//! Luxe's own folders, and the `.agents/skills` folders every other skills-aware agent reads —
|
||||
//! Codex, OpenCode, Pi and Copilot among them, and where `npx skills` installs — so a skill
|
||||
//! installed for one of them is already installed here. Broadest first:
|
||||
//!
|
||||
//! 1. `~/.agents/skills`
|
||||
//! 2. `~/.config/luxe/skills`
|
||||
//! 3. `.agents/skills` from the top of the checkout down to the project
|
||||
//! 4. `.luxe/skills` in the project
|
||||
//!
|
||||
//! Two skills with one name resolve to the later, so a project's skill beats a personal one —
|
||||
//! the rule every client the Agent Skills guide surveyed agrees on — and the shadowed one is logged.
|
||||
//! The same folder reached twice, which is what a symlinked install looks like, is one skill.
|
||||
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
/// A discovered skill: its frontmatter identity plus the path to load its body from.
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub struct SkillDoc {
|
||||
/// Skill name (frontmatter `name`, else the directory name).
|
||||
pub name: String,
|
||||
/// One-line description (frontmatter `description`).
|
||||
pub description: String,
|
||||
/// Path to the `SKILL.md` file.
|
||||
pub path: PathBuf,
|
||||
}
|
||||
|
||||
/// Discover skills across every skill directory, broadest first, one per name.
|
||||
///
|
||||
/// Unreadable or malformed entries are skipped; a missing directory is not an error.
|
||||
pub fn discover(cwd: &Path) -> Vec<SkillDoc> {
|
||||
let mut found = Vec::new();
|
||||
for dir in skill_dirs(cwd) {
|
||||
discover_in(&dir, &mut found);
|
||||
}
|
||||
resolve_names(found)
|
||||
}
|
||||
|
||||
/// Keeps the last skill of each name, where the later of two shadows the earlier.
|
||||
///
|
||||
/// The survivor takes the earlier one's place in the list, so the index reads in the same order
|
||||
/// whichever copy won.
|
||||
fn resolve_names(found: Vec<SkillDoc>) -> Vec<SkillDoc> {
|
||||
let mut skills: Vec<SkillDoc> = Vec::with_capacity(found.len());
|
||||
for skill in found {
|
||||
let Some(earlier) =
|
||||
skills.iter_mut().find(|earlier| earlier.name.eq_ignore_ascii_case(&skill.name))
|
||||
else {
|
||||
skills.push(skill);
|
||||
continue;
|
||||
};
|
||||
if !same_file::is_same_file(&earlier.path, &skill.path).unwrap_or(false) {
|
||||
tracing::info!(
|
||||
skill = %skill.name,
|
||||
used = %skill.path.display(),
|
||||
shadowed = %earlier.path.display(),
|
||||
"two skills share a name; the more specific one is used",
|
||||
);
|
||||
}
|
||||
*earlier = skill;
|
||||
}
|
||||
skills
|
||||
}
|
||||
|
||||
/// Load a skill's full `SKILL.md` body (frontmatter stripped) by name, searching the skill dirs.
|
||||
pub fn load(cwd: &Path, name: &str) -> Option<String> {
|
||||
load_with_path(cwd, name).map(|(body, _)| body)
|
||||
}
|
||||
|
||||
/// Load a skill body along with the file it came from.
|
||||
///
|
||||
/// Callers that bound the body need the path: telling a reader "the rest is in the file" without
|
||||
/// saying which file is a dead end.
|
||||
pub fn load_with_path(cwd: &Path, name: &str) -> Option<(String, PathBuf)> {
|
||||
let doc = discover(cwd).into_iter().find(|s| s.name.eq_ignore_ascii_case(name))?;
|
||||
let content = std::fs::read_to_string(&doc.path).ok()?;
|
||||
let body = crate::instructions::sanitize(strip_frontmatter(&content));
|
||||
Some((body.text.trim().to_string(), doc.path))
|
||||
}
|
||||
|
||||
/// The skill search directories, broadest first. See the module docs for the order.
|
||||
///
|
||||
/// A session's worktree reads `.luxe/skills` from the project it belongs to: `.luxe/` ignores
|
||||
/// itself, so a checkout never carries it. `.agents/skills` is committed like any other file, so
|
||||
/// the worktree's own copy is the one that matches the code it is working on.
|
||||
pub fn skill_dirs(cwd: &Path) -> Vec<PathBuf> {
|
||||
let mut dirs = Vec::new();
|
||||
if let Some(home) = crate::user_dirs::home_dir() {
|
||||
dirs.push(home.join(".agents").join("skills"));
|
||||
}
|
||||
if let Some(luxe) = crate::user_dirs::luxe_config_home() {
|
||||
dirs.push(luxe.join("skills"));
|
||||
}
|
||||
dirs.extend(
|
||||
crate::project::chain_from_top(cwd)
|
||||
.into_iter()
|
||||
.map(|dir| dir.join(".agents").join("skills")),
|
||||
);
|
||||
let project = crate::worktree::project_of(cwd).unwrap_or_else(|| cwd.to_path_buf());
|
||||
dirs.push(project.join(".luxe").join("skills"));
|
||||
dirs
|
||||
}
|
||||
|
||||
/// Skill directories holding a `SKILL.md` of their own, where a skill folder should be.
|
||||
///
|
||||
/// The shape an ordinary `cp -r some-skill ~/.config/luxe/skills/` leaves behind when `skills/`
|
||||
/// did not exist yet: the copy *becomes* `skills/`, so `SKILL.md` lands one level too high and
|
||||
/// nothing is indexed. Discovery cannot guess what was meant, but it can say what it found.
|
||||
pub fn misplaced(cwd: &Path) -> Vec<PathBuf> {
|
||||
skill_dirs(cwd)
|
||||
.into_iter()
|
||||
.map(|dir| dir.join("SKILL.md"))
|
||||
.filter(|path| path.is_file())
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// Scan one directory for `<subdir>/SKILL.md` files.
|
||||
fn discover_in(dir: &Path, skills: &mut Vec<SkillDoc>) {
|
||||
let Ok(entries) = std::fs::read_dir(dir) else { return };
|
||||
for entry in entries.flatten() {
|
||||
let skill_md = entry.path().join("SKILL.md");
|
||||
if skill_md.is_file() {
|
||||
if let Some(doc) = parse(&skill_md) {
|
||||
skills.push(doc);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Parse a `SKILL.md`'s frontmatter into a [`SkillDoc`].
|
||||
///
|
||||
/// The description is indexed into the system prompt of every session that discovers the skill, so
|
||||
/// it goes through the same filter as an instruction file: a skill is a file in a repository, and
|
||||
/// cloning a repository is not consent to run what is hidden in it.
|
||||
fn parse(path: &Path) -> Option<SkillDoc> {
|
||||
let content = std::fs::read_to_string(path).ok()?;
|
||||
let content = crate::instructions::sanitize(&content).text;
|
||||
let (mut name, description) = parse_frontmatter(&content);
|
||||
if name.is_empty() {
|
||||
name = path
|
||||
.parent()
|
||||
.and_then(|p| p.file_name())
|
||||
.map(|n| n.to_string_lossy().into_owned())
|
||||
.unwrap_or_else(|| "skill".to_string());
|
||||
}
|
||||
Some(SkillDoc { name, description, path: path.to_path_buf() })
|
||||
}
|
||||
|
||||
/// Pull `name:` and `description:` out of leading `---`-delimited frontmatter.
|
||||
fn parse_frontmatter(content: &str) -> (String, String) {
|
||||
let Some(front) = frontmatter(content) else { return (String::new(), String::new()) };
|
||||
let mut name = String::new();
|
||||
let mut description = String::new();
|
||||
let lines: Vec<&str> = front.lines().collect();
|
||||
for (index, line) in lines.iter().enumerate() {
|
||||
if let Some(value) = line.strip_prefix("name:") {
|
||||
name = scalar(value.trim(), &lines[index + 1..]);
|
||||
} else if let Some(value) = line.strip_prefix("description:") {
|
||||
description = scalar(value.trim(), &lines[index + 1..]);
|
||||
}
|
||||
}
|
||||
(name, description)
|
||||
}
|
||||
|
||||
/// A frontmatter value, following a YAML block scalar onto the lines beneath it.
|
||||
///
|
||||
/// `description: >` and its relatives are how anyone with more than a few words to say writes this
|
||||
/// — GitHub's own `gh-stack` skill does — and reading only the first line yielded the description
|
||||
/// `>`. That is not a cosmetic loss: the description is the *whole* of what a session knows about a
|
||||
/// skill until something loads its body, so a mangled one is a skill the model can never find a
|
||||
/// reason to open.
|
||||
///
|
||||
/// Folded (`>`) joins its lines with spaces, literal (`|`) keeps the newlines; the chomping
|
||||
/// indicators (`-`, `+`) change trailing whitespace, which nothing here cares about. Anything else
|
||||
/// is a plain scalar and is already complete.
|
||||
fn scalar(first: &str, rest: &[&str]) -> String {
|
||||
let folded = match first {
|
||||
">" | ">-" | ">+" => true,
|
||||
"|" | "|-" | "|+" => false,
|
||||
plain => return unquote(plain),
|
||||
};
|
||||
// The block runs until a line that is not indented — the next key, or the end.
|
||||
let block: Vec<&str> = rest
|
||||
.iter()
|
||||
.take_while(|line| line.trim().is_empty() || line.starts_with([' ', '\t']))
|
||||
.map(|line| line.trim())
|
||||
.collect();
|
||||
let joined = match folded {
|
||||
true => block.join(" "),
|
||||
false => block.join("\n"),
|
||||
};
|
||||
joined.trim().to_string()
|
||||
}
|
||||
|
||||
/// Drop the matching quotes YAML allows around a plain scalar.
|
||||
fn unquote(value: &str) -> String {
|
||||
for quote in ['"', '\''] {
|
||||
if let Some(inner) = value.strip_prefix(quote).and_then(|v| v.strip_suffix(quote)) {
|
||||
return inner.to_string();
|
||||
}
|
||||
}
|
||||
value.to_string()
|
||||
}
|
||||
|
||||
/// The frontmatter block (between the leading `---` fences), if present.
|
||||
fn frontmatter(content: &str) -> Option<&str> {
|
||||
let rest = content.strip_prefix("---\n").or_else(|| content.strip_prefix("---\r\n"))?;
|
||||
let end = rest.find("\n---")?;
|
||||
Some(&rest[..end])
|
||||
}
|
||||
|
||||
/// The body with any leading frontmatter block removed.
|
||||
fn strip_frontmatter(content: &str) -> &str {
|
||||
match frontmatter(content) {
|
||||
Some(front) => {
|
||||
// Skip past the closing fence line after the frontmatter.
|
||||
let after_front = &content[content.find(front).unwrap_or(0) + front.len()..];
|
||||
after_front
|
||||
.find("---")
|
||||
.and_then(|i| {
|
||||
after_front[i + 3..].strip_prefix('\n').or(Some(&after_front[i + 3..]))
|
||||
})
|
||||
.unwrap_or(content)
|
||||
}
|
||||
None => content,
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests;
|
||||
Reference in New Issue
Block a user