novahiz 0.2.3 → 0.3.1

package/skills/skill-creator/scripts/run_loop.py

@@ -1,328 +0,0 @@
-#!/usr/bin/env python3
-"""Run the eval + improve loop until all pass or max iterations reached.
-
-Combines run_eval.py and improve_description.py in a loop, tracking history
-and returning the best description found. Supports train/test split to prevent
-overfitting.
-"""
-
-import argparse
-import json
-import random
-import sys
-import tempfile
-import time
-import webbrowser
-from pathlib import Path
-
-from scripts.generate_report import generate_html
-from scripts.improve_description import improve_description
-from scripts.run_eval import find_project_root, run_eval
-from scripts.utils import parse_skill_md
-
-
-def split_eval_set(eval_set: list[dict], holdout: float, seed: int = 42) -> tuple[list[dict], list[dict]]:
-    """Split eval set into train and test sets, stratified by should_trigger."""
-    random.seed(seed)
-
-    # Separate by should_trigger
-    trigger = [e for e in eval_set if e["should_trigger"]]
-    no_trigger = [e for e in eval_set if not e["should_trigger"]]
-
-    # Shuffle each group
-    random.shuffle(trigger)
-    random.shuffle(no_trigger)
-
-    # Calculate split points
-    n_trigger_test = max(1, int(len(trigger) * holdout))
-    n_no_trigger_test = max(1, int(len(no_trigger) * holdout))
-
-    # Split
-    test_set = trigger[:n_trigger_test] + no_trigger[:n_no_trigger_test]
-    train_set = trigger[n_trigger_test:] + no_trigger[n_no_trigger_test:]
-
-    return train_set, test_set
-
-
-def run_loop(
-    eval_set: list[dict],
-    skill_path: Path,
-    description_override: str | None,
-    num_workers: int,
-    timeout: int,
-    max_iterations: int,
-    runs_per_query: int,
-    trigger_threshold: float,
-    holdout: float,
-    model: str,
-    verbose: bool,
-    live_report_path: Path | None = None,
-    log_dir: Path | None = None,
-) -> dict:
-    """Run the eval + improvement loop."""
-    project_root = find_project_root()
-    name, original_description, content = parse_skill_md(skill_path)
-    current_description = description_override or original_description
-
-    # Split into train/test if holdout > 0
-    if holdout > 0:
-        train_set, test_set = split_eval_set(eval_set, holdout)
-        if verbose:
-            print(f"Split: {len(train_set)} train, {len(test_set)} test (holdout={holdout})", file=sys.stderr)
-    else:
-        train_set = eval_set
-        test_set = []
-
-    history = []
-    exit_reason = "unknown"
-
-    for iteration in range(1, max_iterations + 1):
-        if verbose:
-            print(f"\n{'='*60}", file=sys.stderr)
-            print(f"Iteration {iteration}/{max_iterations}", file=sys.stderr)
-            print(f"Description: {current_description}", file=sys.stderr)
-            print(f"{'='*60}", file=sys.stderr)
-
-        # Evaluate train + test together in one batch for parallelism
-        all_queries = train_set + test_set
-        t0 = time.time()
-        all_results = run_eval(
-            eval_set=all_queries,
-            skill_name=name,
-            description=current_description,
-            num_workers=num_workers,
-            timeout=timeout,
-            project_root=project_root,
-            runs_per_query=runs_per_query,
-            trigger_threshold=trigger_threshold,
-            model=model,
-        )
-        eval_elapsed = time.time() - t0
-
-        # Split results back into train/test by matching queries
-        train_queries_set = {q["query"] for q in train_set}
-        train_result_list = [r for r in all_results["results"] if r["query"] in train_queries_set]
-        test_result_list = [r for r in all_results["results"] if r["query"] not in train_queries_set]
-
-        train_passed = sum(1 for r in train_result_list if r["pass"])
-        train_total = len(train_result_list)
-        train_summary = {"passed": train_passed, "failed": train_total - train_passed, "total": train_total}
-        train_results = {"results": train_result_list, "summary": train_summary}
-
-        if test_set:
-            test_passed = sum(1 for r in test_result_list if r["pass"])
-            test_total = len(test_result_list)
-            test_summary = {"passed": test_passed, "failed": test_total - test_passed, "total": test_total}
-            test_results = {"results": test_result_list, "summary": test_summary}
-        else:
-            test_results = None
-            test_summary = None
-
-        history.append({
-            "iteration": iteration,
-            "description": current_description,
-            "train_passed": train_summary["passed"],
-            "train_failed": train_summary["failed"],
-            "train_total": train_summary["total"],
-            "train_results": train_results["results"],
-            "test_passed": test_summary["passed"] if test_summary else None,
-            "test_failed": test_summary["failed"] if test_summary else None,
-            "test_total": test_summary["total"] if test_summary else None,
-            "test_results": test_results["results"] if test_results else None,
-            # For backward compat with report generator
-            "passed": train_summary["passed"],
-            "failed": train_summary["failed"],
-            "total": train_summary["total"],
-            "results": train_results["results"],
-        })
-
-        # Write live report if path provided
-        if live_report_path:
-            partial_output = {
-                "original_description": original_description,
-                "best_description": current_description,
-                "best_score": "in progress",
-                "iterations_run": len(history),
-                "holdout": holdout,
-                "train_size": len(train_set),
-                "test_size": len(test_set),
-                "history": history,
-            }
-            live_report_path.write_text(generate_html(partial_output, auto_refresh=True, skill_name=name))
-
-        if verbose:
-            def print_eval_stats(label, results, elapsed):
-                pos = [r for r in results if r["should_trigger"]]
-                neg = [r for r in results if not r["should_trigger"]]
-                tp = sum(r["triggers"] for r in pos)
-                pos_runs = sum(r["runs"] for r in pos)
-                fn = pos_runs - tp
-                fp = sum(r["triggers"] for r in neg)
-                neg_runs = sum(r["runs"] for r in neg)
-                tn = neg_runs - fp
-                total = tp + tn + fp + fn
-                precision = tp / (tp + fp) if (tp + fp) > 0 else 1.0
-                recall = tp / (tp + fn) if (tp + fn) > 0 else 1.0
-                accuracy = (tp + tn) / total if total > 0 else 0.0
-                print(f"{label}: {tp+tn}/{total} correct, precision={precision:.0%} recall={recall:.0%} accuracy={accuracy:.0%} ({elapsed:.1f}s)", file=sys.stderr)
-                for r in results:
-                    status = "PASS" if r["pass"] else "FAIL"
-                    rate_str = f"{r['triggers']}/{r['runs']}"
-                    print(f"  [{status}] rate={rate_str} expected={r['should_trigger']}: {r['query'][:60]}", file=sys.stderr)
-
-            print_eval_stats("Train", train_results["results"], eval_elapsed)
-            if test_summary:
-                print_eval_stats("Test ", test_results["results"], 0)
-
-        if train_summary["failed"] == 0:
-            exit_reason = f"all_passed (iteration {iteration})"
-            if verbose:
-                print(f"\nAll train queries passed on iteration {iteration}!", file=sys.stderr)
-            break
-
-        if iteration == max_iterations:
-            exit_reason = f"max_iterations ({max_iterations})"
-            if verbose:
-                print(f"\nMax iterations reached ({max_iterations}).", file=sys.stderr)
-            break
-
-        # Improve the description based on train results
-        if verbose:
-            print(f"\nImproving description...", file=sys.stderr)
-
-        t0 = time.time()
-        # Strip test scores from history so improvement model can't see them
-        blinded_history = [
-            {k: v for k, v in h.items() if not k.startswith("test_")}
-            for h in history
-        ]
-        new_description = improve_description(
-            skill_name=name,
-            skill_content=content,
-            current_description=current_description,
-            eval_results=train_results,
-            history=blinded_history,
-            model=model,
-            log_dir=log_dir,
-            iteration=iteration,
-        )
-        improve_elapsed = time.time() - t0
-
-        if verbose:
-            print(f"Proposed ({improve_elapsed:.1f}s): {new_description}", file=sys.stderr)
-
-        current_description = new_description
-
-    # Find the best iteration by TEST score (or train if no test set)
-    if test_set:
-        best = max(history, key=lambda h: h["test_passed"] or 0)
-        best_score = f"{best['test_passed']}/{best['test_total']}"
-    else:
-        best = max(history, key=lambda h: h["train_passed"])
-        best_score = f"{best['train_passed']}/{best['train_total']}"
-
-    if verbose:
-        print(f"\nExit reason: {exit_reason}", file=sys.stderr)
-        print(f"Best score: {best_score} (iteration {best['iteration']})", file=sys.stderr)
-
-    return {
-        "exit_reason": exit_reason,
-        "original_description": original_description,
-        "best_description": best["description"],
-        "best_score": best_score,
-        "best_train_score": f"{best['train_passed']}/{best['train_total']}",
-        "best_test_score": f"{best['test_passed']}/{best['test_total']}" if test_set else None,
-        "final_description": current_description,
-        "iterations_run": len(history),
-        "holdout": holdout,
-        "train_size": len(train_set),
-        "test_size": len(test_set),
-        "history": history,
-    }
-
-
-def main():
-    parser = argparse.ArgumentParser(description="Run eval + improve loop")
-    parser.add_argument("--eval-set", required=True, help="Path to eval set JSON file")
-    parser.add_argument("--skill-path", required=True, help="Path to skill directory")
-    parser.add_argument("--description", default=None, help="Override starting description")
-    parser.add_argument("--num-workers", type=int, default=10, help="Number of parallel workers")
-    parser.add_argument("--timeout", type=int, default=30, help="Timeout per query in seconds")
-    parser.add_argument("--max-iterations", type=int, default=5, help="Max improvement iterations")
-    parser.add_argument("--runs-per-query", type=int, default=3, help="Number of runs per query")
-    parser.add_argument("--trigger-threshold", type=float, default=0.5, help="Trigger rate threshold")
-    parser.add_argument("--holdout", type=float, default=0.4, help="Fraction of eval set to hold out for testing (0 to disable)")
-    parser.add_argument("--model", required=True, help="Model for improvement")
-    parser.add_argument("--verbose", action="store_true", help="Print progress to stderr")
-    parser.add_argument("--report", default="auto", help="Generate HTML report at this path (default: 'auto' for temp file, 'none' to disable)")
-    parser.add_argument("--results-dir", default=None, help="Save all outputs (results.json, report.html, log.txt) to a timestamped subdirectory here")
-    args = parser.parse_args()
-
-    eval_set = json.loads(Path(args.eval_set).read_text())
-    skill_path = Path(args.skill_path)
-
-    if not (skill_path / "SKILL.md").exists():
-        print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr)
-        sys.exit(1)
-
-    name, _, _ = parse_skill_md(skill_path)
-
-    # Set up live report path
-    if args.report != "none":
-        if args.report == "auto":
-            timestamp = time.strftime("%Y%m%d_%H%M%S")
-            live_report_path = Path(tempfile.gettempdir()) / f"skill_description_report_{skill_path.name}_{timestamp}.html"
-        else:
-            live_report_path = Path(args.report)
-        # Open the report immediately so the user can watch
-        live_report_path.write_text("<html><body><h1>Starting optimization loop...</h1><meta http-equiv='refresh' content='5'></body></html>")
-        webbrowser.open(str(live_report_path))
-    else:
-        live_report_path = None
-
-    # Determine output directory (create before run_loop so logs can be written)
-    if args.results_dir:
-        timestamp = time.strftime("%Y-%m-%d_%H%M%S")
-        results_dir = Path(args.results_dir) / timestamp
-        results_dir.mkdir(parents=True, exist_ok=True)
-    else:
-        results_dir = None
-
-    log_dir = results_dir / "logs" if results_dir else None
-
-    output = run_loop(
-        eval_set=eval_set,
-        skill_path=skill_path,
-        description_override=args.description,
-        num_workers=args.num_workers,
-        timeout=args.timeout,
-        max_iterations=args.max_iterations,
-        runs_per_query=args.runs_per_query,
-        trigger_threshold=args.trigger_threshold,
-        holdout=args.holdout,
-        model=args.model,
-        verbose=args.verbose,
-        live_report_path=live_report_path,
-        log_dir=log_dir,
-    )
-
-    # Save JSON output
-    json_output = json.dumps(output, indent=2)
-    print(json_output)
-    if results_dir:
-        (results_dir / "results.json").write_text(json_output)
-
-    # Write final HTML report (without auto-refresh)
-    if live_report_path:
-        live_report_path.write_text(generate_html(output, auto_refresh=False, skill_name=name))
-        print(f"\nReport: {live_report_path}", file=sys.stderr)
-
-    if results_dir and live_report_path:
-        (results_dir / "report.html").write_text(generate_html(output, auto_refresh=False, skill_name=name))
-
-    if results_dir:
-        print(f"Results saved to: {results_dir}", file=sys.stderr)
-
-
-if __name__ == "__main__":
-    main()

