@cubis/foundry 0.3.63 → 0.3.65

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/skill-authoring/references/foundry-platform-parity.md

@@ -0,0 +1,50 @@
+# Foundry Platform Parity
+
+Use this reference when a skill has to work cleanly across generated platform bundles.
+
+## Canonical Authoring Rule
+
+- Author the real skill only under `workflows/skills/<id>`.
+- Generated mirrors are derived artifacts, not the source of truth.
+- If a mirror looks wrong, fix the canonical skill or the generator, then regenerate.
+
+## Packaging Rules
+
+- Keep `SKILL.md` as the only top-level markdown entry file.
+- Place sidecars under `references/`, `steering/`, or `templates/`.
+- Do not keep `POWER.md` in canonical skills or mirrored bundles.
+- Keep links relative to the skill root so the same content survives mirror relocation.
+
+## Platform Notes
+
+### Codex
+
+- Full canonical skill content is mirrored into `.agents/skills`.
+- Compatibility wrappers may exist for workflows and agents, but skills remain normal packages.
+
+### Antigravity
+
+- Skills are mirrored into `.agent/skills`.
+- Route-first rule text still expects the same `SKILL.md` plus selective sidecar loading.
+
+### Copilot
+
+- Copilot-facing skills must keep only supported frontmatter keys after sanitization.
+- The canonical skill may keep richer `metadata`, but the generated mirror should rely on Foundry's sanitization rather than hand-authored Copilot-only fields.
+- Workspace MCP should stay in `.vscode/mcp.json`.
+
+### Cursor and Windsurf
+
+- These mirrors follow the same filtered bundle rules as Copilot.
+- Duplicate top-level markdown files and stale sidecars will show up here too if the canonical package is sloppy.
+
+## Metadata Guidance
+
+- Required everywhere: `name`, `description`
+- Allowed canonical extensions: `license`, `allowed-tools`, `metadata`, `compatibility`
+- Keep the trigger boundary in `description` sharp enough that route-first loading can direct-load the skill when intent is obvious.
+
+## Routing Guidance
+
+- Do not create platform-specific aliases just to shadow a built-in skill.
+- If a built-in name collides with a Foundry skill, prefer a distinct canonical ID and route authoring intent to it explicitly.

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/skill-authoring/references/foundry-skill-checklist.md

