cortexapps-cli 1.24.0__tar.gz → 1.26.0__tar.gz

{cortexapps_cli-1.24.0 → cortexapps_cli-1.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexapps-cli
-Version: 1.24.0
+Version: 1.26.0
 Summary: Command Line Interface for cortexapps
 License: MIT
 License-File: LICENSE

{cortexapps_cli-1.24.0 → cortexapps_cli-1.26.0}/cortexapps_cli/cli.py

@@ -14,6 +14,7 @@ import requests
 
 from cortexapps_cli.cortex_client import CortexClient
 
+import cortexapps_cli.commands.ai_skills as ai_skills
 import cortexapps_cli.commands.api_keys as api_keys
 import cortexapps_cli.commands.audit_logs as audit_logs
 import cortexapps_cli.commands.backup as backup
@@ -248,6 +249,7 @@ def version():
     print(version)
 
 # Register all commands alphabetically so they appear in order in --help
+app.add_typer(ai_skills.app, name="ai-skills")
 app.add_typer(api_keys.app, name="api-keys")
 app.add_typer(audit_logs.app, name="audit-logs")
 app.add_typer(backup.app, name="backup")

cortexapps_cli-1.26.0/cortexapps_cli/commands/ai_skills.py

@@ -0,0 +1,200 @@
+import json
+import re
+from pathlib import Path
+from typing import Optional
+
+import typer
+import yaml
+from typing_extensions import Annotated
+
+app = typer.Typer(help="AI Skills commands", no_args_is_help=True)
+
+
+def _parse_frontmatter(content: str) -> tuple[dict, str]:
+    """Split a SKILL.md file into its YAML frontmatter and body."""
+    match = re.match(r"^---\n(.*?)\n---\n(.*)$", content, re.DOTALL)
+    if not match:
+        return {}, content
+    try:
+        frontmatter = yaml.safe_load(match.group(1)) or {}
+    except yaml.YAMLError:
+        frontmatter = {}
+    return frontmatter, match.group(2)
+
+
+def _local_links(text: str, base_dir: Path) -> list[Path]:
+    """Return local files referenced by markdown links in text, resolved against base_dir."""
+    links = []
+    for target in re.findall(r"\]\(([^)]+)\)", text):
+        target = target.split("#")[0].strip()
+        if not target or target.startswith(("http://", "https://", "${")):
+            continue
+        candidate = (base_dir / target).resolve()
+        if candidate.is_file():
+            links.append(candidate)
+    return links
+
+
+def _has_deep_references(skill_dir: Path, body: str) -> bool:
+    """True if a file SKILL.md links to itself links to another local file (>1 level deep)."""
+    for linked in _local_links(body, skill_dir):
+        try:
+            linked_body = linked.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        if _local_links(linked_body, linked.parent):
+            return True
+    return False
+
+
+def _entity_yaml(tag: str, entity_type: str, description: str, relationships: list) -> str:
+    info = {
+        "title": tag,
+        "description": description or "",
+        "x-cortex-tag": tag,
+        "x-cortex-type": entity_type,
+        "x-cortex-definition": {},
+    }
+    if relationships:
+        info["x-cortex-relationships"] = relationships
+    doc = {"openapi": "3.0.0", "info": info}
+    return yaml.safe_dump(doc, sort_keys=False)
+
+
+def _push_entity(client, entity_yaml: str) -> None:
+    client.post(
+        "api/v1/open-api",
+        data=entity_yaml,
+        content_type="application/openapi;charset=UTF-8",
+    )
+
+
+def _push_custom_data(client, tag: str, key: str, value) -> None:
+    client.post(
+        f"api/v1/catalog/{tag}/custom-data",
+        data={"key": key, "value": str(value)},
+        params={"force": False},
+    )
+
+
+@app.command()
+def sync(
+    ctx: typer.Context,
+    directory: Annotated[
+        Path,
+        typer.Option(
+            "--directory", "-d",
+            help="Directory containing plugin folders, each with .claude-plugin/plugin.json and skills/*/SKILL.md (the eng-commons layout).",
+        ),
+    ],
+    service: Annotated[
+        Optional[str],
+        typer.Option(
+            "--service", "-s",
+            help="Cortex Service tag to link every synced plugin/skill's ownership to (ai-plugin-service / ai-skill-service).",
+            show_default=False,
+        ),
+    ] = None,
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", "-n", help="Print what would be synced without pushing anything to Cortex."),
+    ] = False,
+):
+    """
+    Scan a plugins directory and sync ai-plugin / ai-skill catalog entities into Cortex.
+
+    Expects the eng-commons layout:
+
+        <directory>/<plugin>/.claude-plugin/plugin.json
+        <directory>/<plugin>/skills/<skill>/SKILL.md
+
+    For each skill, also pushes the lineCount, descriptionCharCount, and
+    hasDeepReferences Custom Data keys the ai-skills-quality scorecard reads
+    (see cortexapps_cli/solutions/ai-skills/scorecards/ai-skills-quality.yaml),
+    via the Custom Data API.
+
+    Re-run this on a schedule tied to when skills actually change (a GitHub
+    Action or webhook on push to the plugins repo), not on a fixed timer —
+    these values change maybe a couple of times a year, so recomputing them
+    multiple times a day is wasted work the scorecard evaluator would
+    otherwise have to redo live against git on every single evaluation.
+    """
+    client = None if dry_run else ctx.obj["client"]
+
+    plugin_dirs = sorted(
+        p for p in directory.iterdir()
+        if p.is_dir() and (p / ".claude-plugin" / "plugin.json").is_file()
+    )
+    if not plugin_dirs:
+        typer.echo(f"No plugins found under {directory} (expected <plugin>/.claude-plugin/plugin.json)")
+        raise typer.Exit(1)
+
+    synced_plugins = 0
+    synced_skills = 0
+
+    for plugin_dir in plugin_dirs:
+        manifest = json.loads((plugin_dir / ".claude-plugin" / "plugin.json").read_text(encoding="utf-8"))
+        plugin_tag = manifest.get("name", plugin_dir.name)
+        plugin_description = manifest.get("description", "")
+
+        skill_tags = []
+        skills_dir = plugin_dir / "skills"
+        if skills_dir.is_dir():
+            for skill_dir in sorted(p for p in skills_dir.iterdir() if p.is_dir()):
+                skill_md = skill_dir / "SKILL.md"
+                if not skill_md.is_file():
+                    continue
+
+                content = skill_md.read_text(encoding="utf-8")
+                frontmatter, body = _parse_frontmatter(content)
+                skill_tag = frontmatter.get("name", skill_dir.name)
+                skill_description = frontmatter.get("description", "")
+
+                line_count = len(body.strip("\n").split("\n")) if body.strip("\n") else 0
+                description_char_count = len(skill_description)
+                has_deep_references = _has_deep_references(skill_dir, body)
+
+                relationships = []
+                if service:
+                    relationships.append({"type": "ai-skill-service", "destinations": [{"tag": service}]})
+
+                skill_yaml = _entity_yaml(skill_tag, "ai-skill", skill_description, relationships)
+
+                if dry_run:
+                    typer.echo(f"--- {skill_tag} (ai-skill) ---")
+                    typer.echo(skill_yaml)
+                    typer.echo(
+                        f"  custom-data: lineCount={line_count} "
+                        f"descriptionCharCount={description_char_count} "
+                        f"hasDeepReferences={has_deep_references}"
+                    )
+                else:
+                    _push_entity(client, skill_yaml)
+                    _push_custom_data(client, skill_tag, "lineCount", line_count)
+                    _push_custom_data(client, skill_tag, "descriptionCharCount", description_char_count)
+                    _push_custom_data(client, skill_tag, "hasDeepReferences", "true" if has_deep_references else "false")
+
+                skill_tags.append(skill_tag)
+                synced_skills += 1
+
+        relationships = []
+        if skill_tags:
+            relationships.append({
+                "type": "ai-plugin-skills",
+                "destinations": [{"tag": t} for t in skill_tags],
+            })
+        if service:
+            relationships.append({"type": "ai-plugin-service", "destinations": [{"tag": service}]})
+
+        plugin_yaml = _entity_yaml(plugin_tag, "ai-plugin", plugin_description, relationships)
+
+        if dry_run:
+            typer.echo(f"--- {plugin_tag} (ai-plugin) ---")
+            typer.echo(plugin_yaml)
+        else:
+            _push_entity(client, plugin_yaml)
+
+        synced_plugins += 1
+
+    suffix = " (dry run — nothing was pushed)" if dry_run else ""
+    typer.echo(f"\nSynced {synced_plugins} plugin(s), {synced_skills} skill(s){suffix}.")