package/skills/skill-creator/scripts/utils.py

@@ -1,47 +0,0 @@
-"""Shared utilities for skill-creator scripts."""
-
-from pathlib import Path
-
-
-
-def parse_skill_md(skill_path: Path) -> tuple[str, str, str]:
-    """Parse a SKILL.md file, returning (name, description, full_content)."""
-    content = (skill_path / "SKILL.md").read_text()
-    lines = content.split("\n")
-
-    if lines[0].strip() != "---":
-        raise ValueError("SKILL.md missing frontmatter (no opening ---)")
-
-    end_idx = None
-    for i, line in enumerate(lines[1:], start=1):
-        if line.strip() == "---":
-            end_idx = i
-            break
-
-    if end_idx is None:
-        raise ValueError("SKILL.md missing frontmatter (no closing ---)")
-
-    name = ""
-    description = ""
-    frontmatter_lines = lines[1:end_idx]
-    i = 0
-    while i < len(frontmatter_lines):
-        line = frontmatter_lines[i]
-        if line.startswith("name:"):
-            name = line[len("name:"):].strip().strip('"').strip("'")
-        elif line.startswith("description:"):
-            value = line[len("description:"):].strip()
-            # Handle YAML multiline indicators (>, |, >-, |-)
-            if value in (">", "|", ">-", "|-"):
-                continuation_lines: list[str] = []
-                i += 1
-                while i < len(frontmatter_lines) and (frontmatter_lines[i].startswith("  ") or frontmatter_lines[i].startswith("\t")):
-                    continuation_lines.append(frontmatter_lines[i].strip())
-                    i += 1
-                description = " ".join(continuation_lines)
-                continue
-            else:
-                description = value.strip('"').strip("'")
-        i += 1
-
-    return name, description, content

