Restructure docs and derive prompt identities from paths

Author: TrueNine

cli/src/inputs/input-agentskills-export-fallback.test.ts

@@ -52,14 +52,12 @@ describe('skill input plugin export fallback', () => {
       fs.mkdirSync(srcSkillDir, {recursive: true})
       fs.mkdirSync(distSkillDir, {recursive: true})
       fs.writeFileSync(path.join(srcSkillDir, 'skill.src.mdx'), `export default {
-  name: 'demo',
   description: 'source export description',
 }
 
 Source skill
 `, 'utf8')
       fs.writeFileSync(path.join(distSkillDir, 'skill.mdx'), `export default {
-  name: 'demo',
   description: 'dist export description',
 }
 

cli/src/inputs/input-agentskills.test.ts

@@ -53,9 +53,11 @@ describe('skill input plugin', () => {
       const [skill] = result.skills ?? []
 
       expect(result.skills?.length ?? 0).toBe(1)
+      expect(skill?.skillName).toBe('demo')
       expect(skill?.content).toContain('Skill dist')
       expect(skill?.content).not.toContain('Skill source')
       expect(skill?.content).not.toContain('export const x = 1')
+      expect(skill?.yamlFrontMatter?.name).toBe('demo')
       expect(skill?.yamlFrontMatter?.description).toBe('dist skill')
       expect(skill?.childDocs?.map(childDoc => childDoc.relativePath)).toEqual(['guide.mdx'])
       expect(skill?.childDocs?.[0]?.content).toContain('Guide dist')
@@ -139,7 +141,7 @@ describe('skill input plugin', () => {
       fs.mkdirSync(srcSkillDir, {recursive: true})
       fs.mkdirSync(distSkillDir, {recursive: true})
       fs.writeFileSync(path.join(srcSkillDir, 'skill.src.mdx'), '---\ndescription: src skill\n---\nSkill source', 'utf8')
-      fs.writeFileSync(path.join(distSkillDir, 'skill.mdx'), '---\nname: demo\ndescription: dist skill\nscope: workspace\n---\nSkill dist', 'utf8')
+      fs.writeFileSync(path.join(distSkillDir, 'skill.mdx'), '---\ndescription: dist skill\nscope: workspace\n---\nSkill dist', 'utf8')
 
       const plugin = new SkillInputCapability()
       await expect(plugin.collect(createContext(tempWorkspace, createMockLogger()))).rejects.toThrow('Field "scope" must be "project" or "global"')
@@ -148,4 +150,30 @@ describe('skill input plugin', () => {
       fs.rmSync(tempWorkspace, {recursive: true, force: true})
     }
   })
+
+  it('warns and ignores authored skill name metadata', async () => {
+    const warnings: string[] = []
+    const tempWorkspace = fs.mkdtempSync(path.join(os.tmpdir(), 'tnmsc-skill-input-name-warning-test-'))
+    const srcSkillDir = path.join(tempWorkspace, 'aindex', 'skills', 'demo')
+    const distSkillDir = path.join(tempWorkspace, 'aindex', 'dist', 'skills', 'demo')
+
+    try {
+      fs.mkdirSync(srcSkillDir, {recursive: true})
+      fs.mkdirSync(distSkillDir, {recursive: true})
+      fs.writeFileSync(path.join(srcSkillDir, 'skill.src.mdx'), '---\nname: custom-demo\ndescription: src skill\n---\nSkill source', 'utf8')
+      fs.writeFileSync(path.join(distSkillDir, 'skill.mdx'), '---\nname: custom-demo\ndescription: dist skill\n---\nSkill dist', 'utf8')
+
+      const plugin = new SkillInputCapability()
+      const result = await plugin.collect(createContext(tempWorkspace, createMockLogger(warnings)))
+      const [skill] = result.skills ?? []
+
+      expect(skill?.skillName).toBe('demo')
+      expect(skill?.yamlFrontMatter?.name).toBe('demo')
+      expect(skill?.yamlFrontMatter?.description).toBe('dist skill')
+      expect(warnings).toContain('SKILL_NAME_IGNORED')
+    }
+    finally {
+      fs.rmSync(tempWorkspace, {recursive: true, force: true})
+    }
+  })
 })

cli/src/inputs/input-agentskills.ts

@@ -111,6 +111,35 @@ function mergeDefinedSkillMetadata(
   return merged
 }
 
+function warnIgnoredSkillName(options: {
+  readonly logger: ILogger
+  readonly warnedDerivedNames?: Set<string>
+  readonly sourcePath: string
+  readonly authoredName: string
+  readonly skillName: string
+}): void {
+  const {logger, warnedDerivedNames, sourcePath, authoredName, skillName} = options
+  if (warnedDerivedNames?.has(sourcePath) === true) return
+
+  warnedDerivedNames?.add(sourcePath)
+  logger.warn(buildConfigDiagnostic({
+    code: 'SKILL_NAME_IGNORED',
+    title: 'Skill authored name is ignored',
+    reason: diagnosticLines(
+      `tnmsc ignores the authored skill name "${authoredName}" in favor of the directory-derived name "${skillName}".`
+    ),
+    configPath: sourcePath,
+    exactFix: diagnosticLines(
+      'Remove the `name` field from the skill front matter or exported metadata.',
+      'Rename the skill directory if you need a different skill name.'
+    ),
+    details: {
+      authoredName,
+      derivedName: skillName
+    }
+  }))
+}
+
 const MIME_TYPES: Record<string, string> = { // MIME types for resources
   '.ts': 'text/typescript',
   '.tsx': 'text/typescript',
@@ -557,16 +586,21 @@ async function createSkillPrompt(
   name: string,
   skillDir: string,
   skillAbsoluteDir: string,
+  sourceSkillAbsoluteDir: string,
   ctx: InputCapabilityContext,
   mcpConfig?: SkillMcpConfig,
   childDocs: SkillPrompt['childDocs'] = [],
   resources: SkillPrompt['resources'] = [],
   seriName?: string | string[] | null,
-  compiledMetadata?: Record<string, unknown>
+  compiledMetadata?: Record<string, unknown>,
+  warnedDerivedNames?: Set<string>
 ): Promise<SkillPrompt> {
   const {logger, globalScope, fs} = ctx
 
   const distFilePath = nodePath.join(skillAbsoluteDir, 'skill.mdx')
+  const sourceFilePath = fs.existsSync(nodePath.join(sourceSkillAbsoluteDir, 'skill.src.mdx'))
+    ? nodePath.join(sourceSkillAbsoluteDir, 'skill.src.mdx')
+    : distFilePath
   let rawContent = content
   let parsed: ReturnType<typeof parseMarkdown<SkillYAMLFrontMatter>> | undefined,
     distMetadata: Record<string, unknown> | undefined
@@ -593,6 +627,22 @@ async function createSkillPrompt(
     distMetadata
   ) // Merge fallback export parsing with compiled metadata so empty metadata objects do not mask valid fields
 
+  const authoredNames = new Set<string>()
+  const yamlName = parsed?.yamlFrontMatter?.['name']
+  if (typeof yamlName === 'string' && yamlName.trim().length > 0) authoredNames.add(yamlName)
+  const exportedName = exportMetadata.name
+  if (typeof exportedName === 'string' && exportedName.trim().length > 0) authoredNames.add(exportedName)
+
+  for (const authoredName of authoredNames) {
+    warnIgnoredSkillName({
+      logger,
+      sourcePath: sourceFilePath,
+      authoredName,
+      skillName: name,
+      ...warnedDerivedNames != null && {warnedDerivedNames}
+    })
+  }
+
   const finalDescription = parsed?.yamlFrontMatter?.description ?? exportMetadata?.description
 
   if (finalDescription == null || finalDescription.trim().length === 0) { // Strict validation: description must exist and not be empty
@@ -634,6 +684,7 @@ async function createSkillPrompt(
     content,
     length: content.length,
     filePathKind: FilePathKind.Relative,
+    skillName: name,
     yamlFrontMatter: mergedFrontMatter,
     markdownAst: parsed?.markdownAst,
     markdownContents: parsed?.markdownContents ?? [],
@@ -694,6 +745,7 @@ export class SkillInputCapability extends AbstractInputCapability {
 
     const flatSkills: SkillPrompt[] = []
     const reader = createLocalizedPromptReader(fs, pathModule, logger, globalScope)
+    const warnedDerivedNames = new Set<string>()
     const skillArtifactCache = new Map<string, {
       readonly childDocs: SkillChildDoc[]
       readonly resources: SkillResource[]
@@ -749,12 +801,14 @@ export class SkillInputCapability extends AbstractInputCapability {
             name,
             distSkillDir,
             skillDistDir,
+            pathModule.join(srcSkillDir, name),
             ctx,
             mcpConfig,
             childDocs,
             resources,
             void 0,
-            metadata
+            metadata,
+            warnedDerivedNames
           )
         }
       }

cli/src/inputs/input-subagent.test.ts

@@ -34,14 +34,15 @@ describe('subagent input plugin', () => {
 
       const srcFile = path.join(srcDir, 'demo.src.mdx')
       const distFile = path.join(distDir, 'demo.mdx')
-      fs.writeFileSync(srcFile, '---\nname: demo\ndescription: src\n---\nSubAgent source', 'utf8')
-      fs.writeFileSync(distFile, '---\nname: demo\ndescription: dist\n---\nexport const x = 1\n\nSubAgent dist', 'utf8')
+      fs.writeFileSync(srcFile, '---\ndescription: src\n---\nSubAgent source', 'utf8')
+      fs.writeFileSync(distFile, '---\ndescription: dist\n---\nexport const x = 1\n\nSubAgent dist', 'utf8')
 
       const plugin = new SubAgentInputCapability()
       const result = await plugin.collect(createContext(tempWorkspace))
 
       expect(result.subAgents?.length ?? 0).toBe(1)
       expect(result.subAgents?.[0]?.agentName).toBe('demo')
+      expect(result.subAgents?.[0]?.canonicalName).toBe('demo')
       expect(result.subAgents?.[0]?.content).toContain('SubAgent dist')
       expect(result.subAgents?.[0]?.content).not.toContain('SubAgent source')
       expect(result.subAgents?.[0]?.content).not.toContain('export const x = 1')
@@ -64,8 +65,8 @@ describe('subagent input plugin', () => {
 
       const srcFile = path.join(srcDir, 'boot.src.mdx')
       const distFile = path.join(distDir, 'boot.mdx')
-      fs.writeFileSync(srcFile, '---\nname: boot\ndescription: qa boot src\n---\nSubAgent source', 'utf8')
-      fs.writeFileSync(distFile, '---\nname: boot\ndescription: qa boot dist\n---\nSubAgent dist', 'utf8')
+      fs.writeFileSync(srcFile, '---\ndescription: qa boot src\n---\nSubAgent source', 'utf8')
+      fs.writeFileSync(distFile, '---\ndescription: qa boot dist\n---\nSubAgent dist', 'utf8')
 
       const plugin = new SubAgentInputCapability()
       const result = await plugin.collect(createContext(tempWorkspace))
@@ -74,6 +75,7 @@ describe('subagent input plugin', () => {
       expect(result.subAgents?.length ?? 0).toBe(1)
       expect(subAgent?.agentPrefix).toBe('qa')
       expect(subAgent?.agentName).toBe('boot')
+      expect(subAgent?.canonicalName).toBe('qa-boot')
       expect(subAgent?.content).toContain('SubAgent dist')
       expect(subAgent?.content).not.toContain('SubAgent source')
     }
@@ -94,8 +96,8 @@ describe('subagent input plugin', () => {
 
       const srcFile = path.join(srcDir, 'demo.src.mdx')
       const distFile = path.join(distDir, 'demo.mdx')
-      fs.writeFileSync(srcFile, '---\nname: demo\ndescription: src\n---\nSubAgent source', 'utf8')
-      fs.writeFileSync(distFile, '---\nname: demo\ndescription: dist\n---\nexport const x = 1\n\nSubAgent dist', 'utf8')
+      fs.writeFileSync(srcFile, '---\ndescription: src\n---\nSubAgent source', 'utf8')
+      fs.writeFileSync(distFile, '---\ndescription: dist\n---\nexport const x = 1\n\nSubAgent dist', 'utf8')
 
       const plugin = new SubAgentInputCapability()
       const result = await plugin.collect(createContext(tempWorkspace))
@@ -118,7 +120,7 @@ describe('subagent input plugin', () => {
       fs.mkdirSync(distDir, {recursive: true})
       fs.writeFileSync(
         path.join(distDir, 'demo.mdx'),
-        '---\nname: demo\ndescription: dist only\n---\nDist only subagent',
+        '---\ndescription: dist only\n---\nDist only subagent',
         'utf8'
       )
 
@@ -127,6 +129,7 @@ describe('subagent input plugin', () => {
 
       expect(result.subAgents?.length ?? 0).toBe(1)
       expect(result.subAgents?.[0]?.agentName).toBe('demo')
+      expect(result.subAgents?.[0]?.canonicalName).toBe('demo')
       expect(result.subAgents?.[0]?.content).toContain('Dist only subagent')
       expect(result.subAgents?.[0]?.yamlFrontMatter?.description).toBe('dist only')
     }
@@ -143,7 +146,7 @@ describe('subagent input plugin', () => {
       fs.mkdirSync(srcDir, {recursive: true})
       fs.writeFileSync(
         path.join(srcDir, 'demo.src.mdx'),
-        '---\nname: demo\ndescription: source only\n---\nSource only subagent',
+        '---\ndescription: source only\n---\nSource only subagent',
         'utf8'
       )
 
@@ -163,7 +166,7 @@ describe('subagent input plugin', () => {
       fs.mkdirSync(distDir, {recursive: true})
       fs.writeFileSync(
         path.join(distDir, 'demo.mdx'),
-        '---\nname: demo\ndescription: dist only\nscope: workspace\n---\nDist only subagent',
+        '---\ndescription: dist only\nscope: workspace\n---\nDist only subagent',
         'utf8'
       )
 
@@ -174,4 +177,48 @@ describe('subagent input plugin', () => {
       fs.rmSync(tempWorkspace, {recursive: true, force: true})
     }
   })
+
+  it('warns and ignores authored subagent names', async () => {
+    const tempWorkspace = fs.mkdtempSync(path.join(os.tmpdir(), 'tnmsc-subagent-name-warning-test-'))
+    const warnings: string[] = []
+    const aindexDir = path.join(tempWorkspace, 'aindex')
+    const srcDir = path.join(aindexDir, 'subagents', 'qa')
+    const distDir = path.join(aindexDir, 'dist', 'subagents', 'qa')
+
+    try {
+      fs.mkdirSync(srcDir, {recursive: true})
+      fs.mkdirSync(distDir, {recursive: true})
+
+      fs.writeFileSync(path.join(srcDir, 'boot.src.mdx'), '---\nname: review-helper\ndescription: src\n---\nSubAgent source', 'utf8')
+      fs.writeFileSync(path.join(distDir, 'boot.mdx'), '---\nname: review-helper\ndescription: dist\n---\nSubAgent dist', 'utf8')
+
+      const logger = {
+        trace: () => {},
+        debug: () => {},
+        info: () => {},
+        warn: diagnostic => warnings.push(diagnostic.code),
+        error: () => {},
+        fatal: () => {}
+      }
+
+      const options = mergeConfig({workspaceDir: tempWorkspace})
+      const plugin = new SubAgentInputCapability()
+      const result = await plugin.collect({
+        logger,
+        fs,
+        path,
+        glob,
+        userConfigOptions: options,
+        dependencyContext: {}
+      } as InputCapabilityContext)
+
+      const [subAgent] = result.subAgents ?? []
+      expect(subAgent?.canonicalName).toBe('qa-boot')
+      expect('name' in (subAgent?.yamlFrontMatter ?? {})).toBe(false)
+      expect(warnings).toContain('SUBAGENT_NAME_IGNORED')
+    }
+    finally {
+      fs.rmSync(tempWorkspace, {recursive: true, force: true})
+    }
+  })
 })