feat(skills): normalize skill discovery contract across runtimes (#2261)
This commit is contained in:
TÂCHES
@@ -1590,75 +1590,207 @@ function cmdAgentSkills(cwd, agentType, raw) {
|
||||
/**
|
||||
* Generate a skill manifest from a skills directory.
|
||||
*
|
||||
* Scans the given skills directory for subdirectories containing SKILL.md,
|
||||
* extracts frontmatter (name, description) and trigger conditions from the
|
||||
* body text, and returns an array of skill descriptors.
|
||||
* Scans the canonical skill discovery roots and returns a normalized
|
||||
* inventory object with discovered skills, root metadata, and installation
|
||||
* summary flags. A legacy `skillsDir` override is still accepted for focused
|
||||
* scans, but the default mode is multi-root discovery.
|
||||
*
|
||||
* @param {string} skillsDir - Absolute path to the skills directory
|
||||
* @returns {Array<{name: string, description: string, triggers: string[], path: string}>}
|
||||
* @param {string} cwd - Project root directory
|
||||
* @param {string|null} [skillsDir] - Optional absolute path to a specific skills directory
|
||||
* @returns {{
|
||||
* skills: Array<{name: string, description: string, triggers: string[], path: string, file_path: string, root: string, scope: string, installed: boolean, deprecated: boolean}>,
|
||||
* roots: Array<{root: string, path: string, scope: string, present: boolean, skill_count?: number, command_count?: number, deprecated?: boolean}>,
|
||||
* installation: { gsd_skills_installed: boolean, legacy_claude_commands_installed: boolean },
|
||||
* counts: { skills: number, roots: number }
|
||||
* }}
|
||||
*/
|
||||
function buildSkillManifest(skillsDir) {
|
||||
function buildSkillManifest(cwd, skillsDir = null) {
|
||||
const { extractFrontmatter } = require('./frontmatter.cjs');
|
||||
const os = require('os');
|
||||
|
||||
if (!fs.existsSync(skillsDir)) return [];
|
||||
const canonicalRoots = skillsDir ? [{
|
||||
root: path.resolve(skillsDir),
|
||||
path: path.resolve(skillsDir),
|
||||
scope: 'custom',
|
||||
present: fs.existsSync(skillsDir),
|
||||
kind: 'skills',
|
||||
}] : [
|
||||
{
|
||||
root: '.claude/skills',
|
||||
path: path.join(cwd, '.claude', 'skills'),
|
||||
scope: 'project',
|
||||
kind: 'skills',
|
||||
},
|
||||
{
|
||||
root: '.agents/skills',
|
||||
path: path.join(cwd, '.agents', 'skills'),
|
||||
scope: 'project',
|
||||
kind: 'skills',
|
||||
},
|
||||
{
|
||||
root: '.cursor/skills',
|
||||
path: path.join(cwd, '.cursor', 'skills'),
|
||||
scope: 'project',
|
||||
kind: 'skills',
|
||||
},
|
||||
{
|
||||
root: '.github/skills',
|
||||
path: path.join(cwd, '.github', 'skills'),
|
||||
scope: 'project',
|
||||
kind: 'skills',
|
||||
},
|
||||
{
|
||||
root: '.codex/skills',
|
||||
path: path.join(cwd, '.codex', 'skills'),
|
||||
scope: 'project',
|
||||
kind: 'skills',
|
||||
},
|
||||
{
|
||||
root: '~/.claude/skills',
|
||||
path: path.join(os.homedir(), '.claude', 'skills'),
|
||||
scope: 'global',
|
||||
kind: 'skills',
|
||||
},
|
||||
{
|
||||
root: '~/.codex/skills',
|
||||
path: path.join(os.homedir(), '.codex', 'skills'),
|
||||
scope: 'global',
|
||||
kind: 'skills',
|
||||
},
|
||||
{
|
||||
root: '~/.claude/get-shit-done/skills',
|
||||
path: path.join(os.homedir(), '.claude', 'get-shit-done', 'skills'),
|
||||
scope: 'import-only',
|
||||
kind: 'skills',
|
||||
deprecated: true,
|
||||
},
|
||||
{
|
||||
root: '~/.claude/commands/gsd',
|
||||
path: path.join(os.homedir(), '.claude', 'commands', 'gsd'),
|
||||
scope: 'legacy-commands',
|
||||
kind: 'commands',
|
||||
deprecated: true,
|
||||
},
|
||||
];
|
||||
|
||||
let entries;
|
||||
try {
|
||||
entries = fs.readdirSync(skillsDir, { withFileTypes: true });
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
const skills = [];
|
||||
const roots = [];
|
||||
let legacyClaudeCommandsInstalled = false;
|
||||
for (const rootInfo of canonicalRoots) {
|
||||
const rootPath = rootInfo.path;
|
||||
const rootSummary = {
|
||||
root: rootInfo.root,
|
||||
path: rootPath,
|
||||
scope: rootInfo.scope,
|
||||
present: fs.existsSync(rootPath),
|
||||
deprecated: !!rootInfo.deprecated,
|
||||
};
|
||||
|
||||
const manifest = [];
|
||||
for (const entry of entries) {
|
||||
if (!entry.isDirectory()) continue;
|
||||
|
||||
const skillMdPath = path.join(skillsDir, entry.name, 'SKILL.md');
|
||||
if (!fs.existsSync(skillMdPath)) continue;
|
||||
|
||||
let content;
|
||||
try {
|
||||
content = fs.readFileSync(skillMdPath, 'utf-8');
|
||||
} catch {
|
||||
if (!rootSummary.present) {
|
||||
roots.push(rootSummary);
|
||||
continue;
|
||||
}
|
||||
|
||||
const frontmatter = extractFrontmatter(content);
|
||||
const name = frontmatter.name || entry.name;
|
||||
const description = frontmatter.description || '';
|
||||
|
||||
// Extract trigger lines from body text (after frontmatter)
|
||||
const triggers = [];
|
||||
const bodyMatch = content.match(/^---[\s\S]*?---\s*\n([\s\S]*)$/);
|
||||
if (bodyMatch) {
|
||||
const body = bodyMatch[1];
|
||||
const triggerLines = body.match(/^TRIGGER\s+when:\s*(.+)$/gmi);
|
||||
if (triggerLines) {
|
||||
for (const line of triggerLines) {
|
||||
const m = line.match(/^TRIGGER\s+when:\s*(.+)$/i);
|
||||
if (m) triggers.push(m[1].trim());
|
||||
}
|
||||
if (rootInfo.kind === 'commands') {
|
||||
let entries = [];
|
||||
try {
|
||||
entries = fs.readdirSync(rootPath, { withFileTypes: true });
|
||||
} catch {
|
||||
roots.push(rootSummary);
|
||||
continue;
|
||||
}
|
||||
|
||||
const commandFiles = entries.filter(entry => entry.isFile() && entry.name.endsWith('.md'));
|
||||
rootSummary.command_count = commandFiles.length;
|
||||
if (rootSummary.command_count > 0) legacyClaudeCommandsInstalled = true;
|
||||
roots.push(rootSummary);
|
||||
continue;
|
||||
}
|
||||
|
||||
manifest.push({
|
||||
name,
|
||||
description,
|
||||
triggers,
|
||||
path: entry.name,
|
||||
});
|
||||
let entries;
|
||||
try {
|
||||
entries = fs.readdirSync(rootPath, { withFileTypes: true });
|
||||
} catch {
|
||||
roots.push(rootSummary);
|
||||
continue;
|
||||
}
|
||||
|
||||
let skillCount = 0;
|
||||
for (const entry of entries) {
|
||||
if (!entry.isDirectory()) continue;
|
||||
|
||||
const skillMdPath = path.join(rootPath, entry.name, 'SKILL.md');
|
||||
if (!fs.existsSync(skillMdPath)) continue;
|
||||
|
||||
let content;
|
||||
try {
|
||||
content = fs.readFileSync(skillMdPath, 'utf-8');
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
|
||||
const frontmatter = extractFrontmatter(content);
|
||||
const name = frontmatter.name || entry.name;
|
||||
const description = frontmatter.description || '';
|
||||
|
||||
// Extract trigger lines from body text (after frontmatter)
|
||||
const triggers = [];
|
||||
const bodyMatch = content.match(/^---[\s\S]*?---\s*\n([\s\S]*)$/);
|
||||
if (bodyMatch) {
|
||||
const body = bodyMatch[1];
|
||||
const triggerLines = body.match(/^TRIGGER\s+when:\s*(.+)$/gmi);
|
||||
if (triggerLines) {
|
||||
for (const line of triggerLines) {
|
||||
const m = line.match(/^TRIGGER\s+when:\s*(.+)$/i);
|
||||
if (m) triggers.push(m[1].trim());
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
skills.push({
|
||||
name,
|
||||
description,
|
||||
triggers,
|
||||
path: entry.name,
|
||||
file_path: `${entry.name}/SKILL.md`,
|
||||
root: rootInfo.root,
|
||||
scope: rootInfo.scope,
|
||||
installed: rootInfo.scope !== 'import-only',
|
||||
deprecated: !!rootInfo.deprecated,
|
||||
});
|
||||
skillCount++;
|
||||
}
|
||||
|
||||
rootSummary.skill_count = skillCount;
|
||||
roots.push(rootSummary);
|
||||
}
|
||||
|
||||
// Sort by name for deterministic output
|
||||
manifest.sort((a, b) => a.name.localeCompare(b.name));
|
||||
return manifest;
|
||||
skills.sort((a, b) => {
|
||||
const rootCmp = a.root.localeCompare(b.root);
|
||||
return rootCmp !== 0 ? rootCmp : a.name.localeCompare(b.name);
|
||||
});
|
||||
|
||||
const gsdSkillsInstalled = skills.some(skill => skill.name.startsWith('gsd-'));
|
||||
|
||||
return {
|
||||
skills,
|
||||
roots,
|
||||
installation: {
|
||||
gsd_skills_installed: gsdSkillsInstalled,
|
||||
legacy_claude_commands_installed: legacyClaudeCommandsInstalled,
|
||||
},
|
||||
counts: {
|
||||
skills: skills.length,
|
||||
roots: roots.length,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Command: generate skill manifest JSON.
|
||||
*
|
||||
* Options:
|
||||
* --skills-dir <path> Path to skills directory (required)
|
||||
* --skills-dir <path> Optional absolute path to a single skills directory
|
||||
* --write Also write to .planning/skill-manifest.json
|
||||
*/
|
||||
function cmdSkillManifest(cwd, args, raw) {
|
||||
@@ -1667,12 +1799,7 @@ function cmdSkillManifest(cwd, args, raw) {
|
||||
? args[skillsDirIdx + 1]
|
||||
: null;
|
||||
|
||||
if (!skillsDir) {
|
||||
output([], raw);
|
||||
return;
|
||||
}
|
||||
|
||||
const manifest = buildSkillManifest(skillsDir);
|
||||
const manifest = buildSkillManifest(cwd, skillsDir);
|
||||
|
||||
// Optionally write to .planning/skill-manifest.json
|
||||
if (args.includes('--write')) {
|
||||
|
||||
@@ -177,11 +177,11 @@ const CLAUDE_MD_FALLBACKS = {
|
||||
stack: 'Technology stack not yet documented. Will populate after codebase mapping or first phase.',
|
||||
conventions: 'Conventions not yet established. Will populate as patterns emerge during development.',
|
||||
architecture: 'Architecture not yet mapped. Follow existing patterns found in the codebase.',
|
||||
skills: 'No project skills found. Add skills to any of: `.claude/skills/`, `.agents/skills/`, `.cursor/skills/`, or `.github/skills/` with a `SKILL.md` index file.',
|
||||
skills: 'No project skills found. Add skills to any of: `.claude/skills/`, `.agents/skills/`, `.cursor/skills/`, `.github/skills/`, or `.codex/skills/` with a `SKILL.md` index file.',
|
||||
};
|
||||
|
||||
// Directories where project skills may live (checked in order)
|
||||
const SKILL_SEARCH_DIRS = ['.claude/skills', '.agents/skills', '.cursor/skills', '.github/skills'];
|
||||
const SKILL_SEARCH_DIRS = ['.claude/skills', '.agents/skills', '.cursor/skills', '.github/skills', '.codex/skills'];
|
||||
|
||||
const CLAUDE_MD_WORKFLOW_ENFORCEMENT = [
|
||||
'Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.',
|
||||
|
||||
Reference in New Issue
Block a user