Specification

The Enterprise AI Agent Skills Specification defines the architectural contract, directory layout, metadata schema, resolution protocol, and cryptographic verification standard for AI Agent Skills compatible with Google Agent Development Kit (ADK) and polyglot agent runtimes.

This specification extends and supersedes baseline specifications (such as agentskills.io) by introducing:

1. Canonical Central Registry & Server Registration (castor://): Registration protocol (POST /api/v1/skills) assigning unique skill_id keys and canonical URIs (castor://skills/{domain}/{category}/{name}/{version}).
2. Native Build Lifecycle Integration: Client build hooks (castor-client for Maven, castor_client.build_meta for Python PEP 517 / uv, //go:generate for Go) that audit skills and inject pre-compiled resources directly into application artifacts.
3. Cryptographic Lockfiles (.manifest.lock): Deterministic SHA-256 checksum tracking to prevent skill drift or unauthorized agent/developer tampering.
4. 5-Point SDLC Quality Invariants: Mandatory frontmatter, progressive disclosure sub-trees, CWE security checkpoints, HTTP 429 resilience rules, and strict file:/// link resolution.
5. Polyglot URI Resolution: Unified URI syntax supporting central servers (castor://, cstr://), GitHub repositories (github://), Go modules (mod://), Java Maven artifacts (maven://), local packages (pkg://), and local filesystems (file://).
6. Zero-I/O Pre-compiled Manifests (skills_manifest.json): In-memory skill registration for low-latency agent startup.
7. Just-in-Time (JIT) Semantic Discovery: Semantic retrieval mapping user intent to specific skills, eliminating the need to statically load entire registries.
8. Human-in-the-Loop (HITL) Intervention Gates: Explicit compliance validation checkpoints designed to isolate read vs. write workloads for AHI safety.
9. Repeatable Scenario Verification Framework: Automated test scenario suites located in scenarios/*.md verifying agent execution correctness through tool assertions (expected_skills) and token-frequency cosine similarity thresholds.

A compliant skill MUST be structured as a self-contained directory containing a root SKILL.md file alongside supporting progressive disclosure subdirectories:

<skill-directory>/
├── SKILL.md                 # Primary skill specification & instructions (Required)
├── references/              # Detailed architectural guides & reference docs (Required)
│   └── *.md
├── examples/                # Code snippets, usage patterns & sample payloads (Required)
│   └── *
├── scenarios/               # Repeatable agent verification scenarios (Optional)
│   └── *.md
├── scripts/                 # Optional setup or execution scripts
└── resources/               # Optional static assets or schema definitions

Every SKILL.md MUST begin with a YAML frontmatter block enclosed by triple dashes (---). The frontmatter MUST contain the following fields:

Any unrecognized keys in the frontmatter MUST be preserved under a generic metadata dictionary.

A compliant skill loader MUST support resolving qualified skill root URIs:

Central server registration publishes source skills and assigns immutable skill_id keys:

1. Client Request: cstr register <source_uri> sends POST /api/v1/skills with X-API-Key authentication header.
2. Server Processing: Castor Registry validates source skill frontmatter, assigns skill_id (e.g., sk-9b1deb4d), and stores source_uri and canonical uri (castor://skills/{domain}/{category}/{name}/{version}).
3. Client Response: Returns HTTP 201 Created with canonical URI castor://skills/{domain}/{category}/{name}/{version}.

Every application registered with Castor Registry MUST be bound to a verified domain authority and assigned a canonical RFC 8141 URN:

• Application URN: urn:castor:app:<domain>:<app_name> (e.g. urn:castor:app:retailcortex.com:checkout-agent)
• Skill URN: urn:castor:skill:<domain>:<app_name>:<skill_name>:<version> (e.g. urn:castor:skill:retailcortex.com:checkout-agent:payment-gateway:v1.0.0)

1. SSO Email Match (VERIFIED_SSO): If the developer’s email domain matches the requested registration domain (e.g. dev@retailcortex.com registering retailcortex.com), domain verification is automatically confirmed.
2. Freemail Prohibition (ErrFreemailDomainProhibited): Public freemail provider addresses (gmail.com, yahoo.com, outlook.com, hotmail.com, icloud.com, etc.) are explicitly forbidden from claiming corporate domain namespaces.
3. DNS Challenge Fallback (PENDING_DNS): Claiming a custom third-party domain generates a DNS TXT challenge token (castor-domain-verify-<uuid>) that must be published under _castor-challenge.<domain> before activation.

Applications support multi-user collaboration and scoped API credentials governed by strict permission tiers:

Central registries MUST compute, index, and maintain multi-modal semantic embeddings for all registered skills:

1. Provider Contract & Vector Precision:
   • Embedding providers MUST implement the standard embedding.Provider interface, emitting $L_2$-normalized []float64 vectors.
   • Providers MUST support text embedding (GenerateEmbedding), binary image embedding (GenerateImageEmbedding), multi-chunk skill decomposition (GenerateSkillEmbeddings), and cosine similarity calculation (CosineSimilarity).
2. Poly-Column Dimensions:
   • embedding_768: 768-dimensional vector for standard text embedding models (text-embedding-004, alloydb-ai).
   • embedding_1408: 1408-dimensional vector for multi-modal image and media models (multimodalembedding).
   • embedding_3072: 3072-dimensional vector reserved for high-dimensional models.
3. Multi-Chunk Sliding-Window Decomposition:
   • Skill content MUST be decomposed into granular chunks prior to vectorization to support accurate RAG retrieval across complex technical instructions and code snippets.
   • Text chunks MUST be capped at at most 900 characters per chunk, with an 80-character sliding step overlap when partitioning large text blocks or code structures.
   • Itemized chunks MUST be generated across:
     • Skill summary & metadata (name, description, tags, categories).
     • System instructions (partitioned into numbered instruction blocks).
     • Trigger phrases (individual query match phrases).
     • Markdown references (references/*.md).
     • Executable examples (examples/*).
4. HNSW Acceleration:
   • PostgreSQL/AlloyDB indexes MUST utilize HNSW (m=16, ef_construction=64) over vector_cosine_ops for all active vector columns (skills_embedding_768_hnsw_idx, skills_embedding_1408_hnsw_idx).
5. Deterministic Offline Fallback:
   • In environments without live Google Cloud or AlloyDB AI credentials, registries and test runners MUST fall back to deterministic, normalized semantic hashing (embedding.GenerateDeterministicVector) to maintain hermetic test isolation.
6. Benchmark & Recall Evaluation:
   • Provider implementations MUST be verifiable against an evaluation test harness (pkg/embedding/harness_test.go) evaluating Mean Reciprocal Rank (MRR $\ge 0.85$), Top-1/Top-3 recall accuracy ($\ge 90%$), and P95 latency bounds.

All REST list and search endpoints (/api/v1/skills) MUST enforce strict request bounding:

1. Parameter Constraints:
   • page: Integer ≥ 1 (default: 1).
   • page_size / max: Integer 1 ≤ page_size ≤ 25 (default: 5).
2. Mandatory Response Headers:
   • X-Total-Count: Total matched entities across the entire dataset.
   • X-Page: Current page index.
   • X-Page-Size: Effective bounded page size.
   • X-Total-Pages: Total calculated page count ($\lceil \text{Total} / \text{PageSize} \rceil$).
3. Optional Envelope Parameter: If ?envelope=true is set, the server MUST wrap items in { "items": [...], "total_count": N, "page": P, "page_size": S, "total_pages": T }.

Skills may include a scenarios/ directory containing repeatable scenario test definitions (scenarios/*.md) used by developers, evaluation suites, and automated test runners (cstr test) to verify skill execution fidelity and tool grounding.

Each scenario is a Markdown file with a YAML frontmatter block defining execution expectations, followed by a reference markdown body defining the target outcome:

---
prompt: "How do I build a Bazel module hermetically using Bzlmod?"
executes: true
expected_skills:
  - bazel
threshold: 0.70
metadata:
  category: "build"
---
To build a Bazel module hermetically using Bzlmod:
1. Configure MODULE.bazel and commit MODULE.bazel.lock (CWE-829).
2. Execute `bazel build //...`.

1. Tool Invocation Assertion:
   • If executes: true, the test runner inspects the agent’s actual tool call history.
   • Every entry in expected_skills MUST be present in the recorded tool calls. If any tool is missing, the test fails immediately.
2. Output Similarity Scoring:
   • The agent’s generated response text is compared against the scenario’s reference outcome body.
   • Text is normalized (tokenized by [a-zA-Z0-9_]+, lowercased) into word-frequency vectors $\vec{u}$ and $\vec{v}$.
   • Cosine similarity is computed: $$\text{sim}(\vec{u}, \vec{v}) = \frac{\vec{u} \cdot \vec{v}}{|\vec{u}|_2 |\vec{v}|_2}$$
   • If $\text{sim}(\vec{u}, \vec{v}) < \text{threshold}$, the test fails.