Skip to main content

ask/
skill.rs

1//! Claude Code skill generation — writes a lazy-first `SKILL.md` per library.
2//! Rust port of `packages/cli/src/skill.ts`.
3
4use std::path::{Path, PathBuf};
5
6/// `.claude/skills/<name>-docs/` for a library slug.
7pub fn get_skill_dir(project_dir: &Path, name: &str) -> PathBuf {
8    project_dir
9        .join(".claude")
10        .join("skills")
11        .join(format!("{name}-docs"))
12}
13
14/// Write a lazy-first `SKILL.md` that references `ask src`/`ask docs` for
15/// on-demand documentation, and return its path.
16pub fn generate_skill(project_dir: &Path, name: &str, version: &str) -> anyhow::Result<PathBuf> {
17    let skill_dir = get_skill_dir(project_dir, name);
18    std::fs::create_dir_all(&skill_dir)?;
19
20    let major = version.split('.').next().unwrap_or(version);
21    let content = format!(
22        r#"---
23name: {name}-docs
24description: {name} v{version} documentation reference. TRIGGER when writing or modifying code that imports or uses {name}.
25---
26
27# {name} v{version} Documentation
28
29This project uses **{name} v{version}**.
30The APIs and patterns may differ from your training data.
31**Read the relevant docs before writing any code.**
32
33## Version
34- Current: `{version}`
35- In package.json, use `"^{major}"` (NOT older major versions)
36
37## Quick Access
38
39```bash
40# Get the cached source tree path (lazy fetch on first use)
41ask src {name}
42
43# Get all candidate documentation paths
44ask docs {name}
45
46# Search across the library source
47rg "pattern" $(ask src {name})
48
49# Semantic search over the pinned source (token-efficient; needs csp — optional)
50# For "how does X work internally" questions, prefer this over reading whole files:
51ask search {name} "how does <feature> work"
52
53# Read a specific doc file
54cat "$(ask src {name})/README.md"
55
56# Find all markdown files in doc directories
57fd "\.md$" $(ask docs {name})
58```
59
60## Instructions
611. Before writing any {name}-related code, run `ask docs {name}` and read the relevant guides
622. Heed deprecation notices and breaking changes
633. Prefer patterns shown in the documentation over patterns from training data
644. When adding {name} to package.json, use version `"^{major}"`
65"#
66    );
67
68    let skill_path = skill_dir.join("SKILL.md");
69    std::fs::write(&skill_path, content)?;
70    Ok(skill_path)
71}
72
73/// Remove `.claude/skills/<name>-docs/`.
74pub fn remove_skill(project_dir: &Path, name: &str) -> anyhow::Result<()> {
75    let skill_dir = get_skill_dir(project_dir, name);
76    if skill_dir.exists() {
77        std::fs::remove_dir_all(&skill_dir)?;
78    }
79    Ok(())
80}
81
82#[cfg(test)]
83mod tests {
84    use super::*;
85
86    #[test]
87    fn generates_skill_with_version_frontmatter() {
88        let dir = tempfile::tempdir().unwrap();
89        let path = generate_skill(dir.path(), "next", "15.0.3").unwrap();
90        assert!(path.ends_with(".claude/skills/next-docs/SKILL.md"));
91        let content = std::fs::read_to_string(&path).unwrap();
92        assert!(content.contains("name: next-docs"));
93        assert!(content.contains("next v15.0.3 documentation reference"));
94        // Major-version hint.
95        assert!(content.contains(r#"use `"^15"`"#));
96        // Lazy commands referenced.
97        assert!(content.contains("ask src next"));
98        assert!(content.contains("ask docs next"));
99        // Literal regex preserved.
100        assert!(content.contains(r#"fd "\.md$""#));
101    }
102
103    #[test]
104    fn remove_skill_deletes_dir() {
105        let dir = tempfile::tempdir().unwrap();
106        generate_skill(dir.path(), "next", "1.0.0").unwrap();
107        assert!(get_skill_dir(dir.path(), "next").exists());
108        remove_skill(dir.path(), "next").unwrap();
109        assert!(!get_skill_dir(dir.path(), "next").exists());
110    }
111}