@@ -0,0 +1,45 @@
+# Foundry Skill Checklist
+
+Use this checklist before finishing a skill creation or maintenance task.
+
+## Canonical Package
+
+- Skill folder name is lowercase hyphen-case and under 64 characters.
+- `SKILL.md` exists and has `name` plus `description`.
+- `description` states both when to use the skill and when not to use it.
+- No `POWER.md` exists in the skill directory.
+- No extra top-level markdown files exist besides `SKILL.md`.
+
+## Sidecars
+
+- Every referenced markdown file exists.
+- Referenced markdown files are non-empty.
+- Links are relative from the skill root.
+- `SKILL.md` tells the agent when to load each sidecar instead of listing files without context.
+
+## Scripts
+
+- Only keep scripts that actually remove repetition or improve reliability.
+- Scripts should prefer standard-library dependencies when possible.
+- Script usage is described briefly in `SKILL.md`.
+
+## Routing and Generation
+
+- If the skill changes route behavior, update shared workflow or agent guidance too.
+- Do not edit platform mirrors directly unless the task is fixing the generator itself.
+- Regenerate mirrors and rule assets after canonical changes.
+
+## Validation
+
+Run the smallest relevant validation set:
+
+- `python workflows/skills/<id>/scripts/quick_validate.py workflows/skills/<id>`
+- `npm run test:attributes`
+- `npm run generate:platform-assets`
+- `npm run sync:skill-mirrors`
+
+If the task changes MCP or runtime routing:
+
+- `npm --prefix mcp test`
+- `npm --prefix mcp run build`
+- `node scripts/mcp-http-smoke.mjs <mcp-url>` when a live endpoint is available

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/skill-authoring/scripts/init_skill.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""
+Scaffold a new Foundry canonical skill.
+
+Usage:
+  python init_skill.py <skill-name> [--path workflows/skills] [--resources scripts,references]
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+ALLOWED_RESOURCES = {"scripts", "references", "steering", "templates", "assets"}
+MAX_SKILL_NAME_LENGTH = 64
+
+
+def normalize_skill_name(raw_name: str) -> str:
+    normalized = re.sub(r"[^a-z0-9]+", "-", raw_name.strip().lower())
+    normalized = re.sub(r"-{2,}", "-", normalized).strip("-")
+    return normalized
+
+
+def title_case(skill_name: str) -> str:
+    return " ".join(part.capitalize() for part in skill_name.split("-") if part)
+
+
+def parse_resources(raw_resources: str) -> list[str]:
+    if not raw_resources:
+        return []
+    resources = []
+    seen = set()
+    for item in raw_resources.split(","):
+        value = item.strip()
+        if not value:
+            continue
+        if value not in ALLOWED_RESOURCES:
+            allowed = ", ".join(sorted(ALLOWED_RESOURCES))
+            raise SystemExit(f"Unknown resource type '{value}'. Allowed: {allowed}")
+        if value not in seen:
+            resources.append(value)
+            seen.add(value)
+    return resources
+
+
+def skill_template(skill_name: str) -> str:
+    skill_title = title_case(skill_name)
+    return f"""---
+name: "{skill_name}"
+description: "Use when [TODO: describe the task trigger, expected files or outputs, and clear non-goals]."
+---
+
+# {skill_title}
+
+## Overview
+
+[TODO: Add a short description of what this skill enables.]
+
+## When to Use
+
+- [TODO]
+
+## When Not to Use
+
+- [TODO]
+
+## Core Workflow
+
+1. [TODO]
+2. [TODO]
+3. [TODO]
+
+## References
+
+Load on demand. Do not preload all reference files.
+
+| File | Load when |
+| --- | --- |
+| `references/example.md` | Replace or remove this row after creating real sidecar docs. |
+
+## Rules
+
+- Keep `SKILL.md` concise and move detailed variants to sidecar files.
+- Keep links relative to the skill root.
+- Do not add `POWER.md`.
+"""
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Scaffold a Foundry canonical skill")
+    parser.add_argument("skill_name", help="Requested skill name")
+    parser.add_argument(
+        "--path",
+        default="workflows/skills",
+        help="Root directory that will contain the new skill",
+    )
+    parser.add_argument(
+        "--resources",
+        default="references",
+        help="Comma-separated optional folders to create",
+    )
+    args = parser.parse_args()
+
+    skill_name = normalize_skill_name(args.skill_name)
+    if not skill_name:
+        raise SystemExit("Skill name normalized to an empty value")
+    if len(skill_name) > MAX_SKILL_NAME_LENGTH:
+        raise SystemExit(
+            f"Skill name '{skill_name}' is too long ({len(skill_name)} > {MAX_SKILL_NAME_LENGTH})"
+        )
+
+    target_root = Path(args.path).resolve()
+    skill_dir = target_root / skill_name
+    if skill_dir.exists():
+        raise SystemExit(f"Target skill already exists: {skill_dir}")
+
+    resources = parse_resources(args.resources)
+    skill_dir.mkdir(parents=True, exist_ok=False)
+    (skill_dir / "SKILL.md").write_text(skill_template(skill_name), encoding="utf8")
+
+    for resource in resources:
+        resource_dir = skill_dir / resource
+        resource_dir.mkdir(parents=True, exist_ok=True)
+        if resource == "references":
+            (resource_dir / "example.md").write_text(
+                "# Example Reference\n\nReplace or remove this file once you add real sidecar documentation.\n",
+                encoding="utf8",
+            )
+
+    print(f"[OK] Created skill scaffold: {skill_dir}")
+    print("[NEXT] Replace TODO sections in SKILL.md")
+    print("[NEXT] Add real sidecar files or remove placeholder reference rows")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/skill-authoring/scripts/quick_validate.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""
+Validate a Foundry skill package without external dependencies.
+"""
+
+import re
+import sys
+from pathlib import Path
+
+MAX_SKILL_NAME_LENGTH = 64
+ALLOWED_KEYS = {
+    "name",
+    "description",
+    "license",
+    "allowed-tools",
+    "metadata",
+    "compatibility",
+}
+SIDECAR_DIRS = {"references", "steering", "templates"}
+
+
+def extract_frontmatter(markdown: str):
+    match = re.match(r"^---\n(.*?)\n---\n?", markdown, re.DOTALL)
+    if not match:
+        return None, markdown
+    return match.group(1), markdown[match.end():]
+
+
+def parse_top_level_keys(frontmatter: str):
+    keys = []
+    values = {}
+    for line in frontmatter.splitlines():
+        if not line or line.startswith((" ", "\t")):
+            continue
+        match = re.match(r"^([A-Za-z0-9_-]+)\s*:\s*(.*)$", line)
+        if not match:
+            continue
+        key = match.group(1)
+        raw_value = match.group(2).strip()
+        keys.append(key)
+        values[key] = raw_value.strip("\"'")
+    return keys, values
+
+
+def extract_markdown_targets(markdown: str):
+    stripped = re.sub(r"```[\s\S]*?```", "", markdown)
+    return [match.group(1).strip() for match in re.finditer(r"\[[^\]]+\]\(([^)]+)\)", stripped)]
+
+
+def validate(skill_dir: Path):
+    errors = []
+    skill_md = skill_dir / "SKILL.md"
+    if not skill_md.exists():
+        return ["SKILL.md not found"]
+
+    content = skill_md.read_text(encoding="utf8")
+    frontmatter, _body = extract_frontmatter(content)
+    if not frontmatter:
+        return ["SKILL.md is missing YAML frontmatter"]
+
+    keys, values = parse_top_level_keys(frontmatter)
+    unexpected = sorted(set(keys) - ALLOWED_KEYS)
+    if unexpected:
+        errors.append(
+            "Unexpected frontmatter keys: " + ", ".join(unexpected)
+        )
+
+    name = values.get("name", "").strip()
+    description = values.get("description", "").strip()
+    if not name:
+        errors.append("Missing name in frontmatter")
+    elif not re.fullmatch(r"[a-z0-9-]+", name):
+        errors.append("name must be lowercase hyphen-case")
+    elif "--" in name or name.startswith("-") or name.endswith("-"):
+        errors.append("name cannot start/end with '-' or contain consecutive hyphens")
+    elif len(name) > MAX_SKILL_NAME_LENGTH:
+        errors.append(
+            f"name is too long ({len(name)} > {MAX_SKILL_NAME_LENGTH})"
+        )
+
+    if not description:
+        errors.append("Missing description in frontmatter")
+
+    if (skill_dir / "POWER.md").exists():
+        errors.append("POWER.md must not exist")
+
+    top_level_markdown = sorted(
+        item.name
+        for item in skill_dir.iterdir()
+        if item.is_file() and item.suffix == ".md"
+    )
+    extras = [name for name in top_level_markdown if name != "SKILL.md"]
+    if extras:
+        errors.append(
+            "Extra top-level markdown files found: " + ", ".join(extras)
+        )
+
+    markdown_files = [skill_md]
+    for folder_name in SIDECAR_DIRS:
+        folder = skill_dir / folder_name
+        if not folder.exists():
+            continue
+        markdown_files.extend(sorted(folder.rglob("*.md")))
+
+    for markdown_file in markdown_files:
+        text = markdown_file.read_text(encoding="utf8")
+        if markdown_file != skill_md and not text.strip():
+            errors.append(f"{markdown_file.relative_to(skill_dir)} is empty")
+        for target in extract_markdown_targets(text):
+            if target.startswith(("http://", "https://", "#", "mailto:", "/")):
+                continue
+            target_path = (markdown_file.parent / target.split("#")[0].split("?")[0]).resolve()
+            if not target_path.exists():
+                errors.append(
+                    f"{markdown_file.relative_to(skill_dir)} references missing file {target}"
+                )
+                continue
+            if target_path.suffix == ".md" and not target_path.read_text(encoding="utf8").strip():
+                errors.append(
+                    f"{markdown_file.relative_to(skill_dir)} references empty markdown file {target}"
+                )
+
+    return errors
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("Usage: python quick_validate.py <skill_directory>")
+        return 1
+
+    skill_dir = Path(sys.argv[1]).resolve()
+    if not skill_dir.exists() or not skill_dir.is_dir():
+        print(f"Skill directory not found: {skill_dir}")
+        return 1
+
+    errors = validate(skill_dir)
+    if errors:
+        print("Skill validation failed:")
+        for item in errors:
+            print(f"- {item}")
+        return 1
+
+    print("Skill is valid.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())