Skill Builder

# Executable spec for the /skill-builder skill — skill scaffolding (BC1 Corpus / Skill Catalog).
# /skill-builder scaffolds a new SKILL.md (or absorbs an existing one) against the unified
# AgentOps template, then generates the Codex parity bundle, self-audits, and overlays a
# factory score. Hexagon: supporting; consumes: a build request + the unified template;
# produces: a new skill + build-report.json. (soc-qk4b)

Feature: Skill-builder materializes template-conformant skills
  As an author adding a skill to the catalog
  I want it scaffolded from the unified template and parity-checked
  So that every new skill is well-formed and Codex-mirrored from the start

  Background:
    Given the unified AgentOps SKILL.md template

  Scenario: A mode is dispatched for build or absorb
    When /skill-builder runs
    Then it dispatches the requested mode (scaffold a new skill or absorb an existing one)

  Scenario: The skill is materialized from the template
    When the build proceeds
    Then it produces a SKILL.md conformant to the unified template

  Scenario: The Codex parity bundle is generated
    When the skill is materialized
    Then it generates the matching skills-codex bundle and hashes

  Scenario: The build self-audits and scores before reporting
    When materialization completes
    Then it self-audits the result and overlays a factory score in build-report.json

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "title": "Skill Build Report",
  "description": "Output contract for skill-builder. Reports what mode ran, which files were created, and whether the post-build self-audit passed.",
  "type": "object",
  "required": ["mode", "skill_name", "files_created", "audit_pass"],
  "properties": {
    "mode": {
      "type": "string",
      "enum": ["from-scratch", "from-template", "absorb-external", "from-pattern"],
      "description": "Which builder mode produced this skill. from-pattern is alpha (passthrough to ao flywheel close-loop)."
    },
    "skill_name": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "description": "Lowercase-hyphen slug for the new skill (matches directory name)."
    },
    "files_created": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Absolute or repo-relative paths of files written during this build."
    },
    "audit_pass": {
      "type": "boolean",
      "description": "Did the immediate post-build self-audit (skill-auditor) emit VERDICT: PASS or VERDICT: WARN? (False if FAIL.)"
    },
    "audit_report_path": {
      "type": "string",
      "description": "Where the self-audit report was written (typically .agents/audits/<skill>-build.md)."
    },
    "warnings": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Non-fatal issues surfaced during build (e.g., template SHA pin mismatch, missing optional sections)."
    },
    "source": {
      "type": "object",
      "description": "Mode-specific provenance.",
      "properties": {
        "external_path": {"type": "string", "description": "For absorb-external: source SKILL.md path"},
        "template_skill": {"type": "string", "description": "For from-template: skill copied from"},
        "flywheel_run_id": {"type": "string", "description": "For from-pattern: ao flywheel close-loop run id"}
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

#!/usr/bin/env bash
# build.sh — skill-builder mode dispatcher
# Usage:
#   build.sh from-scratch <skill-name>
#   build.sh from-template <skill-name> --like <existing-skill>
#   build.sh absorb-external <skill-name> --from <path-to-external-SKILL.md>
#   build.sh from-pattern   # alpha: passthrough to ao flywheel close-loop
#
# Always runs skill-auditor on the new skill as a self-check before declaring success.

set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
INIT_SH="$SCRIPT_DIR/init.sh"
AUDITOR_SH="$REPO_ROOT/skills/skill-auditor/scripts/audit.sh"

usage() {
  cat <<EOF
Usage:
  $0 from-scratch <skill-name>
  $0 from-template <skill-name> --like <existing-skill>
  $0 absorb-external <skill-name> --from <path-to-external-SKILL.md>
  $0 from-pattern    # alpha: passthrough to ao flywheel close-loop

Modes:
  from-scratch     Interactive scaffold from canonical template
  from-template    Copy structure from a sibling skill
  absorb-external  Wrap an external SKILL.md in AgentOps frontmatter
  from-pattern     ALPHA — delegates to 'ao flywheel close-loop'.
                   Outputs at .agents/knowledge/promoted/, NOT shaped as SKILL.md drafts.
                   Use from-scratch or absorb-external for SKILL.md output today.
EOF
  exit 2
}

[[ $# -lt 1 ]] && usage

MODE="$1"
shift

case "$MODE" in
  from-pattern)
    # Alpha passthrough — explicitly documented in SKILL.md
    echo "[skill-builder] from-pattern is ALPHA — delegating to 'ao flywheel close-loop'"
    echo "[skill-builder] Output will NOT be a SKILL.md draft; it lands at .agents/knowledge/promoted/"
    exec ao flywheel close-loop "$@"
    ;;

  from-scratch)
    [[ $# -lt 1 ]] && { echo "Error: from-scratch requires <skill-name>" >&2; usage; }
    SKILL_NAME="$1"; shift
    bash "$INIT_SH" --interactive "$SKILL_NAME" "$@"
    ;;

  from-template)
    [[ $# -lt 1 ]] && { echo "Error: from-template requires <skill-name>" >&2; usage; }
    SKILL_NAME="$1"; shift
    bash "$INIT_SH" --like-flag-mode "$SKILL_NAME" "$@"
    ;;

  absorb-external)
    [[ $# -lt 1 ]] && { echo "Error: absorb-external requires <skill-name>" >&2; usage; }
    SKILL_NAME="$1"; shift
    bash "$INIT_SH" --absorb "$SKILL_NAME" "$@"
    ;;

  *)
    echo "Error: unknown mode '$MODE'" >&2
    usage
    ;;
esac

# Post-build self-audit (mandatory per Critical Constraints)
NEW_SKILL_DIR="$REPO_ROOT/skills/$SKILL_NAME"
if [[ ! -d "$NEW_SKILL_DIR" ]]; then
  echo "[skill-builder] ERROR: expected $NEW_SKILL_DIR to exist after init.sh" >&2
  exit 1
fi

# The build report (written by init.sh) carries audit_pass=null as a pre-audit
# placeholder. Patch it to the REAL audit outcome here so the report records what
# actually happened and stays schema-valid (build-report.json requires
# audit_pass to be a boolean). Without this the report's audit_pass was always
# null — the original defect this fixes (age-fix-skill-factory-mcc).
BUILD_REPORT="$REPO_ROOT/.agents/audits/${SKILL_NAME}-build.json"

# patch_audit_pass <true|false> — record the audit outcome in the build report.
# Never fails the build: a missing report or absent jq/python3 only warns.
patch_audit_pass() {
  [[ -f "$BUILD_REPORT" ]] || return 0
  local val="$1" tmp
  # Create the temp in the report's OWN directory so the mv is an atomic
  # same-filesystem rename (a cross-device mv can degrade to a non-atomic copy
  # and corrupt the report on failure).
  tmp="$(mktemp "$(dirname "$BUILD_REPORT")/.audit-patch.XXXXXX")" || return 0
  if command -v jq >/dev/null 2>&1; then
    # Fold the mv into the tested condition so a failed write only WARNs (never
    # aborts the build under set -e).
    if jq --argjson ap "$val" '.audit_pass = $ap' "$BUILD_REPORT" >"$tmp" 2>/dev/null \
       && mv "$tmp" "$BUILD_REPORT" 2>/dev/null; then
      :
    else
      rm -f "$tmp"; echo "[skill-builder] WARN: could not patch audit_pass in $BUILD_REPORT" >&2
    fi
  elif command -v python3 >/dev/null 2>&1; then
    if python3 - "$BUILD_REPORT" "$val" >"$tmp" 2>/dev/null <<'PY' && mv "$tmp" "$BUILD_REPORT" 2>/dev/null
import json, sys
d = json.load(open(sys.argv[1]))
d["audit_pass"] = (sys.argv[2] == "true")
json.dump(d, sys.stdout, indent=2)
PY
    then
      :
    else
      rm -f "$tmp"; echo "[skill-builder] WARN: could not patch audit_pass in $BUILD_REPORT" >&2
    fi
  else
    rm -f "$tmp"; echo "[skill-builder] WARN: no jq/python3 to record audit_pass in $BUILD_REPORT" >&2
  fi
  return 0
}

if [[ -x "$AUDITOR_SH" ]]; then
  echo ""
  echo "[skill-builder] Running self-audit on $NEW_SKILL_DIR..."
  if bash "$AUDITOR_SH" "$NEW_SKILL_DIR"; then
    patch_audit_pass true
    echo "[skill-builder] Self-audit PASS or WARN — build complete (audit_pass=true)"
  else
    # Record the failure before aborting so the report reflects reality.
    patch_audit_pass false
    echo "[skill-builder] Self-audit FAIL — build aborted (audit_pass=false)" >&2
    exit 1
  fi
else
  # An unaudited build cannot claim a pass: record false rather than leaving the
  # null placeholder (which would be schema-invalid and read as "audited").
  patch_audit_pass false
  echo "[skill-builder] WARN: skill-auditor not found at $AUDITOR_SH; skipping self-audit (audit_pass=false)" >&2
fi

#!/usr/bin/env bash
# init.sh — materialize a new skill from the canonical template
# Invoked by build.sh; not typically called directly.
#
# Usage:
#   init.sh --interactive <skill-name>
#   init.sh --like-flag-mode <skill-name> --like <source-skill>
#   init.sh --absorb <skill-name> --from <path-to-external-SKILL.md>

set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
TEMPLATE_REF="$REPO_ROOT/skills/skill-builder/references/skill-template.md"

[[ -f "$TEMPLATE_REF" ]] || { echo "init.sh: missing $TEMPLATE_REF" >&2; exit 1; }

MODE="${1:?usage: init.sh --interactive|--like-flag-mode|--absorb <name> [opts]}"
shift

SKILL_NAME="${1:?missing <skill-name>}"
shift

# Validate slug
[[ "$SKILL_NAME" =~ ^[a-z][a-z0-9-]*$ ]] || {
  echo "init.sh: skill name '$SKILL_NAME' must be lowercase-hyphen (e.g. my-skill)" >&2
  exit 1
}

NEW_DIR="$REPO_ROOT/skills/$SKILL_NAME"
NEW_SKILL_MD="$NEW_DIR/SKILL.md"
[[ -e "$NEW_DIR" ]] && { echo "init.sh: $NEW_DIR already exists; aborting" >&2; exit 1; }

mkdir -p "$NEW_DIR/scripts"

# --- Per-mode population --------------------------------------------------
case "$MODE" in
  --interactive)
    # Minimal non-blocking defaults; skip prompts in CI by reading env vars
    TIER="${SKILL_TIER:-execution}"
    DEPS="${SKILL_DEPS:-[]}"
    INTENT_MODE="${SKILL_INTENT_MODE:-task}"
    ;;

  --like-flag-mode)
    LIKE_FLAG="${1:-}"; SOURCE_SKILL="${2:-}"
    [[ "$LIKE_FLAG" == "--like" && -n "$SOURCE_SKILL" ]] || {
      echo "init.sh --like-flag-mode requires '--like <source-skill>'" >&2
      exit 1
    }
    SOURCE_DIR="$REPO_ROOT/skills/$SOURCE_SKILL"
    [[ -f "$SOURCE_DIR/SKILL.md" ]] || {
      echo "init.sh: source skill $SOURCE_DIR/SKILL.md not found" >&2
      exit 1
    }
    # Extract frontmatter values from source for sane defaults
    TIER="$(awk '/^---$/{n++;next} n==1 && /^[ ]+tier:/{print $2; exit}' "$SOURCE_DIR/SKILL.md")"
    TIER="${TIER:-execution}"
    DEPS="[]"
    INTENT_MODE="$(awk '/^---$/{n++;next} n==1 && /^[ ]+mode:/{print $2; exit}' "$SOURCE_DIR/SKILL.md")"
    INTENT_MODE="${INTENT_MODE:-task}"
    ;;

  --absorb)
    FROM_FLAG="${1:-}"; SOURCE_PATH="${2:-}"
    [[ "$FROM_FLAG" == "--from" && -n "$SOURCE_PATH" ]] || {
      echo "init.sh --absorb requires '--from <path-to-external-SKILL.md>'" >&2
      exit 1
    }
    [[ -f "$SOURCE_PATH" ]] || { echo "init.sh: external SKILL.md not found at $SOURCE_PATH" >&2; exit 1; }
    TIER="${SKILL_TIER:-execution}"
    DEPS="[]"
    INTENT_MODE="task"
    ;;

  *)
    echo "init.sh: unknown mode '$MODE'" >&2
    exit 2
    ;;
esac

# --- Render frontmatter + skeleton ---------------------------------------
cat > "$NEW_SKILL_MD" <<EOF
---
name: $SKILL_NAME
description: |
  <one-line: verb + object + domain>

  **Use when:**
  - <Trigger 1>
  - <Trigger 2>

  **Triggers:** "<trigger phrase 1>", "<trigger phrase 2>"

  **Not ideal for:**
  - <Anti-scenario 1>
skill_api_version: 1
context:
  window: fork
  intent:
    mode: $INTENT_MODE
  sections:
    exclude: [HISTORY]
  intel_scope: topic
metadata:
  tier: $TIER
  dependencies: $DEPS
  stability: experimental
output_contract: "TODO: path to schema or output description"
---

# /$SKILL_NAME — <Title matching slug>

<1-2 sentence purpose paragraph>

## Overview

<What this skill does, why it matters, and when to use it>

## ⚠️ Critical Constraints

- **Rule 1:** <constraint>. **Why:** <rationale>

## Workflow

### Phase 1: <name>

<instructions>

**Checkpoint:** <what to confirm before next phase>

## Output Specification

**Format:** <markdown | json | excel | etc.>
**Filename:** <naming convention>
**Structure:** <key sections / fields>

## Quality Rubric

- [ ] <Check 1>
- [ ] <Check 2>
- [ ] <Check 3>

## Examples

\`\`\`bash
/$SKILL_NAME <example-args>
\`\`\`

## Troubleshooting

| Problem | Cause | Solution |
|---------|-------|----------|

## See Also

- [skill-auditor](../skill-auditor/SKILL.md) — audit this skill before declaring stable
EOF

# --- Mode-specific content injection -------------------------------------
if [[ "$MODE" == "--absorb" ]]; then
  # Append a "Source" reference section pointing at the absorbed external doc
  cat >> "$NEW_SKILL_MD" <<EOF

## References

- Source absorbed from: \`$SOURCE_PATH\`
EOF
fi

# --- Companion files -----------------------------------------------------
cat > "$NEW_DIR/scripts/validate.sh" <<'EOF'
#!/usr/bin/env bash
# validate.sh — minimal self-validation
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
REPO_ROOT="$(cd "$SKILL_DIR/../.." && pwd)"
exec bash "$REPO_ROOT/skills/skill-auditor/scripts/audit.sh" "$SKILL_DIR"
EOF
chmod +x "$NEW_DIR/scripts/validate.sh"
chmod +x "$NEW_DIR" 2>/dev/null || true

# --- Codex parity (slim frontmatter + prompt.md) -------------------------
CODEX_DIR="$REPO_ROOT/skills-codex/$SKILL_NAME"
mkdir -p "$CODEX_DIR"

# Try /converter if present, otherwise hand-build
CONVERTER="$REPO_ROOT/skills/converter/scripts/convert.sh"
if [[ -x "$CONVERTER" ]]; then
  bash "$CONVERTER" "skills/$SKILL_NAME" codex 2>/dev/null || {
    echo "init.sh: converter failed; falling back to hand-built codex artifacts" >&2
  }
fi

# Hand-build codex SKILL.md (slim frontmatter — NO skill_api_version per learning 2026-05-03)
if [[ ! -f "$CODEX_DIR/SKILL.md" ]]; then
  cat > "$CODEX_DIR/SKILL.md" <<EOF
---
name: $SKILL_NAME
description: <copy from skills/$SKILL_NAME/SKILL.md description>
---

# /$SKILL_NAME

See \`skills/$SKILL_NAME/SKILL.md\` for the canonical specification.

## Codex Execution Profile

See \`prompt.md\` in this directory.
EOF
fi

# Always trim skill_api_version from codex SKILL.md if present
if grep -q "^skill_api_version:" "$CODEX_DIR/SKILL.md"; then
  sed -i.bak '/^skill_api_version:/d' "$CODEX_DIR/SKILL.md" && rm -f "$CODEX_DIR/SKILL.md.bak"
fi

# Hand-build prompt.md
if [[ ! -f "$CODEX_DIR/prompt.md" ]]; then
  cat > "$CODEX_DIR/prompt.md" <<EOF
# Execution Profile: $SKILL_NAME

You are running /$SKILL_NAME.

See \`SKILL.md\` in this directory for full specification, OR
read \`skills/$SKILL_NAME/SKILL.md\` in the host repo for the canonical document.

Workflow:
1. Read the user's request
2. Apply the skill's Workflow section
3. Produce output per the Output Specification
4. Self-check against the Quality Rubric
EOF
fi

# --- Build report --------------------------------------------------------
BUILD_REPORT="$REPO_ROOT/.agents/audits/${SKILL_NAME}-build.json"
mkdir -p "$(dirname "$BUILD_REPORT")"
cat > "$BUILD_REPORT" <<EOF
{
  "mode": "${MODE#--}",
  "skill_name": "$SKILL_NAME",
  "files_created": [
    "skills/$SKILL_NAME/SKILL.md",
    "skills/$SKILL_NAME/scripts/validate.sh",
    "skills-codex/$SKILL_NAME/SKILL.md",
    "skills-codex/$SKILL_NAME/prompt.md"
  ],
  "audit_pass": null,
  "warnings": ["v1 skeleton — manual content fill required for description, constraints, workflow"]
}
EOF

# --- New-skill plumbing (ag-cw2y): make the scaffold one-shot-green ----------
# The local/CI gates that silently tripped /burndown #600 are pre-empted here:
# 1. Dispositions row — else heal.sh Check 12 (MISSING_DISPOSITION).
if [[ -f "$REPO_ROOT/scripts/append-skill-disposition.sh" ]]; then
  bash "$REPO_ROOT/scripts/append-skill-disposition.sh" "$SKILL_NAME" "$REPO_ROOT" \
    || echo "init.sh: WARN could not append dispositions row — add one manually" >&2
fi
# 2. Narrative skill counts — --fix-counts bumps the "N checked-in skills" tokens
#    in the domain-map + bdd Gherkin so the new skill doesn't trip registry-drift.
if [[ -x "$REPO_ROOT/scripts/check-registry-drift.sh" ]]; then
  bash "$REPO_ROOT/scripts/check-registry-drift.sh" --fix-counts >/dev/null 2>&1 \
    || echo "init.sh: WARN registry-drift --fix-counts could not run — bump counts manually" >&2
fi
# 3. Codex override catalog entry — else validate-codex-override-coverage fails
#    ("source skill missing from Codex catalog"). Default parity_only (derived).
if [[ -f "$REPO_ROOT/scripts/append-codex-override-entry.sh" ]]; then
  bash "$REPO_ROOT/scripts/append-codex-override-entry.sh" "$SKILL_NAME" "$REPO_ROOT" \
    || echo "init.sh: WARN could not add codex override catalog entry — add one manually" >&2
fi
# 4. registry.json SKU catalog — else contracts-sync + correctness(ubuntu) BOTH
#    fail ("registry.json is stale" / "SKU_CATALOG: DRIFT"). This is the 5th
#    one-shot-green surface ag-cw2y missed; it cost /burndown #600 a 2nd
#    fix-and-repush (ag-ekyq). MUST run last — it scans the whole skills/ tree,
#    so the new skeleton must already exist on disk.
if [[ -f "$REPO_ROOT/scripts/generate-registry.sh" ]]; then
  bash "$REPO_ROOT/scripts/generate-registry.sh" >/dev/null 2>&1 \
    || echo "init.sh: WARN could not regen registry.json — run scripts/generate-registry.sh manually" >&2
fi

echo "init.sh: created skill skeleton at $NEW_DIR"
echo "init.sh: codex parity at $CODEX_DIR"
echo "init.sh: build report at $BUILD_REPORT"
echo "init.sh: dispositions row + narrative counts scaffolded (refine the placeholder row)"

#!/usr/bin/env python3
"""Corpus-wide skill description trigger scanner.

The per-skill `skill-auditor` runs `description-has-triggers` / `trigger-clarity`
as WARN checks, so a missing trigger phrase never blocks a merge and the gap
accumulates silently across the corpus. This scanner is the corpus-wide
companion: it walks every `skills/*/SKILL.md`, applies the *same* three-form
trigger detection as `skill-auditor/scripts/audit.sh`, scores each description,
and emits a prioritized remediation list with a suggested `Triggers:` stub for
each skill that lacks one.

Discovery in the runtime is pure LLM reasoning over the `description` field, so
a missing trigger phrase is a material skill-selection risk, not cosmetic. See
`skills/skill-builder/references/skill-authoring-standard.md`.

Usage:
    python3 scan_descriptions.py [SKILLS_DIR] [--json] [--strict] [--quiet]
    python3 scan_descriptions.py [SKILLS_DIR] --probe "<phrase>" [--json]
    python3 scan_descriptions.py [SKILLS_DIR] --list-probes

Probe mode (`--probe "<phrase>"`) ranks every skill against the phrase using
ONLY the deterministic lexical ranker below — no live model, no `claude -p`, no
network — and asserts the skill that DECLARES the phrase in its
`trigger_probes:` frontmatter list ranks #1. Output is byte-stable across runs.

Exit codes:
    0  every description carries a trigger (or --strict not set);
       in --probe mode: the declaring skill ranks #1 for the phrase
    1  one or more descriptions lack a trigger AND --strict is set;
       in --probe mode: the declaring skill does NOT rank #1
    2  usage error (skills dir not found, or no skill declares the phrase)
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from dataclasses import dataclass, field
from pathlib import Path

# Phrases that count as an explicit trigger marker, mirroring the regex in
# skill-auditor/scripts/audit.sh (Form b). Keep these in sync with the auditor.
TRIGGER_MARKERS = (
    "**Use when:",
    "**Triggers:",
    "**Perfect for:",
    "Use when:",
    "Triggers:",
)

# Stop-words stripped when deriving a suggested trigger stub from the name.
_STOPWORDS = frozenset({"the", "a", "an", "for", "and", "to", "of", "with"})


@dataclass
class SkillScan:
    """Result of scanning one SKILL.md for trigger quality."""

    name: str
    path: Path
    description: str
    has_trigger: bool
    forms: list[str] = field(default_factory=list)
    score: int = 0
    suggestion: str = ""

    def to_dict(self) -> dict:
        """Return a JSON-serializable view for --json / robot mode."""
        return {
            "name": self.name,
            "path": str(self.path),
            "has_trigger": self.has_trigger,
            "forms": self.forms,
            "score": self.score,
            "suggestion": self.suggestion,
        }


def split_frontmatter(text: str) -> tuple[str, str]:
    """Split a SKILL.md into (frontmatter, body). Empty frontmatter if absent."""
    if not text.startswith("---"):
        return "", text
    parts = text.split("\n---", 1)
    if len(parts) != 2:
        return "", text
    frontmatter = parts[0][len("---") :]
    body = parts[1].lstrip("-\n")
    return frontmatter, body


def parse_field(frontmatter: str, key: str) -> str:
    """Extract a single top-level scalar field's first line from frontmatter."""
    match = re.search(rf"^{re.escape(key)}:\s*(.*)$", frontmatter, re.MULTILINE)
    return match.group(1).strip() if match else ""


def description_block(frontmatter: str) -> str:
    """Return the full description value, including folded/literal continuations."""
    lines = frontmatter.splitlines()
    out: list[str] = []
    capturing = False
    for line in lines:
        if line.startswith("description:"):
            capturing = True
            out.append(line)
            continue
        if capturing:
            # A new top-level key (no leading whitespace, ends the block).
            if re.match(r"^[A-Za-z_-]+:", line):
                break
            out.append(line)
    return "\n".join(out)


def count_trigger_list(frontmatter: str) -> int:
    """Count items under a `metadata.triggers:` (or `triggers:`) YAML list."""
    lines = frontmatter.splitlines()
    in_list = False
    count = 0
    for line in lines:
        if re.match(r"^\s+triggers:\s*$", line):
            in_list = True
            continue
        if in_list:
            if re.match(r"^\s+-\s+", line):
                count += 1
                continue
            if re.match(r"^\s*[A-Za-z_-]+:", line):
                break
    return count


def split_flow_items(inner: str) -> list[str]:
    """Split a simple YAML flow sequence body without breaking quoted commas."""
    items: list[str] = []
    current: list[str] = []
    quote = ""
    i = 0
    while i < len(inner):
        char = inner[i]
        if quote:
            if char == "\\" and quote == '"' and i + 1 < len(inner):
                current.append(inner[i + 1])
                i += 2
                continue
            if char == quote:
                if quote == "'" and i + 1 < len(inner) and inner[i + 1] == "'":
                    current.append("'")
                    i += 2
                    continue
                quote = ""
            else:
                current.append(char)
        elif char in ("'", '"'):
            quote = char
        elif char == ",":
            items.append("".join(current))
            current = []
        else:
            current.append(char)
        i += 1
    items.append("".join(current))
    return items


def parse_trigger_probes(frontmatter: str) -> list[str]:
    """Return the items under a top-level `trigger_probes:` YAML list.

    Supports the flow form (`trigger_probes: ["a", "b"]`) and the block form
    (`trigger_probes:` followed by indented `- item` lines). Quotes are
    stripped; order is preserved. Purely lexical — no YAML library required so
    the scanner stays dependency-free and deterministic.
    """
    lines = frontmatter.splitlines()
    probes: list[str] = []
    for idx, line in enumerate(lines):
        flow = re.match(r"^trigger_probes:\s*\[(.*)\]\s*$", line)
        if flow:
            inner = flow.group(1).strip()
            if inner:
                for item in split_flow_items(inner):
                    cleaned = item.strip().strip("'\"").strip()
                    if cleaned:
                        probes.append(cleaned)
            return probes
        if re.match(r"^trigger_probes:\s*$", line):
            for follow in lines[idx + 1 :]:
                item = re.match(r"^\s+-\s+(.*)$", follow)
                if item:
                    cleaned = item.group(1).strip().strip("'\"").strip()
                    if cleaned:
                        probes.append(cleaned)
                    continue
                if re.match(r"^\S", follow):
                    break
            return probes
    return probes


_WORD_RE = re.compile(r"[a-z0-9]+")


def _tokens(text: str) -> list[str]:
    """Lowercase alphanumeric tokens, in order, for deterministic scoring."""
    return _WORD_RE.findall(text.lower())


def lexical_score(phrase: str, scan: SkillScan) -> tuple:
    """Deterministic lexical relevance of one skill to a probe phrase.

    Pure token math over the skill's own SEARCHABLE TEXT (name + description) —
    no model, no network, and deliberately NOT a function of the skill's
    `trigger_probes:` declaration. The declaration only identifies *which*
    skill is expected to win; the ranking itself is earned purely by lexical
    overlap, so a skill that stops describing its phrase genuinely drops in
    rank. Returns a tuple sort key (higher is more relevant); ties break by
    name so the ranking is total and byte-stable. Signals, in priority order:

    1. fraction of phrase tokens present in the searchable text (coverage),
    2. raw count of phrase-token hits,
    3. name-token overlap (a phrase word that is also a name word).
    """
    phrase_tokens = _tokens(phrase)
    name_tokens = set(_tokens(scan.name))
    haystack = " ".join([scan.name, scan.description])
    hay_tokens = _tokens(haystack)
    hay_set = set(hay_tokens)

    if phrase_tokens:
        present = sum(1 for t in phrase_tokens if t in hay_set)
        coverage = present / len(phrase_tokens)
        hits = sum(hay_tokens.count(t) for t in set(phrase_tokens))
    else:
        coverage = 0.0
        hits = 0
    name_overlap = sum(1 for t in set(phrase_tokens) if t in name_tokens)
    return (coverage, hits, name_overlap)


@dataclass
class ProbeResult:
    """One skill's deterministic rank for a probe phrase."""

    name: str
    score_key: tuple
    declares_phrase: bool

    def to_dict(self) -> dict:
        """JSON-serializable view (score_key as a list for stable output)."""
        return {
            "name": self.name,
            "score_key": list(self.score_key),
            "declares_phrase": self.declares_phrase,
        }


def probe_corpus(skills_dir: Path, phrase: str) -> list[ProbeResult]:
    """Rank every skill against `phrase` using the deterministic lexical ranker.

    Sorted by descending score, then ascending name — a total, byte-stable
    order. Each result records whether that skill declares the phrase in its
    `trigger_probes:` list.
    """
    ranked: list[ProbeResult] = []
    for skill_md in sorted(skills_dir.glob("*/SKILL.md")):
        scan = scan_skill(skill_md)
        if scan is None:
            continue
        frontmatter, _ = split_frontmatter(skill_md.read_text(encoding="utf-8"))
        probes = parse_trigger_probes(frontmatter)
        key = lexical_score(phrase, scan)
        declares = phrase.strip().lower() in {p.strip().lower() for p in probes}
        ranked.append(ProbeResult(name=scan.name, score_key=key, declares_phrase=declares))

    def sort_key(result: ProbeResult) -> tuple:
        # Descending score (negate the numeric components), ascending name.
        return (tuple(-x for x in result.score_key), result.name)

    ranked.sort(key=sort_key)
    return ranked


def render_probe(phrase: str, ranked: list[ProbeResult]) -> str:
    """Render a deterministic human-readable probe report."""
    declaring = [r.name for r in ranked if r.declares_phrase]
    lines = [
        "# Trigger probe",
        "",
        f"- Phrase: {phrase!r}",
        f"- Skills ranked: {len(ranked)}",
        f"- Declaring skills: {', '.join(declaring) if declaring else '(none)'}",
        "",
        "## Ranking (deterministic lexical, no model)",
        "",
        "| Rank | Skill | Declares | Score key |",
        "|------|-------|----------|-----------|",
    ]
    for i, r in enumerate(ranked, start=1):
        mark = "yes" if r.declares_phrase else ""
        lines.append(f"| {i} | `{r.name}` | {mark} | {list(r.score_key)} |")
    return "\n".join(lines)


def detect_trigger(text: str, frontmatter: str) -> list[str]:
    """Return the trigger forms present, matching audit.sh's three forms.

    Form a: `description: |` literal block scalar.
    Form b: an explicit marker (`Use when:` / `Triggers:` / `Perfect for:`)
            anywhere in the file, mirroring audit.sh's whole-file grep.
    Form c: a `triggers:` YAML list with three or more items.
    """
    forms: list[str] = []
    desc_value = parse_field(frontmatter, "description")
    if desc_value.startswith("|"):
        forms.append("block-scalar")
    if any(marker in text for marker in TRIGGER_MARKERS):
        forms.append("explicit-marker")
    if count_trigger_list(frontmatter) >= 3:
        forms.append("triggers-list")
    return forms


def score_trigger(description: str) -> int:
    """Score 0-3, mirroring skill-auditor/scripts/score_agentops_skill.py."""
    signals = sum(
        marker.lower().strip("*").rstrip(":") in description.lower()
        for marker in ("Use when", "Triggers", "Perfect for")
    )
    return min(3, int(bool(description.strip())) + signals)


def suggest_triggers(name: str, description: str) -> str:
    """Derive a deterministic `Triggers:` stub from the skill name + first verb."""
    tokens = [t for t in name.split("-") if t not in _STOPWORDS]
    spaced = " ".join(tokens)
    first_sentence = re.split(r"[.\n]", description.strip(), maxsplit=1)[0]
    words = first_sentence.split()
    verb = words[0].lower().strip("'\"") if words else ""
    candidates = [name, spaced]
    # Only add a verb phrase when the verb adds a word not already in the name.
    if verb and tokens and verb not in tokens:
        candidates.append(f"{verb} {tokens[-1]}")
    seen: list[str] = []
    for phrase in candidates:
        cleaned = " ".join(dict.fromkeys(phrase.strip().lower().split()))
        if cleaned and cleaned not in seen:
            seen.append(cleaned)
    quoted = ", ".join(f'"{p}"' for p in seen)
    return f"Triggers: {quoted}"


def scan_skill(skill_md: Path) -> SkillScan | None:
    """Scan one SKILL.md. Returns None if the file is unreadable/empty."""
    try:
        text = skill_md.read_text(encoding="utf-8")
    except OSError:
        return None
    frontmatter, _body = split_frontmatter(text)
    name = parse_field(frontmatter, "name") or skill_md.parent.name
    description = description_block(frontmatter)
    forms = detect_trigger(text, frontmatter)
    has_trigger = bool(forms)
    scan = SkillScan(
        name=name,
        path=skill_md,
        description=description,
        has_trigger=has_trigger,
        forms=forms,
        score=score_trigger(description),
    )
    if not has_trigger:
        scan.suggestion = suggest_triggers(name, parse_field(frontmatter, "description"))
    return scan


def scan_corpus(skills_dir: Path) -> list[SkillScan]:
    """Scan every `<skill>/SKILL.md` under skills_dir, sorted by name."""
    results: list[SkillScan] = []
    for skill_md in sorted(skills_dir.glob("*/SKILL.md")):
        scan = scan_skill(skill_md)
        if scan is not None:
            results.append(scan)
    return results


def list_probe_pairs(skills_dir: Path) -> list[tuple[str, str]]:
    """Return every (skill-id, probe-phrase) pair declared in the corpus.

    The skill-id is the SKILL.md's parent directory name (matching what the
    rest of the tooling keys on). Phrases come from the SAME `parse_trigger_probes`
    parser used by --probe, so any downstream consumer that wants the parsed
    pairs reuses this one parser instead of reimplementing the YAML walk.
    Sorted by (skill-id, phrase) for byte-stable output.
    """
    pairs: list[tuple[str, str]] = []
    for skill_md in sorted(skills_dir.glob("*/SKILL.md")):
        try:
            text = skill_md.read_text(encoding="utf-8")
        except OSError:
            continue
        frontmatter, _body = split_frontmatter(text)
        sid = skill_md.parent.name
        for phrase in parse_trigger_probes(frontmatter):
            pairs.append((sid, phrase))
    return sorted(set(pairs))


def render_markdown(results: list[SkillScan]) -> str:
    """Render a human-readable remediation report."""
    total = len(results)
    missing = [r for r in results if not r.has_trigger]
    lines = [
        "# Skill description trigger scan",
        "",
        f"- Skills scanned: **{total}**",
        f"- With trigger marker: **{total - len(missing)}**",
        f"- Missing trigger marker: **{len(missing)}** "
        f"({(len(missing) / total * 100):.0f}%)" if total else "- Missing: 0",
        "",
    ]
    if not missing:
        lines.append("All descriptions carry a trigger marker. ✅")
        return "\n".join(lines)
    lines += [
        "## Remediation backlog (add a trigger marker to each)",
        "",
        "| Skill | Score | Suggested stub |",
        "|-------|-------|----------------|",
    ]
    for r in missing:
        lines.append(f"| `{r.name}` | {r.score}/3 | `{r.suggestion}` |")
    return "\n".join(lines)


def _run_probe(skills_dir: Path, phrase: str, *, json_mode: bool, quiet: bool) -> int:
    """Drive --probe: rank the corpus and assert the declaring skill wins.

    Returns 2 if no skill declares the phrase (a usage error — nothing to
    assert), 0 if the declaring skill ranks #1, 1 otherwise.
    """
    ranked = probe_corpus(skills_dir, phrase)
    declaring = [r for r in ranked if r.declares_phrase]
    top = ranked[0] if ranked else None
    declarer_is_top = bool(top and top.declares_phrase)

    if json_mode:
        payload = {
            "phrase": phrase,
            "ranked": len(ranked),
            "declaring": [r.name for r in declaring],
            "top": top.name if top else None,
            "declarer_is_top": declarer_is_top,
            "skills": [r.to_dict() for r in ranked],
        }
        print(json.dumps(payload, indent=2, sort_keys=True))
    elif not quiet:
        print(render_probe(phrase, ranked))

    if not declaring:
        if not json_mode:
            print(f"error: no skill declares the probe phrase: {phrase!r}", file=sys.stderr)
        return 2
    return 0 if declarer_is_top else 1


def main(argv: list[str] | None = None) -> int:
    """CLI entry point."""
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        "skills_dir",
        nargs="?",
        default="skills",
        help="Path to the skills/ directory (default: skills)",
    )
    parser.add_argument("--json", action="store_true", help="Emit JSON (robot mode)")
    parser.add_argument(
        "--strict", action="store_true", help="Exit 1 if any description lacks a trigger"
    )
    parser.add_argument("--quiet", action="store_true", help="Suppress the human report")
    parser.add_argument(
        "--probe",
        metavar="PHRASE",
        default=None,
        help="Deterministic lexical probe: assert the skill that declares PHRASE "
        "in trigger_probes: ranks #1 (no live model, no network)",
    )
    parser.add_argument(
        "--list-probes",
        action="store_true",
        help="Emit every declared (skill-id<TAB>phrase) pair, one per line, using "
        "the SAME parser as --probe (so consumers don't reimplement the YAML walk)",
    )
    args = parser.parse_args(argv)

    skills_dir = Path(args.skills_dir)
    if not skills_dir.is_dir():
        print(f"error: skills dir not found: {skills_dir}", file=sys.stderr)
        return 2

    if args.list_probes:
        for sid, phrase in list_probe_pairs(skills_dir):
            print(f"{sid}\t{phrase}")
        return 0

    if args.probe is not None:
        return _run_probe(skills_dir, args.probe, json_mode=args.json, quiet=args.quiet)

    results = scan_corpus(skills_dir)
    missing = [r for r in results if not r.has_trigger]

    if args.json:
        payload = {
            "scanned": len(results),
            "missing": len(missing),
            "skills": [r.to_dict() for r in results],
        }
        print(json.dumps(payload, indent=2))
    elif not args.quiet:
        print(render_markdown(results))

    return 1 if (args.strict and missing) else 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env bash