package/skills/write-a-skill/SKILL.md

@@ -1,111 +0,0 @@
----
-name: write-a-skill
-description: Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, build, or author a new skill.
-license: Apache-2.0
-metadata:
-  author: Novahiz
-  organization: Novahiz
-  version: "2.0.0"
-  date: September 2026
----
-
-# Writing skills
-
-## Process
-
-1. **Clarify the need.** Ask about the domain, the concrete cases the skill must handle, whether scripts are required, and what reference material should ship with it.
-2. **Draft the files.** Write SKILL.md first. Push anything past 100 lines into a reference file. Add scripts only for deterministic work the model should not re-derive each time.
-3. **Review with the author.** Present the draft. Ask what is missing, what is unclear, and which sections are too heavy or too thin.
-
-## Layout
-
-```
-skill-name/
-├── SKILL.md           # required entry point
-├── REFERENCE.md       # optional long-form detail
-├── EXAMPLES.md        # optional worked cases
-└── scripts/           # optional helpers
-    └── helper.js
-```
-
-## SKILL.md skeleton
-
-```md
----
-name: skill-name
-description: What the skill does. Use when [specific triggers].
----
-
-# Skill name
-
-## Quick start
-
-[Minimal working example]
-
-## Workflows
-
-[Step-by-step processes for complex tasks]
-
-## Advanced features
-
-[See REFERENCE.md](REFERENCE.md)
-```
-
-## Description rules
-
-The description is the only text the agent sees when it decides whether to load the skill. It sits in the system prompt next to every other installed skill, and the agent picks from it alone.
-
-Two facts must land:
-
-1. What the skill does.
-2. When to fire: keywords, contexts, file types.
-
-Constraints:
-
-- Hard cap at 1024 characters.
-- Third person throughout.
-- Sentence one: the action.
-- Sentence two: `Use when [specific triggers]`.
-
-Good:
-
-```
-Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
-```
-
-Bad:
-
-```
-Helps with documents.
-```
-
-The weak version gives the agent nothing to match against. Every document skill in the list looks the same from it.
-
-## When scripts belong in the skill
-
-Ship a script when the work is deterministic (validation, formatting), when the same code would otherwise be generated over and over, or when failure needs explicit handling. Scripts cut token use and remove the chance of two runs inventing two different implementations.
-
-## When to split the file
-
-Split when SKILL.md crosses 100 lines, when the content covers distinct domains (finance schemas next to sales schemas), or when advanced paths are rarely needed. The agent should read SKILL.md in full and stop there unless a pointer sends it deeper.
-
-## Review checklist
-
-- [ ] Description carries triggers (`Use when ...`)
-- [ ] SKILL.md stays under 100 lines
-- [ ] No dates, versions, or `as of YYYY` claims
-- [ ] One word per concept throughout
-- [ ] At least one concrete example
-- [ ] References sit one level deep
-
-## Tooling
-
-Three stdlib validators sit next to this skill:
-
-```
-python scripts/skill_description_validator.py path/to/SKILL.md
-python scripts/skill_structure_validator.py path/to/skill-folder
-python scripts/skill_review_checklist_runner.py path/to/skill-folder
-```
-
-Catalogue and companions: [references/companion_tooling.md](references/companion_tooling.md).

