promptgraph-mcp 2.1.9 → 2.2.1

package/index.js

@@ -246,12 +246,40 @@ if (args[0] === 'marketplace') {
 
 if (args[0] === 'validate') {
   const { validateSkill } = await import('./validator.js');
+  const { isSkillFile } = await import('./parser.js');
   const file = args[1];
   if (!file) { error('Usage: ' + bin + ' validate <skill.md>'); process.exit(1); }
+
+  const raw = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+
+  // Show indexing score breakdown
+  if (raw) {
+    const { skillScore: _score } = await import('./parser.js').catch(() => ({}));
+    const willIndex = isSkillFile(file, raw);
+    const scoreLabel = willIndex ? chalk.green('✓ will be indexed') : chalk.red('✗ will be skipped by indexer');
+    console.log(chalk.bold('\n  Indexing check: ') + scoreLabel);
+
+    // Show which signals were detected
+    const lines = raw.split('\n').filter(l => l.trim());
+    const signals = [];
+    try { const { data } = (await import('gray-matter')).default(raw); if (data.name) signals.push(chalk.green('+4 frontmatter name:')); } catch {}
+    if (/^#{1,3}\s+(steps?|usage|instructions?|how\s+to|when\s+to\s+use|workflow)/im.test(raw)) signals.push(chalk.green('+2 instructional headers (## Steps / ## Usage)'));
+    if (lines.filter(l => /^#{1,3}\s/.test(l)).some(h => /\b(run|use|fix|debug|check|create|deploy|scan|audit)\b/i.test(h))) signals.push(chalk.green('+2 imperative verbs in headers'));
+    if (raw.includes('```')) signals.push(chalk.green('+1 code block'));
+    if (lines.some(l => /^\d+\.\s/.test(l))) signals.push(chalk.green('+1 numbered list'));
+    if (lines.some(l => /^[-*+]\s/.test(l))) signals.push(chalk.green('+1 bullet list'));
+    const firstH = lines.find(l => /^#{1,3}\s/.test(l))?.replace(/^#+\s*/, '') || '';
+    if (/^(overview|introduction|about|background|welcome)/i.test(firstH)) signals.push(chalk.red('-3 first header looks like docs ("' + firstH + '")'));
+    if (signals.length) {
+      signals.forEach(s => console.log('    ' + s));
+    }
+    console.log();
+  }
+
   const result = validateSkill(file);
   result.warnings.forEach(w => console.log(chalk.yellow('⚠') + '  ' + chalk.gray(w)));
   if (result.ok) {
-    success('Skill is valid');
+    success('Skill is valid — ready to publish');
     process.exit(0);
   } else {
     error('Validation failed:');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promptgraph-mcp",
-  "version": "2.1.9",
+  "version": "2.2.1",
   "main": "index.js",
   "type": "module",
   "bin": {

package/parser.js

@@ -9,15 +9,18 @@ const SKILL_REF_RE = /(?<!https?:|ftp:)(?<![a-zA-Z0-9])\/([a-z0-9][a-z0-9-]{2,})
 const SKIP_FILENAMES = new Set([
   'readme', 'changelog', 'license', 'contributing', 'code-of-conduct',
   'security', 'authors', 'credits', 'install', 'installation', 'usage',
-  'engagements', 'contributing', 'contributors', 'maintainers',
-  'acknowledgements', 'faq', 'glossary', 'index', 'overview', 'summary',
-  'roadmap', 'todo', 'notes', 'template', 'example', 'sample', 'demo',
-  'getting-started', 'quickstart', 'guide', 'tutorial', 'walkthrough',
-  'architecture', 'design', 'spec', 'specification', 'requirements',
-  'privacy', 'terms', 'disclaimer', 'notice', 'copying', 'warranty',
-  'codeofconduct', 'pull_request_template', 'issue_template', 'funding',
+  'engagements', 'contributors', 'maintainers', 'acknowledgements',
+  'faq', 'glossary', 'index', 'overview', 'summary', 'roadmap', 'todo',
+  'notes', 'template', 'example', 'sample', 'demo', 'getting-started',
+  'quickstart', 'guide', 'tutorial', 'walkthrough', 'architecture',
+  'design', 'spec', 'specification', 'requirements', 'privacy', 'terms',
+  'disclaimer', 'notice', 'copying', 'warranty', 'codeofconduct',
+  'pull_request_template', 'issue_template', 'funding',
 ]);
 
+// Filename patterns that are never skills
+const SKIP_FILENAME_RE = /^(_|\.)|^v?\d+[\.\-]\d+|^\d{4}[\-_]\d{2}/i; // _template, .hidden, v1.0, 2024-01
+
 // Path segments that indicate the file is NOT a skill
 const SKIP_DIRS = new Set([
   '.github', 'docs', 'doc', 'documentation', 'examples', 'example',
@@ -26,38 +29,97 @@ const SKIP_DIRS = new Set([
   'node_modules', 'vendor', 'third_party',
 ]);
 
+// First-header values that signal documentation, not a skill
+const DOC_FIRST_HEADERS = /^(overview|introduction|about|background|welcome|getting started|what is|why |table of contents|toc|foreword|preface)/i;
+
+// Imperative verbs commonly found in skill headers
+const IMPERATIVE_HEADERS = /\b(run|use|apply|execute|check|debug|fix|create|add|remove|deploy|test|write|generate|analyze|review|refactor|optimize|configure|setup|install|scan|audit|validate|search|find|extract|parse)\b/i;
+
+// Instructional section headers
+const INSTRUCTION_HEADERS = /^#{1,3}\s+(steps?|usage|instructions?|how\s+to|when\s+to\s+use|workflow|process|procedure|example|examples?|commands?|output|result)/i;
+
+// ── scoring ───────────────────────────────────────────────────────────────────
+
+function skillScore(raw, base) {
+  let score = 0;
+
+  // Fast path: frontmatter with name = definitely a skill
+  try {
+    const { data } = matter(raw);
+    if (data.name && typeof data.name === 'string') return 10;
+  } catch {}
+
+  const lines = raw.split('\n');
+  const nonEmpty = lines.filter(l => l.trim());
+  const headers = nonEmpty.filter(l => /^#{1,3}\s/.test(l));
+
+  // Minimum viable content
+  if (raw.length < 150)  return -99;
+  if (headers.length < 1) return -99;
+
+  // ── positive signals ──────────────────────────────────────────────────────
+
+  // Instructional section names (## Steps, ## Usage, etc.)
+  if (lines.some(l => INSTRUCTION_HEADERS.test(l))) score += 2;
+
+  // Headers with imperative verbs
+  if (headers.some(h => IMPERATIVE_HEADERS.test(h))) score += 2;
+
+  // Code block
+  if (raw.includes('```') || raw.includes('    ')) score += 1;
+
+  // Numbered list (step-by-step)
+  if (nonEmpty.some(l => /^\d+\.\s/.test(l))) score += 1;
+
+  // Bullet list
+  if (nonEmpty.some(l => /^[-*+]\s/.test(l))) score += 1;
+
+  // Multiple headers (structure)
+  if (headers.length >= 2) score += 1;
+  if (headers.length >= 4) score += 1;
+
+  // ── negative signals ──────────────────────────────────────────────────────
+
+  // First header looks like documentation
+  const firstHeader = headers[0]?.replace(/^#+\s*/, '') || '';
+  if (DOC_FIRST_HEADERS.test(firstHeader)) score -= 3;
+
+  // Content is mostly long prose paragraphs (narrative, not instructional)
+  const paragraphs = raw.split(/\n\n+/).filter(p => p.trim() && !p.trim().startsWith('#'));
+  const longProse = paragraphs.filter(p => p.split(' ').length > 60 && !/```/.test(p));
+  if (longProse.length > paragraphs.length * 0.6 && paragraphs.length > 3) score -= 2;
+
+  // Filename looks like a version, date, or index
+  if (SKIP_FILENAME_RE.test(base)) score -= 3;
+
+  // Very high word repetition (filler content)
+  const words = raw.toLowerCase().split(/\s+/).filter(w => w.length > 3);
+  if (words.length > 80) {
+    const unique = new Set(words);
+    if (unique.size / words.length < 0.22) score -= 2;
+  }
+
+  return score;
+}
+
+// ── public API ────────────────────────────────────────────────────────────────
+
 export function isSkillFile(filePath, raw) {
   const parts = filePath.replace(/\\/g, '/').split('/');
   const base = parts[parts.length - 1].replace(/\.md$/i, '').toLowerCase();
 
+  // Hard-reject by filename
   if (SKIP_FILENAMES.has(base)) return false;
+  if (SKIP_FILENAME_RE.test(base)) return false;
 
+  // Hard-reject by parent directory
   for (const part of parts.slice(0, -1)) {
     if (SKIP_DIRS.has(part.toLowerCase())) return false;
   }
 
   try {
     if (!raw) raw = fs.readFileSync(filePath, 'utf8');
-
-    // Too short to be a real skill
-    if (raw.length < 150) return false;
-
-    // Has valid frontmatter with name → definitely a skill
-    try {
-      const { data } = matter(raw);
-      if (data.name && typeof data.name === 'string') return true;
-    } catch {}
-
-    // No frontmatter — check if it looks like instructions (not pure docs)
-    // Must have some imperative/instructional content, not just markdown prose
-    const lines = raw.split('\n').filter(l => l.trim());
-    const hasCodeBlock = raw.includes('```');
-    const hasBullets = lines.some(l => /^[-*]\s/.test(l));
-    const hasNumbered = lines.some(l => /^\d+\.\s/.test(l));
-    const hasHeaders = lines.filter(l => /^#{1,3}\s/.test(l)).length >= 2;
-
-    // Must look structured, not just a prose document
-    return (hasCodeBlock || hasBullets || hasNumbered) && hasHeaders;
+    return skillScore(raw, base) >= 3;
   } catch {
     return false;
   }