# validate.sh — self-validation for skill-builder
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
REPO_ROOT="$(cd "$SKILL_DIR/../.." && pwd)"

# Run heal-skill structural check on ourselves by exit code.
bash "$REPO_ROOT/skills/heal-skill/scripts/heal.sh" --check --strict "$SKILL_DIR"

# Verify required artifacts exist
for f in SKILL.md scripts/build.sh scripts/init.sh references/skill-template.md schemas/build-report.json; do
  [[ -f "$SKILL_DIR/$f" ]] || { echo "validate.sh: missing $SKILL_DIR/$f" >&2; exit 1; }
done

# Verify scale-factory lessons stay encoded.
for phrase in \
  "heal-skill --check --strict" \
  "One skill directory = one writer" \
  "git status" \
  "Clean-room includes names" \
  "Workflow tool"; do
  grep -q "$phrase" "$SKILL_DIR/SKILL.md" "$SKILL_DIR/references/agentops-skill-factory.md" || {
    echo "validate.sh: missing scale-factory lesson: $phrase" >&2
    exit 1
  }
done

# Verify SKILL.md is within churn budget
LINES="$(wc -l < "$SKILL_DIR/SKILL.md")"
if (( LINES > 250 )); then
  echo "validate.sh: SKILL.md is $LINES lines (>250 budget per finding f-2026-05-01-025)" >&2
  exit 1
fi

# Verify build.sh and init.sh are executable
for s in scripts/build.sh scripts/init.sh; do
  [[ -x "$SKILL_DIR/$s" ]] || chmod +x "$SKILL_DIR/$s"
done

echo "validate.sh: skill-builder PASS ($LINES lines, all artifacts present)"