{cortexapps_cli-1.24.0 → cortexapps_cli-1.26.0}/cortexapps_cli/commands/entity_types.py

@@ -100,6 +100,7 @@ def update(
     ctx: typer.Context,
     file_input: Annotated[typer.FileText, typer.Option("--file", "-f", help=" File containing custom entity definition; can be passed as stdin with -, example: -f-")] = None,
     entity_type: str = typer.Option(..., "--type", "-t", help="The entity type"),
+    _print: CommandOptions._print = True,
 ):
     """
     Update entity type
@@ -108,7 +109,11 @@ def update(
     client = ctx.obj["client"]
     data = json.loads("".join([line for line in file_input]))
 
-    r = client.update("api/v1/catalog/definitions/" + entity_type, data=data)
+    r = client.put("api/v1/catalog/definitions/" + entity_type, data=data)
+    if _print:
+        print_output_with_context(ctx, r)
+    else:
+        return(r)
 
 @app.command()
 def get(

cortexapps_cli-1.26.0/cortexapps_cli/solutions/ai-skills/README.md

@@ -0,0 +1,85 @@
+---
+name: AI Skills Catalog
+description: Catalog your AI plugins and skills as first-class Cortex entities, with ownership and best-practice quality scorecards.
+---
+
+# AI Skills Catalog
+
+Model your AI plugins and the skills they bundle (e.g. Claude Code plugins and Agent Skills) as Cortex entities — owned, scored, and discoverable just like your services.
+
+## Overview
+
+```
+                              ┌──────────────────────┐
+                              │      ai-plugin       │
+                              │    docs-generator    │
+                              └──────────┬───────────┘
+                                         │
+                                 ai-plugin-skills
+               ┌─────────────────────────┴─────────────────────────┐
+               ▼                                                   ▼
+    ┌──────────────────────┐             │              ┌──────────────────────┐
+    │       ai-skill       │             │              │       ai-skill       │
+    │   changelog-writer   │             │              │     api-doc-sync     │
+    └──────────┬───────────┘             │              └──────────┬───────────┘
+               │                         │                         │
+               └─────────────────────────┴─────────────────────────┘
+                                         ▼
+                       ai-plugin-service / ai-skill-service
+                              ┌──────────────────────┐
+                              │       service        │
+                              │     docs-portal      │
+                              └──────────────────────┘
+```
+
+Ownership is never duplicated onto the AI entities themselves — `ai-plugin-service` and `ai-skill-service` relationships point at a Service (or however you already model repos) that already carries an owning team in your Catalog. A skill's or plugin's owner is always "whoever owns the linked Service."
+
+## What's Included
+
+**Entity types:** `ai-plugin`, `ai-skill`
+
+**Relationship types:**
+- `ai-plugin-skills` — a plugin's bundled skills (plugin → skill)
+- `ai-plugin-service` — the Service/repo that owns and hosts a plugin
+- `ai-skill-service` — the Service/repo that owns a skill directly, for cases where a skill's ownership differs from its parent plugin's (e.g. distinct CODEOWNERS within a monorepo)
+
+**Scorecard:** `ai-skills-quality` — 8 rules covering ownership (via the relationships above) and Anthropic's [Agent Skills authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices): concise SKILL.md (both this org's stricter target and Anthropic's hard limit), substantive descriptions within the spec's length bounds, no reserved words in the name, and shallow (one-level-deep) file references.
+
+**Sample entities:** one plugin (`docs-generator`), two skills (`changelog-writer`, `api-doc-sync`), and one sample service (`docs-portal`) they're linked to — enough to see the shape without assuming anything about your real catalog.
+
+## Installation
+
+```
+cortex solutions install -s ai-skills
+```
+
+## After Installing
+
+**Populate quality data for real skills**
+
+Three of the scorecard's rules — concise (`lineCount`), description length (`descriptionCharCount`, named to avoid confusion with the entity's own `description` field), and shallow references (`hasDeepReferences`) — read from Cortex custom metadata. `cortex ai-skills sync` pushes these via the Custom Data API. For each real skill you ingest:
+
+```
+cortex custom-data add --tag <skill-tag> --key lineCount --value <int>
+cortex custom-data add --tag <skill-tag> --key descriptionCharCount --value <int>
+cortex custom-data add --tag <skill-tag> --key hasDeepReferences --value <true|false>
+```
+
+The `cortex ai-skills sync` command computes and pushes all three automatically. Recompute on change, not on a timer — wire a GitHub Action or webhook to fire when a plugin/skill's files change, rather than recalculating on a fixed schedule. These values move maybe a couple of times a year; there's no reason to redo the work (or hit the git API) on every scorecard evaluation.
+
+The sample entities above don't have these set, so they'll score lower on those three rules until you do — that's expected; they're there to show the entity/relationship shape, not a passing score.
+
+**Link real plugins and skills to your own Services**
+
+Point `ai-plugin-service` / `ai-skill-service` at whatever Service (or repository entity) already owns that code in your Catalog, instead of the sample `docs-portal`.
+
+**Set up your AI Skills catalog**
+
+Cortex Catalogs (the nav-level groupings like Services, Infrastructure, Domains) are UI-only today — there's no API or CLI support yet to script this step:
+
+1. Go to [Catalogs](https://app.getcortexapp.com/admin/catalogs) → **New Catalog**
+2. Relationship type: `ai-plugin-skills`
+3. Root entity type: `ai-plugin`
+4. Name it **AI Skills**
+
+> Catalog creation will be automated once catalog API support is added to the CLI.

cortexapps_cli-1.26.0/cortexapps_cli/solutions/ai-skills/catalog/api-doc-sync.yaml

@@ -0,0 +1,11 @@
+openapi: "3.0.0"
+info:
+  title: api-doc-sync
+  x-cortex-tag: api-doc-sync
+  x-cortex-type: ai-skill
+  description: Keeps API reference docs in sync with OpenAPI spec changes, flagging drift for review.
+  x-cortex-definition: {}
+  x-cortex-relationships:
+    - type: ai-skill-service
+      destinations:
+        - tag: docs-portal

cortexapps_cli-1.26.0/cortexapps_cli/solutions/ai-skills/catalog/changelog-writer.yaml

@@ -0,0 +1,11 @@
+openapi: "3.0.0"
+info:
+  title: changelog-writer
+  x-cortex-tag: changelog-writer
+  x-cortex-type: ai-skill
+  description: Drafts changelog entries from merged PR titles and descriptions, grouped by conventional-commit type.
+  x-cortex-definition: {}
+  x-cortex-relationships:
+    - type: ai-skill-service
+      destinations:
+        - tag: docs-portal

cortexapps_cli-1.26.0/cortexapps_cli/solutions/ai-skills/catalog/docs-generator.yaml

@@ -0,0 +1,15 @@
+openapi: "3.0.0"
+info:
+  title: docs-generator
+  x-cortex-tag: docs-generator
+  x-cortex-type: ai-plugin
+  description: Generates and maintains developer-facing documentation from code and PR context.
+  x-cortex-definition: {}
+  x-cortex-relationships:
+    - type: ai-plugin-skills
+      destinations:
+        - tag: changelog-writer
+        - tag: api-doc-sync
+    - type: ai-plugin-service
+      destinations:
+        - tag: docs-portal

cortexapps_cli-1.26.0/cortexapps_cli/solutions/ai-skills/catalog/docs-portal.yaml

@@ -0,0 +1,6 @@
+openapi: "3.0.0"
+info:
+  title: docs-portal
+  x-cortex-tag: docs-portal
+  x-cortex-type: service
+  description: Internal documentation portal and static site.

cortexapps_cli-1.26.0/cortexapps_cli/solutions/ai-skills/entity-relationship-types/ai-plugin-service.json

@@ -0,0 +1,24 @@
+{
+  "tag": "ai-plugin-service",
+  "name": "AI Plugin Service",
+  "description": "Links an AI Plugin to the Cortex Service that owns and hosts it, so ownership is inherited from the Catalog instead of duplicated. Sources: ai-plugin. Destinations: service.",
+  "definitionLocation": "SOURCE",
+  "isSingleSource": false,
+  "isSingleDestination": true,
+  "allowCycles": false,
+  "sourcesFilter": {
+    "include": true,
+    "types": [
+      "ai-plugin"
+    ],
+    "providers": []
+  },
+  "destinationsFilter": {
+    "include": true,
+    "types": [
+      "service"
+    ],
+    "providers": []
+  },
+  "inheritances": []
+}

cortexapps_cli-1.26.0/cortexapps_cli/solutions/ai-skills/entity-relationship-types/ai-plugin-skills.json

@@ -0,0 +1,24 @@
+{
+  "tag": "ai-plugin-skills",
+  "name": "AI Plugin Skills",
+  "description": "Links an AI Plugin to the AI Skills it bundles. Sources: ai-plugin. Destinations: ai-skill.",
+  "definitionLocation": "SOURCE",
+  "isSingleSource": false,
+  "isSingleDestination": false,
+  "allowCycles": false,
+  "sourcesFilter": {
+    "include": true,
+    "types": [
+      "ai-plugin"
+    ],
+    "providers": []
+  },
+  "destinationsFilter": {
+    "include": true,
+    "types": [
+      "ai-skill"
+    ],
+    "providers": []
+  },
+  "inheritances": []
+}

cortexapps_cli-1.26.0/cortexapps_cli/solutions/ai-skills/entity-relationship-types/ai-skill-service.json

@@ -0,0 +1,24 @@
+{
+  "tag": "ai-skill-service",
+  "name": "AI Skill Service",
+  "description": "Links an AI Skill directly to the Cortex Service that owns it, for cases where a skill's ownership differs from its parent plugin's (e.g. distinct CODEOWNERS within a monorepo). Sources: ai-skill. Destinations: service.",
+  "definitionLocation": "SOURCE",
+  "isSingleSource": false,
+  "isSingleDestination": true,
+  "allowCycles": false,
+  "sourcesFilter": {
+    "include": true,
+    "types": [
+      "ai-skill"
+    ],
+    "providers": []
+  },
+  "destinationsFilter": {
+    "include": true,
+    "types": [
+      "service"
+    ],
+    "providers": []
+  },
+  "inheritances": []
+}

cortexapps_cli-1.26.0/cortexapps_cli/solutions/ai-skills/entity-types/ai-plugin.json

@@ -0,0 +1 @@
+{"type": "ai-plugin", "name": "AI Plugin", "description": "A bundle of AI skills distributed and versioned together (e.g. a Claude Code plugin). Installed as a unit, managed like a service.", "iconTag": "Cortex-builtin::PlugsConnected", "schema": {"type": "object", "properties": {}}}

cortexapps_cli-1.26.0/cortexapps_cli/solutions/ai-skills/entity-types/ai-skill.json

@@ -0,0 +1 @@
+{"type": "ai-skill", "name": "AI Skill", "description": "An individual AI skill (e.g. a Claude Code SKILL.md) bundled inside an AI Plugin.", "iconTag": "Cortex-builtin::MagicWand", "schema": {"type": "object", "properties": {}}}

cortexapps_cli-1.26.0/cortexapps_cli/solutions/ai-skills/scorecards/ai-skills-quality.yaml

@@ -0,0 +1,76 @@
+# AI Skill quality & ownership scorecard.
+#
+# The "Concise", "Description substantive/hard-limit", and "Line count hard
+# limit" rules read numeric/boolean values via Cortex custom metadata.
+# `cortex ai-skills sync` populates these via the Custom Data API (POST
+# api/v1/custom-data) for each key referenced below -- you can also set them
+# yourself with `cortex custom-data add --tag <skill> --key <key> --value
+# <value>` (or the bulk endpoint):
+#   lineCount              (int)  - line count of the skill's SKILL.md body
+#   descriptionCharCount    (int)  - character length of the skill's description
+#                                    (named to avoid confusion with the
+#                                    entity's own "description" field, which
+#                                    already appears in both this YAML and the
+#                                    API response)
+#   hasDeepReferences       (bool) - whether the skill's docs reference files
+#                                    more than one level deep from SKILL.md (see
+#                                    https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#avoid-deeply-nested-references)
+#
+# `--value true`/`--value false` on the CLI are stored and evaluated as real
+# booleans (confirmed live) -- use jq(custom("key"), "not") or
+# jq(custom("key"), ". == false") for boolean checks, not custom("key") ==
+# false/"false" directly (both fail against the live evaluator).
+#
+# Recompute these on change, not on a timer: wire a GitHub Action or webhook
+# to fire when a plugin/skill's files change and re-run the sync, rather than
+# recalculating on a fixed schedule -- these values move maybe a couple of
+# times a year, so there's no reason to redo the work (or hit the git API)
+# every time the scorecard evaluates.
+tag: ai-skills-quality
+name: AI Skill Quality & Ownership
+description: Checks that AI skills are owned via a linked Cortex Service, bundled under a plugin, and follow Anthropic's Agent Skills authoring best practices.
+filter:
+  kind: GENERIC
+  types:
+    include:
+      - ai-skill
+rules:
+  - title: Owned by a Cortex Service
+    description: The skill is linked to a Service via the ai-skill-service relationship, so there's a clear owning team in the Catalog.
+    weight: 3
+    expression: 'entity.destinations(relationshipType = "ai-skill-service").length > 0'
+
+  - title: Belongs to a plugin
+    description: The skill is bundled under an AI Plugin rather than managed ad hoc.
+    weight: 2
+    expression: 'entity.sources(relationshipType = "ai-plugin-skills").length > 0'
+
+  - title: Concise (team target -- <=200 lines)
+    description: '"Good skills should only be 200 lines" -- keeps SKILL.md focused and maintainable. Requires custom-data key "lineCount".'
+    weight: 2
+    expression: 'jq(custom("lineCount"), ". | tonumber") <= 200'
+
+  - title: Within Anthropic's SKILL.md line limit (<=500 lines)
+    description: 'Anthropic''s Agent Skills docs recommend keeping SKILL.md body under 500 lines for optimal performance -- a looser ceiling than this org''s 200-line target, useful for skills that miss the team target but aren''t badly bloated. Requires custom-data key "lineCount".'
+    weight: 1
+    expression: 'jq(custom("lineCount"), ". | tonumber") <= 500'
+
+  - title: Description is substantive
+    description: 'Per Anthropic''s guidance, avoid vague descriptions like "Helps with documents" -- the description drives skill discovery/triggering, so it needs real content. Requires custom-data key "descriptionCharCount".'
+    weight: 1
+    expression: 'jq(custom("descriptionCharCount"), ". | tonumber") >= 40'
+
+  - title: Description within Anthropic's hard limit (<=1024 chars)
+    description: 'The Agent Skills spec caps the description frontmatter field at 1024 characters. Requires custom-data key "descriptionCharCount".'
+    weight: 1
+    expression: 'jq(custom("descriptionCharCount"), ". | tonumber") <= 1024'
+
+  - title: No reserved words in tag/name
+    description: Anthropic's naming rules forbid "claude" or "anthropic" in a Skill's name field -- checked here against the Cortex tag as a proxy.
+    weight: 1
+    expression: '!(entity.tag().matches(".*claude.*") OR entity.tag().matches(".*anthropic.*"))'
+
+  - title: References stay one level deep
+    description: 'Per Anthropic''s progressive-disclosure guidance, all reference files should link directly from SKILL.md -- nested references (SKILL.md -> advanced.md -> details.md) cause Claude to partially read files with `head`, losing information. Requires custom-data key "hasDeepReferences" (boolean, as "true"/"false").'
+    weight: 1
+    expression: 'jq(custom("hasDeepReferences"), "not")'

{cortexapps_cli-1.24.0 → cortexapps_cli-1.26.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "cortexapps-cli"
 # version will be incremented via command line as part of github actions build
-version = "1.24.0"
+version = "1.26.0"
 description = "Command Line Interface for cortexapps"
 license = "MIT"
 authors = [