bmad-method 6.2.1-next.2 → 6.2.1-next.21

package/tools/cli/installers/lib/core/dependency-resolver.js

@@ -82,11 +82,11 @@ class DependencyResolver {
       // Check if this is a source directory (has 'src' subdirectory)
       const srcDir = path.join(bmadDir, 'src');
       if (await fs.pathExists(srcDir)) {
-        // Source directory structure: src/core or src/bmm
+        // Source directory structure: src/core-skills or src/bmm-skills
         if (module === 'core') {
-          moduleDir = path.join(srcDir, 'core');
+          moduleDir = path.join(srcDir, 'core-skills');
         } else if (module === 'bmm') {
-          moduleDir = path.join(srcDir, 'bmm');
+          moduleDir = path.join(srcDir, 'bmm-skills');
         }
       }
 
@@ -401,8 +401,8 @@ class DependencyResolver {
         const bmadPath = dep.dependency.replace(/^bmad\//, '');
 
         // Try to resolve as if it's in src structure
-        // bmad/core/tasks/foo.md -> src/core/tasks/foo.md
-        // bmad/bmm/tasks/bar.md -> src/bmm/tasks/bar.md (bmm is directly under src/)
+        // bmad/core/tasks/foo.md -> src/core-skills/tasks/foo.md
+        // bmad/bmm/tasks/bar.md -> src/bmm-skills/tasks/bar.md (bmm is directly under src/)
         // bmad/cis/agents/bar.md -> src/modules/cis/agents/bar.md
 
         if (bmadPath.startsWith('core/')) {
@@ -584,11 +584,11 @@ class DependencyResolver {
     const relative = path.relative(bmadDir, filePath);
     const parts = relative.split(path.sep);
 
-    // Handle source directory structure (src/core, src/bmm, or src/modules/xxx)
+    // Handle source directory structure (src/core-skills, src/bmm-skills, or src/modules/xxx)
     if (parts[0] === 'src') {
-      if (parts[1] === 'core') {
+      if (parts[1] === 'core-skills') {
         return 'core';
-      } else if (parts[1] === 'bmm') {
+      } else if (parts[1] === 'bmm-skills') {
         return 'bmm';
       } else if (parts[1] === 'modules' && parts.length > 2) {
         return parts[2];
@@ -631,11 +631,11 @@ class DependencyResolver {
       let moduleBase;
 
       // Check if file is in source directory structure
-      if (file.includes('/src/core/') || file.includes('/src/bmm/')) {
+      if (file.includes('/src/core-skills/') || file.includes('/src/bmm-skills/')) {
         if (module === 'core') {
-          moduleBase = path.join(bmadDir, 'src', 'core');
+          moduleBase = path.join(bmadDir, 'src', 'core-skills');
         } else if (module === 'bmm') {
-          moduleBase = path.join(bmadDir, 'src', 'bmm');
+          moduleBase = path.join(bmadDir, 'src', 'bmm-skills');
         }
       } else {
         moduleBase = module === 'core' ? path.join(bmadDir, 'core') : path.join(bmadDir, 'modules', module);

package/tools/cli/installers/lib/core/installer.js

@@ -1789,8 +1789,8 @@ class Installer {
       .filter((entry) => entry.isDirectory() && entry.name !== '_config' && entry.name !== 'docs' && entry.name !== '_memory')
       .map((entry) => entry.name);
 
-    // Add core module to scan (it's installed at root level as _config, but we check src/core)
-    const coreModulePath = getSourcePath('core');
+    // Add core module to scan (it's installed at root level as _config, but we check src/core-skills)
+    const coreModulePath = getSourcePath('core-skills');
     const modulePaths = new Map();
 
     // Map all module source paths
@@ -2709,7 +2709,7 @@ class Installer {
         // Get source path
         let sourcePath;
         if (moduleId === 'core') {
-          sourcePath = getSourcePath('core');
+          sourcePath = getSourcePath('core-skills');
         } else {
           // First check if it's in the custom cache
           if (customModuleSources.has(moduleId)) {

package/tools/cli/installers/lib/core/manifest-generator.js

@@ -50,6 +50,29 @@ class ManifestGenerator {
     return getInstallToBmadShared(manifest, filename);
   }
 
+  /**
+   * Native SKILL.md entrypoints can be packaged as either skills or agents.
+   * Both need verbatim installation for skill-format IDEs.
+   * @param {string|null} artifactType - Manifest type resolved for SKILL.md
+   * @returns {boolean} True when the directory should be installed verbatim
+   */
+  isNativeSkillDirType(artifactType) {
+    return artifactType === 'skill' || artifactType === 'agent';
+  }
+
+  /**
+   * Check whether a loaded bmad-skill-manifest.yaml declares a native
+   * SKILL.md entrypoint, either as a single-entry manifest or a multi-entry map.
+   * @param {Object|null} manifest - Loaded manifest
+   * @returns {boolean} True when the manifest contains a native skill/agent entrypoint
+   */
+  hasNativeSkillManifest(manifest) {
+    if (!manifest) return false;
+    if (manifest.__single) return this.isNativeSkillDirType(manifest.__single.type);
+
+    return Object.values(manifest).some((entry) => this.isNativeSkillDirType(entry?.type));
+  }
+
   /**
    * Clean text for CSV output by normalizing whitespace.
    * Note: Quote escaping is handled by escapeCsv() at write time.
@@ -146,9 +169,10 @@ class ManifestGenerator {
   }
 
   /**
-   * Recursively walk a module directory tree, collecting skill directories.
-   * A skill directory is one that contains both a bmad-skill-manifest.yaml with
-   * type: skill AND a SKILL.md file with name/description frontmatter.
+   * Recursively walk a module directory tree, collecting native SKILL.md entrypoints.
+   * A native entrypoint directory is one that contains both a
+   * bmad-skill-manifest.yaml with type: skill or type: agent AND a SKILL.md file
+   * with name/description frontmatter.
    * Populates this.skills[] and this.skillClaimedDirs (Set of absolute paths).
    */
   async collectSkills() {
@@ -172,11 +196,11 @@ class ManifestGenerator {
         // Check this directory for skill manifest
         const manifest = await this.loadSkillManifest(dir);
 
-        // Determine if this directory is a skill (type: skill in manifest)
+        // Determine if this directory is a native SKILL.md entrypoint
         const skillFile = 'SKILL.md';
         const artifactType = this.getArtifactType(manifest, skillFile);
 
-        if (artifactType === 'skill' || artifactType === 'agent') {
+        if (this.isNativeSkillDirType(artifactType)) {
           const skillMdPath = path.join(dir, 'SKILL.md');
           const dirName = path.basename(dir);
 
@@ -190,11 +214,12 @@ class ManifestGenerator {
               ? `${this.bmadFolderName}/${moduleName}/${relativePath}/${skillFile}`
               : `${this.bmadFolderName}/${moduleName}/${skillFile}`;
 
-            // Skills derive canonicalId from directory name — never from manifest
-            // (agent-type skills legitimately use canonicalId for agent-manifest mapping, so skip warning)
+            // Native SKILL.md entrypoints derive canonicalId from directory name.
+            // Agent entrypoints may keep canonicalId metadata for compatibility, so
+            // only warn for non-agent SKILL.md directories.
             if (manifest && manifest.__single && manifest.__single.canonicalId && artifactType !== 'agent') {
               console.warn(
-                `Warning: Skill manifest at ${dir}/bmad-skill-manifest.yaml contains canonicalId — this field is ignored for skills (directory name is the canonical ID)`,
+                `Warning: Native entrypoint manifest at ${dir}/bmad-skill-manifest.yaml contains canonicalId — this field is ignored for SKILL.md directories (directory name is the canonical ID)`,
               );
             }
             const canonicalId = dirName;
@@ -224,21 +249,21 @@ class ManifestGenerator {
           }
         }
 
-        // Warn if manifest says type:skill but directory was not claimed
+        // Warn if manifest says this is a native entrypoint but the directory was not claimed
         if (manifest && !this.skillClaimedDirs.has(dir)) {
-          let hasSkillType = false;
+          let hasNativeSkillType = false;
           if (manifest.__single) {
-            hasSkillType = manifest.__single.type === 'skill' || manifest.__single.type === 'agent';
+            hasNativeSkillType = this.isNativeSkillDirType(manifest.__single.type);
           } else {
             for (const key of Object.keys(manifest)) {
-              if (manifest[key]?.type === 'skill' || manifest[key]?.type === 'agent') {
-                hasSkillType = true;
+              if (this.isNativeSkillDirType(manifest[key]?.type)) {
+                hasNativeSkillType = true;
                 break;
               }
             }
           }
-          if (hasSkillType && debug) {
-            console.log(`[DEBUG] collectSkills: dir has type:skill manifest but failed validation: ${dir}`);
+          if (hasNativeSkillType && debug) {
+            console.log(`[DEBUG] collectSkills: dir has native SKILL.md manifest but failed validation: ${dir}`);
           }
         }
 
@@ -1359,7 +1384,8 @@ class ManifestGenerator {
         const hasTasks = await fs.pathExists(path.join(modulePath, 'tasks'));
         const hasTools = await fs.pathExists(path.join(modulePath, 'tools'));
 
-        // Check for skill-only modules: recursive scan for bmad-skill-manifest.yaml with type: skill
+        // Check for native-entrypoint-only modules: recursive scan for
+        // bmad-skill-manifest.yaml with type: skill or type: agent
         let hasSkills = false;
         if (!hasAgents && !hasWorkflows && !hasTasks && !hasTools) {
           hasSkills = await this._hasSkillManifestRecursive(modulePath);
@@ -1378,7 +1404,8 @@ class ManifestGenerator {
   }
 
   /**
-   * Recursively check if a directory tree contains a bmad-skill-manifest.yaml with type: skill.
+   * Recursively check if a directory tree contains a bmad-skill-manifest.yaml that
+   * declares a native SKILL.md entrypoint (type: skill or type: agent).
    * Skips directories starting with . or _.
    * @param {string} dir - Directory to search
    * @returns {boolean} True if a skill manifest is found
@@ -1393,10 +1420,7 @@ class ManifestGenerator {
 
     // Check for manifest in this directory
     const manifest = await this.loadSkillManifest(dir);
-    if (manifest) {
-      const type = this.getArtifactType(manifest, 'workflow.md');
-      if (type === 'skill') return true;
-    }
+    if (this.hasNativeSkillManifest(manifest)) return true;
 
     // Recurse into subdirectories
     for (const entry of entries) {

package/tools/cli/installers/lib/core/manifest.js

@@ -764,10 +764,10 @@ class Manifest {
     const configs = {};
 
     for (const moduleName of modules) {
-      // Handle core module differently - it's in src/core not src/modules/core
+      // Handle core module differently - it's in src/core-skills not src/modules/core
       const configPath =
         moduleName === 'core'
-          ? path.join(process.cwd(), 'src', 'core', 'config.yaml')
+          ? path.join(process.cwd(), 'src', 'core-skills', 'config.yaml')
           : path.join(process.cwd(), 'src', 'modules', moduleName, 'config.yaml');
 
       try {

package/tools/cli/installers/lib/ide/_config-driven.js

@@ -630,7 +630,7 @@ LOAD and execute from: {project-root}/{{bmadFolderName}}/{{path}}
   }
 
   /**
-   * Install verbatim skill directories (type: skill entries from skill-manifest.csv).
+   * Install verbatim native SKILL.md directories from skill-manifest.csv.
    * Copies the entire source directory as-is into the IDE skill directory.
    * The source SKILL.md is used directly — no frontmatter transformation or file generation.
    * @param {string} projectDir - Project directory

package/tools/cli/installers/lib/ide/shared/workflow-command-generator.js

@@ -146,13 +146,13 @@ When running any workflow:
   transformWorkflowPath(workflowPath) {
     let transformed = workflowPath;
 
-    if (workflowPath.includes('/src/bmm/')) {
-      const match = workflowPath.match(/\/src\/bmm\/(.+)/);
+    if (workflowPath.includes('/src/bmm-skills/')) {
+      const match = workflowPath.match(/\/src\/bmm-skills\/(.+)/);
       if (match) {
         transformed = `{project-root}/${this.bmadFolderName}/bmm/${match[1]}`;
       }
-    } else if (workflowPath.includes('/src/core/')) {
-      const match = workflowPath.match(/\/src\/core\/(.+)/);
+    } else if (workflowPath.includes('/src/core-skills/')) {
+      const match = workflowPath.match(/\/src\/core-skills\/(.+)/);
       if (match) {
         transformed = `{project-root}/${this.bmadFolderName}/core/${match[1]}`;
       }

package/tools/cli/installers/lib/modules/manager.js

@@ -187,7 +187,7 @@ class ModuleManager {
 
   /**
    * List all available modules (excluding core which is always installed)
-   * bmm is the only built-in module, directly under src/bmm
+   * bmm is the only built-in module, directly under src/bmm-skills
    * All other modules come from external-official-modules.yaml
    * @returns {Object} Object with modules array and customModules array
    */
@@ -195,10 +195,10 @@ class ModuleManager {
     const modules = [];
     const customModules = [];
 
-    // Add built-in bmm module (directly under src/bmm)
-    const bmmPath = getSourcePath('bmm');
+    // Add built-in bmm module (directly under src/bmm-skills)
+    const bmmPath = getSourcePath('bmm-skills');
     if (await fs.pathExists(bmmPath)) {
-      const bmmInfo = await this.getModuleInfo(bmmPath, 'bmm', 'src/bmm');
+      const bmmInfo = await this.getModuleInfo(bmmPath, 'bmm', 'src/bmm-skills');
       if (bmmInfo) {
         modules.push(bmmInfo);
       }
@@ -251,7 +251,8 @@ class ModuleManager {
     }
 
     // Mark as custom if it's using custom.yaml OR if it's outside src/bmm or src/core
-    const isCustomSource = sourceDescription !== 'src/bmm' && sourceDescription !== 'src/core' && sourceDescription !== 'src/modules';
+    const isCustomSource =
+      sourceDescription !== 'src/bmm-skills' && sourceDescription !== 'src/core-skills' && sourceDescription !== 'src/modules';
     const moduleInfo = {
       id: defaultName,
       path: modulePath,
@@ -300,9 +301,9 @@ class ModuleManager {
       return this.customModulePaths.get(moduleCode);
     }
 
-    // Check for built-in bmm module (directly under src/bmm)
+    // Check for built-in bmm module (directly under src/bmm-skills)
     if (moduleCode === 'bmm') {
-      const bmmPath = getSourcePath('bmm');
+      const bmmPath = getSourcePath('bmm-skills');
       if (await fs.pathExists(bmmPath)) {
         return bmmPath;
       }
@@ -1141,10 +1142,10 @@ class ModuleManager {
     const projectRoot = path.dirname(bmadDir);
     const emptyResult = { createdDirs: [], movedDirs: [], createdWdsFolders: [] };
 
-    // Special handling for core module - it's in src/core not src/modules
+    // Special handling for core module - it's in src/core-skills not src/modules
     let sourcePath;
     if (moduleName === 'core') {
-      sourcePath = getSourcePath('core');
+      sourcePath = getSourcePath('core-skills');
     } else {
       sourcePath = await this.findModuleSource(moduleName, { silent: true });
       if (!sourcePath) {

package/tools/cli/lib/project-root.js

@@ -16,7 +16,7 @@ function findProjectRoot(startPath = __dirname) {
       try {
         const pkg = fs.readJsonSync(packagePath);
         // Check if this is the BMAD project
-        if (pkg.name === 'bmad-method' || fs.existsSync(path.join(currentPath, 'src', 'core'))) {
+        if (pkg.name === 'bmad-method' || fs.existsSync(path.join(currentPath, 'src', 'core-skills'))) {
           return currentPath;
         }
       } catch {
@@ -24,8 +24,8 @@ function findProjectRoot(startPath = __dirname) {
       }
     }
 
-    // Also check for src/core as a marker
-    if (fs.existsSync(path.join(currentPath, 'src', 'core', 'agents'))) {
+    // Also check for src/core-skills as a marker
+    if (fs.existsSync(path.join(currentPath, 'src', 'core-skills', 'agents'))) {
       return currentPath;
     }
 
@@ -61,10 +61,10 @@ function getSourcePath(...segments) {
  */
 function getModulePath(moduleName, ...segments) {
   if (moduleName === 'core') {
-    return getSourcePath('core', ...segments);
+    return getSourcePath('core-skills', ...segments);
   }
   if (moduleName === 'bmm') {
-    return getSourcePath('bmm', ...segments);
+    return getSourcePath('bmm-skills', ...segments);
   }
   return getSourcePath('modules', moduleName, ...segments);
 }

package/tools/cli/lib/yaml-xml-builder.js

@@ -495,7 +495,7 @@ class YamlXmlBuilder {
 
     // Extract module from path (e.g., /path/to/modules/bmm/agents/pm.yaml -> bmm)
     // or /path/to/bmad/bmm/agents/pm.yaml -> bmm
-    // or /path/to/src/bmm/agents/pm.yaml -> bmm
+    // or /path/to/src/bmm-skills/agents/pm.yaml -> bmm
     let module = 'core'; // default to core
     const pathParts = agentYamlPath.split(path.sep);
 
@@ -515,10 +515,12 @@ class YamlXmlBuilder {
         module = potentialModule;
       }
     } else if (srcIndex !== -1 && pathParts[srcIndex + 1]) {
-      // Path contains /src/{module}/ (bmm and core are directly under src/)
+      // Path contains /src/{module}/ (bmm-skills and core-skills are directly under src/)
       const potentialModule = pathParts[srcIndex + 1];
-      if (potentialModule === 'bmm' || potentialModule === 'core') {
-        module = potentialModule;
+      if (potentialModule === 'bmm-skills') {
+        module = 'bmm';
+      } else if (potentialModule === 'core-skills') {
+        module = 'core';
       }
     }
 

package/tools/skill-validator.md

@@ -2,14 +2,27 @@
 
 An LLM-readable validation prompt for skills following the Agent Skills open standard.
 
+## First Pass — Deterministic Checks
+
+Before running inference-based validation, run the deterministic validator:
+
+```bash
+node tools/validate-skills.js --json path/to/skill-dir
+```
+
+This checks 14 rules deterministically: SKILL-01, SKILL-02, SKILL-03, SKILL-04, SKILL-05, SKILL-06, SKILL-07, WF-01, WF-02, PATH-02, STEP-01, STEP-06, STEP-07, SEQ-02.
+
+Review its JSON output. For any rule that produced **zero findings** in the first pass, **skip it** during inference-based validation below — it has already been verified. If a rule produced any findings, the inference validator should still review that rule (some rules like SKILL-04 and SKILL-06 have sub-checks that benefit from judgment). Focus your inference effort on the remaining rules that require judgment (PATH-01, PATH-03, PATH-04, PATH-05, WF-03, STEP-02, STEP-03, STEP-04, STEP-05, SEQ-01, REF-01, REF-02, REF-03).
+
 ## How to Use
 
 1. You are given a **skill directory path** to validate.
-2. Read every file in the skill directory recursively.
-3. Apply every rule in the catalog below to every applicable file.
-4. Produce a findings report using the report template at the end.
+2. Run the deterministic first pass (see above) and note which rules passed.
+3. Read every file in the skill directory recursively.
+4. Apply every rule in the catalog below to every applicable file, **skipping rules that passed the deterministic first pass**.
+5. Produce a findings report using the report template at the end, including any deterministic findings from the first pass.
 
-If no findings are generated, the skill passes validation.
+If no findings are generated (from either pass), the skill passes validation.
 
 ---
 
@@ -55,9 +68,9 @@ If no findings are generated, the skill passes validation.
 
 - **Severity:** HIGH
 - **Applies to:** `SKILL.md`
-- **Rule:** The `name` value must use only lowercase letters, numbers, and hyphens. Max 64 characters. Must not contain "anthropic" or "claude".
-- **Detection:** Regex test: `^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$`. String search for forbidden substrings.
-- **Fix:** Rename to comply with the format.
+- **Rule:** The `name` value must start with `bmad-`, use only lowercase letters, numbers, and single hyphens between segments.
+- **Detection:** Regex test: `^bmad-[a-z0-9]+(-[a-z0-9]+)*$`.
+- **Fix:** Rename to comply with the format (e.g., `bmad-my-skill`).
 
 ### SKILL-05 — `name` Must Match Directory Name
 
@@ -75,23 +88,33 @@ If no findings are generated, the skill passes validation.
 - **Detection:** Check length. Look for trigger phrases like "Use when" or "Use if" — their absence suggests the description only says _what_ but not _when_.
 - **Fix:** Append a "Use when..." clause to the description.
 
+### SKILL-07 — SKILL.md Must Have Body Content
+
+- **Severity:** HIGH
+- **Applies to:** `SKILL.md`
+- **Rule:** SKILL.md must have non-empty markdown body content after the frontmatter. The body provides L2 instructions — a SKILL.md with only frontmatter is incomplete.
+- **Detection:** Extract content after the closing `---` frontmatter delimiter and check it is non-empty after trimming whitespace.
+- **Fix:** Add markdown body with skill instructions after the closing `---`.
+
 ---
 
-### WF-01 — workflow.md Must NOT Have `name` in Frontmatter
+### WF-01 — Only SKILL.md May Have `name` in Frontmatter
 
 - **Severity:** HIGH
-- **Applies to:** `workflow.md` (if it exists)
-- **Rule:** The `name` field belongs only in `SKILL.md`. If `workflow.md` has YAML frontmatter, it must not contain `name:`.
-- **Detection:** Parse frontmatter and check for `name:` key.
-- **Fix:** Remove the `name:` line from workflow.md frontmatter.
+- **Applies to:** all `.md` files except `SKILL.md`
+- **Rule:** The `name` field belongs only in `SKILL.md`. No other markdown file in the skill directory may have `name:` in its frontmatter.
+- **Detection:** Parse frontmatter of every non-SKILL.md markdown file and check for `name:` key.
+- **Fix:** Remove the `name:` line from the file's frontmatter.
+- **Exception:** `bmad-agent-tech-writer` — has sub-skill files with intentional `name` fields (to be revisited).
 
-### WF-02 — workflow.md Must NOT Have `description` in Frontmatter
+### WF-02 — Only SKILL.md May Have `description` in Frontmatter
 
 - **Severity:** HIGH
-- **Applies to:** `workflow.md` (if it exists)
-- **Rule:** The `description` field belongs only in `SKILL.md`. If `workflow.md` has YAML frontmatter, it must not contain `description:`.
-- **Detection:** Parse frontmatter and check for `description:` key.
-- **Fix:** Remove the `description:` line from workflow.md frontmatter.
+- **Applies to:** all `.md` files except `SKILL.md`
+- **Rule:** The `description` field belongs only in `SKILL.md`. No other markdown file in the skill directory may have `description:` in its frontmatter.
+- **Detection:** Parse frontmatter of every non-SKILL.md markdown file and check for `description:` key.
+- **Fix:** Remove the `description:` line from the file's frontmatter.
+- **Exception:** `bmad-agent-tech-writer` — has sub-skill files with intentional `description` fields (to be revisited).
 
 ### WF-03 — workflow.md Frontmatter Variables Must Be Config or Runtime Only
 
@@ -103,6 +126,7 @@ If no findings are generated, the skill passes validation.
   - A legitimate external path expression (must not violate PATH-05 — no paths into another skill's directory)
 
   It must NOT be a path to a file within the skill directory (see PATH-04), nor a path into another skill's directory (see PATH-05).
+
 - **Detection:** For each frontmatter variable, check if its value resolves to a file inside the skill (e.g., starts with `./`, `{installed_path}`, or is a bare relative path to a sibling file). If so, it is an intra-skill path variable. Also check if the value is a path into another skill's directory — if so, it violates PATH-05 and is not a legitimate external path.
 - **Fix:** Remove the variable. Use a hardcoded relative path inline where the file is referenced.
 
@@ -294,11 +318,11 @@ When reporting findings, use this format:
 ## Summary
 
 | Severity | Count |
-|----------|-------|
-| CRITICAL | N |
-| HIGH     | N |
-| MEDIUM   | N |
-| LOW      | N |
+| -------- | ----- |
+| CRITICAL | N     |
+| HIGH     | N     |
+| MEDIUM   | N     |
+| LOW      | N     |
 
 ## Findings
 
@@ -329,28 +353,34 @@ Quick-reference for the Agent Skills open standard.
 For the full standard, see: [Agent Skills specification](https://agentskills.io/specification)
 
 ### Structure
+
 - Every skill is a directory with `SKILL.md` as the required entrypoint
 - YAML frontmatter between `---` markers provides metadata; markdown body provides instructions
 - Supporting files (scripts, templates, references) live alongside SKILL.md
 
 ### Path resolution
+
 - Relative file references resolve from the directory of the file that contains the reference, not from the skill root
 - Example: from `branch-a/deep/next.md`, `./deeper/final.md` resolves to `branch-a/deep/deeper/final.md`
 - Example: from `branch-a/deep/next.md`, `./branch-b/alt/leaf.md` incorrectly resolves to `branch-a/deep/branch-b/alt/leaf.md`
 
 ### Frontmatter fields (standard)
+
 - `name`: lowercase letters, numbers, hyphens only; max 64 chars; no "anthropic" or "claude"
 - `description`: required, max 1024 chars; should state what the skill does AND when to use it
 
 ### Progressive disclosure — three loading levels
+
 - **L1 Metadata** (~100 tokens): `name` + `description` loaded at startup into system prompt
 - **L2 Instructions** (<5k tokens): SKILL.md body loaded only when skill is triggered
 - **L3 Resources** (unlimited): additional files + scripts loaded/executed on demand; script output enters context, script code does not
 
 ### Key design principle
+
 - Skills are filesystem-based directories, not API payloads — Claude reads them via bash/file tools
 - Keep SKILL.md focused; offload detailed reference to separate files
 
 ### Practical tips
+
 - Keep SKILL.md under 500 lines
 - `description` drives auto-discovery — use keywords users would naturally say