docs(plugin): clarify shared bundle contracts

Author: ScriptedAlchemy

src/agents/plugin_bundle.rs

@@ -48,8 +48,8 @@ pub(crate) fn set_mcp_command(raw: &str, bin: &str) -> Result<String> {
     Ok(format!("{}\n", serde_json::to_string_pretty(&mcp)?))
 }
 
-/// One embedded plugin file: `relative` is its deploy path; `contents` is
-/// embedded from the shared `plugin/` tree at compile time.
+/// One embedded plugin file: `relative` is its deploy path; `contents` may come
+/// from a different source path in the shared `plugin/` tree.
 #[derive(Clone, Copy)]
 pub struct PluginFile {
     pub relative: &'static str,
@@ -65,7 +65,7 @@ macro_rules! plugin_file {
     };
 }
 
-// Every file under `plugin/skills/`, embedded recursively by `build.rs`.
+// Every file under `plugin/skills/`, including support files, embedded by build.rs.
 include!(concat!(env!("OUT_DIR"), "/plugin_bundle_generated.rs"));
 
 /// Prefix of the dispatcher skills that Cursor does **not** deploy (they are

src/automation/skill_frontmatter.rs

@@ -1,14 +1,14 @@
 //! Parser for the `SKILL.md` frontmatter subset used by plugin and managed
-//! skills.
+//! skills: fenced `key: value` scalars plus indented block values.
 
 use std::collections::BTreeMap;
 
 use crate::errors::{Result, TraceDecayError};
 
-/// One frontmatter value.
+/// One parsed frontmatter value.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum SkillFrontmatterValue {
-    /// Inline scalar with outer quotes stripped.
+    /// Inline scalar with one level of YAML quotes stripped.
     Scalar(String),
     /// Trimmed block lines under a key with no inline value.
     Block(Vec<String>),
@@ -22,7 +22,7 @@ impl SkillFrontmatterValue {
         }
     }
 
-    /// Returns unquoted `- item` block entries.
+    /// Returns unquoted `- item` entries when every block line is a list item.
     pub fn as_list_items(&self) -> Option<Vec<String>> {
         match self {
             Self::Scalar(_) => None,
@@ -42,7 +42,7 @@ impl SkillFrontmatterValue {
     }
 }
 
-/// Parses the leading `---`-fenced frontmatter of a `SKILL.md` document.
+/// Parses leading `---`-fenced frontmatter, normalizing LF and CRLF input.
 pub fn parse_skill_frontmatter(contents: &str) -> Result<BTreeMap<String, SkillFrontmatterValue>> {
     let mut lines = contents.lines();
     if lines.next().map(str::trim_end) != Some("---") {
@@ -106,7 +106,7 @@ pub fn parse_skill_frontmatter(contents: &str) -> Result<BTreeMap<String, SkillF
     Ok(fields)
 }
 
-/// Strips one level of YAML quoting.
+/// Strips one level of YAML quoting, including YAML `''` single-quote escaping.
 fn unquote_scalar(value: &str) -> String {
     if let Some(inner) = value.strip_prefix('\'').and_then(|v| v.strip_suffix('\'')) {
         inner.replace("''", "'")