NotebookLM Skills Factory

#!/usr/bin/env python3
"""Check a SKILL.md (or a skill folder) before installing it. Standard library only.

Usage:
  python3 scripts/check_skill.py <SKILL.md or skill folder>
  python3 scripts/check_skill.py <file> --fix      # also writes the cleaned file back

Errors (exit 1) are things that stop the skill loading: missing or bad frontmatter,
a name that breaks the rules, an empty or over-long description.
Warnings are quality problems worth fixing: no "use when" in the description,
missing sections, no sources list, a file so long it costs context on every use.

--fix only does safe, mechanical repairs: strips code fences NotebookLM sometimes wraps
the answer in, drops chat text before the frontmatter, lowercases/hyphenates the name,
and moves a trailing "## Sources" section into SOURCES.md next to the skill.
"""
import os, re, sys

NAME_RE = re.compile(r'^[a-z0-9]+(-[a-z0-9]+)*$')
SECTIONS = ['Goal', 'Method', 'Rules', 'Examples', 'Mistakes to avoid', 'Checklist']


def parse(text):
    m = re.match(r'^---\s*\n(.*?)\n---\s*\n?(.*)$', text, re.S)
    if not m:
        return None, text
    fm = {}
    key = None
    for line in m.group(1).splitlines():
        km = re.match(r'^([A-Za-z_][\w-]*):\s*(.*)$', line)
        if km:
            key = km.group(1)
            fm[key] = km.group(2).strip()
        elif key and line.startswith((' ', '\t')):
            fm[key] = (fm[key] + ' ' + line.strip()).strip()
    for k, v in fm.items():
        if v in ('>', '|', '>-', '|-'):
            fm[k] = ''
        fm[k] = fm[k].strip().strip('"').strip("'")
    return fm, m.group(2)


def clean(text):
    text = text.strip()
    text = re.sub(r'^```[a-zA-Z]*\s*\n', '', text)
    text = re.sub(r'\n```\s*$', '', text)
    i = text.find('---\n')
    if i > 0:
        text = text[i:]
    return text.strip() + '\n'


def main():
    if len(sys.argv) < 2:
        sys.exit(__doc__)
    path = sys.argv[1]
    fix = '--fix' in sys.argv
    if os.path.isdir(path):
        path = os.path.join(path, 'SKILL.md')
    if not os.path.exists(path):
        sys.exit(f'not found: {path}')
    raw = open(path, encoding='utf-8').read()
    text = clean(raw)
    errors, warnings, notes = [], [], []

    fm, body = parse(text)
    if fm is None:
        errors.append('No frontmatter. The file must start with --- , name: , description: , --- .')
        fm, body = {}, text

    name = fm.get('name', '')
    if fix and name and not NAME_RE.match(name):
        new = re.sub(r'[^a-z0-9]+', '-', name.lower()).strip('-')[:64]
        text = text.replace(f'name: {name}', f'name: {new}', 1)
        notes.append(f'name "{name}" -> "{new}"')
        name = new
    if not name:
        errors.append('name is missing.')
    else:
        if len(name) > 64:
            errors.append(f'name is {len(name)} characters; the limit is 64.')
        if not NAME_RE.match(name):
            errors.append(f'name "{name}" must be lowercase letters, numbers and hyphens only.')
        if 'claude' in name or 'anthropic' in name:
            errors.append(f'name "{name}" cannot contain the reserved words "claude" or "anthropic".')

    desc = fm.get('description', '')
    if not desc:
        errors.append('description is missing or empty.')
    else:
        if len(desc) > 1024:
            errors.append(f'description is {len(desc)} characters; the limit is 1,024.')
        if re.search(r'<[^>]+>', desc):
            errors.append('description cannot contain XML or HTML tags.')
        if not re.search(r'\buse (it )?(when|for|on)\b', desc, re.I):
            warnings.append('description does not say when to use the skill ("Use when ..."). Claude picks skills by the description, so name the requests that should trigger it.')
        if len(desc) < 60:
            warnings.append('description is very short; it may not trigger reliably.')

    heads = [h.strip() for h in re.findall(r'^##\s+(.+)$', body, re.M)]
    missing = [s for s in SECTIONS if not any(h.lower().startswith(s.lower()) for h in heads)]
    if missing:
        warnings.append('missing sections: ' + ', '.join(missing))

    src = re.search(r'^##\s+Sources\b.*$', body, re.M | re.I)
    has_sources_file = os.path.exists(os.path.join(os.path.dirname(os.path.abspath(path)), 'SOURCES.md'))
    if not src and not has_sources_file:
        warnings.append('no "## Sources" list. Ask NotebookLM which source supports each rule, and delete any rule it cannot trace.')
    elif fix:
        sources = body[src.start():].strip()
        body_wo = body[:src.start()].rstrip() + '\n'
        text = text.replace(body, body_wo, 1) if body in text else text
        out = os.path.join(os.path.dirname(os.path.abspath(path)), 'SOURCES.md')
        open(out, 'w', encoding='utf-8').write(sources + '\n')
        notes.append(f'moved the Sources list to {out} (kept for checking, not loaded on every use)')

    lines = text.count('\n')
    if lines > 500:
        warnings.append(f'{lines} lines. Keep SKILL.md under ~500 lines; move long reference material into a separate file in the skill folder.')
    for bad in ('as an ai', 'i cannot', "i can't access", 'based on the sources provided'):
        if bad in text.lower():
            warnings.append(f'contains chat filler ("{bad}"); delete it so it does not become an instruction.')

    if fix and (text != raw or notes):
        open(path, 'w', encoding='utf-8').write(text)
        notes.append(f'wrote {path}')

    print(f'skill: {name or "?"}  ({lines} lines)')
    for n in notes:
        print('  fixed  ' + n)
    for e in errors:
        print('  ERROR  ' + e)
    for w in warnings:
        print('  warn   ' + w)
    if not errors and not warnings:
        print('  ok     ready to install')
    sys.exit(1 if errors else 0)


if __name__ == '__main__':
    main()