@cubis/foundry 0.3.64 → 0.3.66

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/seo-fundamentals/scripts/seo_checker.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+"""
+SEO Checker - Search Engine Optimization Audit
+Checks HTML/JSX/TSX pages for SEO best practices.
+
+PURPOSE:
+    - Verify meta tags, titles, descriptions
+    - Check Open Graph tags for social sharing
+    - Validate heading hierarchy
+    - Check image accessibility (alt attributes)
+
+WHAT IT CHECKS:
+    - HTML files (actual web pages)
+    - JSX/TSX files (React page components)
+    - Only files that are likely PUBLIC pages
+
+Usage:
+    python seo_checker.py <project_path>
+"""
+import sys
+import json
+import re
+from pathlib import Path
+from datetime import datetime
+
+# Fix Windows console encoding
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except:
+    pass
+
+
+# Directories to skip
+SKIP_DIRS = {
+    'node_modules', '.next', 'dist', 'build', '.git', '.github',
+    '__pycache__', '.vscode', '.idea', 'coverage', 'test', 'tests',
+    '__tests__', 'spec', 'docs', 'documentation', 'examples'
+}
+
+# Files to skip (not pages)
+SKIP_PATTERNS = [
+    'config', 'setup', 'util', 'helper', 'hook', 'context', 'store',
+    'service', 'api', 'lib', 'constant', 'type', 'interface', 'mock',
+    '.test.', '.spec.', '_test.', '_spec.'
+]
+
+
+def is_page_file(file_path: Path) -> bool:
+    """Check if this file is likely a public-facing page."""
+    name = file_path.name.lower()
+    stem = file_path.stem.lower()
+    
+    # Skip utility/config files
+    if any(skip in name for skip in SKIP_PATTERNS):
+        return False
+    
+    # Check path - pages in specific directories are likely pages
+    parts = [p.lower() for p in file_path.parts]
+    page_dirs = ['pages', 'app', 'routes', 'views', 'screens']
+    
+    if any(d in parts for d in page_dirs):
+        return True
+    
+    # Filename indicators for pages
+    page_names = ['page', 'index', 'home', 'about', 'contact', 'blog', 
+                  'post', 'article', 'product', 'landing', 'layout']
+    
+    if any(p in stem for p in page_names):
+        return True
+    
+    # HTML files are usually pages
+    if file_path.suffix.lower() in ['.html', '.htm']:
+        return True
+    
+    return False
+
+
+def find_pages(project_path: Path) -> list:
+    """Find page files to check."""
+    patterns = ['**/*.html', '**/*.htm', '**/*.jsx', '**/*.tsx']
+    
+    files = []
+    for pattern in patterns:
+        for f in project_path.glob(pattern):
+            # Skip excluded directories
+            if any(skip in f.parts for skip in SKIP_DIRS):
+                continue
+            
+            # Check if it's likely a page
+            if is_page_file(f):
+                files.append(f)
+    
+    return files[:50]  # Limit to 50 files
+
+
+def check_page(file_path: Path) -> dict:
+    """Check a single page for SEO issues."""
+    issues = []
+    
+    try:
+        content = file_path.read_text(encoding='utf-8', errors='ignore')
+    except Exception as e:
+        return {"file": str(file_path.name), "issues": [f"Error: {e}"]}
+    
+    # Detect if this is a layout/template file (has Head component)
+    is_layout = 'Head>' in content or '<head' in content.lower()
+    
+    # 1. Title tag
+    has_title = '<title' in content.lower() or 'title=' in content or 'Head>' in content
+    if not has_title and is_layout:
+        issues.append("Missing <title> tag")
+    
+    # 2. Meta description
+    has_description = 'name="description"' in content.lower() or 'name=\'description\'' in content.lower()
+    if not has_description and is_layout:
+        issues.append("Missing meta description")
+    
+    # 3. Open Graph tags
+    has_og = 'og:' in content or 'property="og:' in content.lower()
+    if not has_og and is_layout:
+        issues.append("Missing Open Graph tags")
+    
+    # 4. Heading hierarchy - multiple H1s
+    h1_matches = re.findall(r'<h1[^>]*>', content, re.I)
+    if len(h1_matches) > 1:
+        issues.append(f"Multiple H1 tags ({len(h1_matches)})")
+    
+    # 5. Images without alt
+    img_pattern = r'<img[^>]+>'
+    imgs = re.findall(img_pattern, content, re.I)
+    for img in imgs:
+        if 'alt=' not in img.lower():
+            issues.append("Image missing alt attribute")
+            break
+        if 'alt=""' in img or "alt=''" in img:
+            issues.append("Image has empty alt attribute")
+            break
+    
+    # 6. Check for canonical link (nice to have)
+    # has_canonical = 'rel="canonical"' in content.lower()
+    
+    return {
+        "file": str(file_path.name),
+        "issues": issues
+    }
+
+
+def main():
+    project_path = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
+    
+    print(f"\n{'='*60}")
+    print(f"  SEO CHECKER - Search Engine Optimization Audit")
+    print(f"{'='*60}")
+    print(f"Project: {project_path}")
+    print(f"Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print("-"*60)
+    
+    # Find pages
+    pages = find_pages(project_path)
+    
+    if not pages:
+        print("\n[!] No page files found.")
+        print("    Looking for: HTML, JSX, TSX in pages/app/routes directories")
+        output = {"script": "seo_checker", "files_checked": 0, "passed": True}
+        print("\n" + json.dumps(output, indent=2))
+        sys.exit(0)
+    
+    print(f"Found {len(pages)} page files to analyze\n")
+    
+    # Check each page
+    all_issues = []
+    for f in pages:
+        result = check_page(f)
+        if result["issues"]:
+            all_issues.append(result)
+    
+    # Summary
+    print("=" * 60)
+    print("SEO ANALYSIS RESULTS")
+    print("=" * 60)
+    
+    if all_issues:
+        # Group by issue type
+        issue_counts = {}
+        for item in all_issues:
+            for issue in item["issues"]:
+                issue_counts[issue] = issue_counts.get(issue, 0) + 1
+        
+        print("\nIssue Summary:")
+        for issue, count in sorted(issue_counts.items(), key=lambda x: -x[1]):
+            print(f"  [{count}] {issue}")
+        
+        print(f"\nAffected files ({len(all_issues)}):")
+        for item in all_issues[:5]:
+            print(f"  - {item['file']}")
+        if len(all_issues) > 5:
+            print(f"  ... and {len(all_issues) - 5} more")
+    else:
+        print("\n[OK] No SEO issues found!")
+    
+    total_issues = sum(len(item["issues"]) for item in all_issues)
+    passed = total_issues == 0
+    
+    output = {
+        "script": "seo_checker",
+        "project": str(project_path),
+        "files_checked": len(pages),
+        "files_with_issues": len(all_issues),
+        "issues_found": total_issues,
+        "passed": passed
+    }
+    
+    print("\n" + json.dumps(output, indent=2))
+    
+    sys.exit(0 if passed else 1)
+
+
+if __name__ == "__main__":
+    main()

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/server-management/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: server-management
+description: "Compatibility alias skill. Deprecated: use sre-engineer."
+metadata:
+  deprecated: true
+  replaced_by: sre-engineer
+  removal_target: v0.6.0
+---
+
+# Server Management
+
+## Compatibility Alias
+
+This skill is deprecated and kept for backward compatibility.
+
+Use `sre-engineer` as the canonical skill.
+
+## Migration
+
+1. Replace direct references to `server-management` with `sre-engineer`.
+2. Apply the full workflow from `sre-engineer` for new work.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/skill-authoring/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: "skill-authoring"
+description: "Use when creating a new Foundry skill or updating an existing one: scaffolding SKILL.md, fixing metadata, wiring references and scripts, removing legacy power files, and making the package work across Codex, Antigravity, Copilot, Cursor, and Windsurf. Do not use for prompt tuning without a skill package change or for editing only one generated mirror."
+metadata:
+  provenance:
+    source: "https://github.com/anthropics/skills/tree/main/skills/skill-creator"
+    snapshot: "Adapted from the local Codex system skill on 2026-03-06"
+  maintenance: "Pinned snapshot; refresh manually when upstream changes are intentionally adopted."
+---
+
+# Skill Authoring
+
+## Overview
+
+Use this skill to create or repair Foundry skills from the canonical source layer. It is adapted from Anthropic's `skill-creator`, but rewritten for Foundry's cross-platform model and packaging rules.
+
+## When to Use
+
+- Creating a new skill under `workflows/skills/<id>`
+- Updating `name`, `description`, `metadata`, or `compatibility` in `SKILL.md`
+- Repairing broken `references/`, `steering/`, or `templates/` links
+- Replacing legacy power-file patterns with canonical skill packaging
+- Adapting a skill so its generated Codex, Antigravity, Copilot, Cursor, and Windsurf bundles stay valid
+- Adding or updating helper scripts that make a skill deterministic and reusable
+
+## When Not to Use
+
+- Pure prompt tuning with no skill package changes
+- Editing only a generated mirror when the canonical source is unchanged
+- General feature work that should route to an implementation, review, or domain skill instead
+
+## Core Workflow
+
+1. Clarify the trigger boundary and package scope with concrete examples.
+2. Edit the canonical skill only. Never hand-edit platform mirrors first.
+3. Keep `SKILL.md` concise and move variant detail into one-level-deep sidecar files.
+4. Add scripts only when they remove repetition or make execution more reliable.
+5. Validate frontmatter, links, sidecar content, and platform packaging before finishing.
+6. Regenerate mirrors and rule assets, then verify the skill is discoverable and readable at runtime.
+
+## Foundry Skill Contract
+
+- Required file: `SKILL.md`
+- Optional folders: `references/`, `steering/`, `templates/`, `scripts/`, `assets/`
+- Keep only `SKILL.md` at the skill root. Do not leave extra top-level markdown files.
+- Use relative paths from the skill root, not platform-specific absolute paths.
+- Reference files must be loaded selectively with explicit `Load when` guidance.
+- Do not ship legacy power files in canonical or platform-facing skill bundles.
+- Canonical metadata can stay richer, but platform mirrors are generated and sanitized automatically.
+
+## References
+
+Load on demand. Do not preload all reference files.
+
+| File | Load when |
+| --- | --- |
+| `references/foundry-platform-parity.md` | Adapting a skill for Codex, Antigravity, Copilot, Cursor, or Windsurf packaging and metadata rules. |
+| `references/foundry-skill-checklist.md` | Verifying naming, frontmatter, sidecars, routing, and validation before shipping a skill update. |
+
+## Helper Scripts
+
+Load or run only when the task needs them.
+
+| File | Load when |
+| --- | --- |
+| `scripts/init_skill.py` | Scaffolding a new canonical skill directory and starter `SKILL.md`. |
+| `scripts/quick_validate.py` | Checking frontmatter, broken markdown references, empty sidecars, and packaging safety for a skill directory. |
+
+## Rules
+
+- Prefer one canonical skill package that generates clean mirrors on every platform.
+- Keep references one level deep from `SKILL.md`.
+- Never bulk-load `references/` or `steering/`; pick only the file needed for the current step.
+- If a task is clearly about skill creation or maintenance, load this skill directly instead of starting with `skill_search`.
+- When cross-platform behavior changes, verify the generated outputs instead of assuming canonical text alone is enough.

package/workflows/workflows/agent-environment-setup/platforms/claude/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/claude/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/claude/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())