package/skills/write-a-skill/references/companion_tooling.md

@@ -1,61 +0,0 @@
-# Companion Tooling
-
-Validation tools layered on top of the core skill-authoring process. Use these when authoring a new skill in this repo.
-
-## Validation Tools (stdlib Python)
-
-| Tool | Purpose | Run before |
-|---|---|---|
-| `scripts/skill_description_validator.py` | Validates description: ≤1024 chars, third person, "Use when" trigger, action verb in first sentence | First draft of SKILL.md |
-| `scripts/skill_structure_validator.py` | Validates folder structure: SKILL.md present, ≤100 lines, references one level deep, no circular refs | Pre-commit |
-| `scripts/skill_review_checklist_runner.py` | Runs all 6 review-checklist items against a skill folder | Final check before PR |
-
-All three tools:
-- Stdlib-only (no external dependencies)
-- Run with embedded sample if no path provided
-- Output text or JSON (`--output json`)
-- Exit code: 0 if PASS, 1 if FAIL/WARN
-
-## cs-skill-author Persona Agent
-
-Lives at `../agents/cs-skill-author.md`. Voice: forcing-question interrogator. Surfaces the skill-authoring workflow as an interrogation before any new skill commit.
-
-**Opening question:** "What capability does this skill provide, and what's the trigger phrase that distinguishes it from existing skills?"
-
-**Six forcing questions** (matches the review checklist):
-1. What's the description? Is it ≤1024 chars + third person + has "Use when ..."?
-2. Is SKILL.md under 100 lines? If not, where will the split land (REFERENCE.md / EXAMPLES.md / references/)?
-3. Are there time-sensitive claims (dates, "as of YYYY")?
-4. Is terminology consistent: same word for the same concept throughout?
-5. Concrete examples: at least 1 code block, ideally good/bad contrast?
-6. References one level deep, no circular refs?
-
-## `/cs:write-a-skill` Slash Command
-
-Lives at `../commands/cs-write-a-skill.md`. Three-step flow:
-
-1. Run `cs-skill-author` interrogation (6 questions)
-2. Draft skill files per the structure pattern
-3. Run all 3 validation tools; show verdict; fix until PASS
-
-Use when: starting a new skill in this repo from scratch.
-
-## Why Wrap the Core Process
-
-The core write-a-skill process is a tight, principled skill: perfect as-is for individual authoring sessions. The wrapper layers add three things this repo benefits from at scale:
-
-1. **Programmatic enforcement** of the review checklist (the validation tools): prevents human review-checklist drift across 100+ skills.
-2. **Forcing-question interrogation** (the cs-skill-author persona): adapts the "review with user" phase to the cs-* persona pattern used elsewhere in this repo.
-3. **Citation-backed references**: the core process links to principles; the wrapper adds 5+ authoritative external sources per reference for newcomers learning the pattern.
-
----
-
-**Source authorities (non-exhaustive):**
-
-- **Novahiz skill-authoring standard** (this repo): the core process
-- **Skills documentation**: official guidance on skill structure
-- **Engineering blog: Skills patterns** (continuously updated): patterns for skill authoring
-- **Karpathy, A.: "Software 3.0" + LLM coding pitfalls** (X.com posts 2024-2025): discipline reference applied throughout this repo's karpathy-coder skill
-- **Pareto principle applied to documentation**: concise = trustworthy; 80% of value in 20% of words
-- **Hyrum's Law** as applied to skill descriptions: once a description shape is observed, downstream agents depend on it
-- **Conway's Law as applied to skill libraries**: skill organization mirrors team responsibilities; progressive disclosure mirrors information needs across team boundaries

package/skills/write-a-skill/references/description_design_patterns.md

@@ -1,136 +0,0 @@
-# Description Design Patterns for Skills
-
-This reference answers exactly one decision: how do we write a skill description that an agent actually picks correctly when faced with a long skill list?
-
-Pair with `scripts/skill_description_validator.py` for automated enforcement.
-
-## The Core Rule
-
-The description is the only thing your agent sees when deciding which skill to load.
-
-Implication: the description is not marketing copy. It is a routing signal for the agent. Every word competes with every other skill's description for activation attention.
-
-## The Four Format Rules
-
-1. **Max 1024 chars**: beyond this, agents lose the early sentences when condensing context
-2. **Third person**: first-person ("I help with...") confuses agent self-identification; second-person ("You can...") confuses pronoun reference
-3. **First sentence: what it does**: front-load the verb + object
-4. **Second sentence: "Use when [specific triggers]"**: agent's most reliable activation cue
-
-## Good vs Bad Examples
-
-**Good:**
-
-```
-Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
-```
-
-**Why good:**
-- Front-loaded verbs: Extract, fill, merge
-- Concrete objects: text, tables, PDF files, forms
-- Explicit trigger: "Use when working with PDF files"
-- Specific keywords for matching: "PDFs", "forms", "document extraction"
-
-**Bad:**
-
-```
-Helps with documents.
-```
-
-**Why bad:**
-- "Helps" is content-free
-- "Documents" is generic: every doc skill has this
-- No trigger
-- No keyword variety
-
-**Bad in a different way (over-specified):**
-
-```
-This skill performs comprehensive PDF document processing including but not limited to extraction, manipulation, format conversion, content analysis, metadata management, and security operations on PDF files, with support for various PDF versions and embedded media types.
-```
-
-**Why bad:** verbose, no triggers, agent can't extract the key keywords from the wall of text.
-
-## The Trigger Sentence Pattern
-
-The "Use when" sentence is the highest-impact part of the description. Patterns that work:
-
-**Keyword triggers** (when user types specific words):
-```
-Use when user mentions PDFs, forms, or document extraction.
-```
-
-**File-type triggers** (when agent sees specific files):
-```
-Use when working with `.tsx` files or React component tests.
-```
-
-**Context triggers** (when agent is in a specific state):
-```
-Use when the user requests a code review of a pull request.
-```
-
-**Workflow triggers** (when agent is mid-workflow):
-```
-Use after running tests and before committing changes.
-```
-
-## Vocabulary Selection
-
-The description's words must overlap with words users + agents naturally use for the task.
-
-| Bad keyword | Better keyword | Why |
-|---|---|---|
-| "documents" | "PDF files" / "Word docs" | More specific = less collision |
-| "improve" | "refactor" / "fix" / "optimize" | Specific verb = clearer routing |
-| "various" | (delete; just list them) | Hedge language = no info |
-| "modern" | (cite the actual tool/version) | Trend words age badly |
-| "comprehensive" | (delete; just list capabilities) | Adjective inflation |
-
-## Length Optimization
-
-Below 1024 chars, shorter is usually better. Target: 100-300 chars for most skills.
-
-Where complexity demands more chars, prioritize:
-1. The verb-object pair (what it does): never compress
-2. The trigger phrase: never compress
-3. Keyword variety (different ways users describe it): expand here if space allows
-4. Anti-keyword (what it does NOT do): only if there's a frequently-confused sibling skill
-
-## Anti-Patterns to Avoid
-
-1. **First-person voice**: "I extract PDFs": confuses agent self-reference
-2. **Marketing language**: "fast, powerful, intuitive": agent doesn't care, ignores adjectives
-3. **Trigger-less descriptions**: every skill needs "Use when X"
-4. **Multi-purpose dumping**: if your skill does 10 unrelated things, it's probably 10 skills
-5. **Pronouns and hedges**: "you can also use this if you want to": drop entirely
-6. **Recursive descriptions**: "Use this skill when you need this skill": adds nothing
-7. **Implementation details**: "Built on Python + stdlib": agent doesn't care; matters for README, not description
-
-## Pre-Commit Discipline
-
-Run before every skill PR:
-
-```bash
-python scripts/skill_description_validator.py path/to/SKILL.md
-```
-
-If validator returns FAIL, fix before merging. If WARN, justify and document the trade-off.
-
-## When This Reference Doesn't Help
-
-- **Naming the skill itself**: different concern; see naming-conventions guidance per-repo
-- **Skill discovery in marketplaces**: different audience (humans browsing), different rules
-- **System-prompt design for the agent that loads skills**: separate concern
-
----
-
-**Source authorities (non-exhaustive):**
-
-- **Novahiz authoring standard** (this repo): the 4 format rules + good/bad example pattern
-- **Skill registry documentation**: how a skill-loader uses descriptions for routing
-- **Effective system prompt writing guides**: same principles applied to system-prompt design
-- **Karpathy, A.: public commentary on LLM prompt design**: emphasis on specificity + lack of ambiguity
-- **Garrett, J.J.: "The Elements of User Experience"** (2002) + information architecture principles: labels must match user mental models
-- **Nielsen Norman Group: Microcontent guidelines**: applies to skill descriptions: front-load value, hard-cap length, scannable structure
-- **Search-engine + SEO patterns adapted for agent routing**: keyword density, intent matching, semantic field coverage