Converting UAIX to an AgentSkill: Analytical Report

Full report

On this page

Executive Summary

This report analyzes how to package the UAIX (Universal AI Exchange) project – which publishes the UAI-1 message standard for AI‑to‑AI communication – as an AgentSkills-compatible skill (Agentskills.io format). UAIX is built as a public WordPress site (with custom themes and plugins) that hosts the UAI-1 specification, JSON schemas, examples, validator tools, and APIs【8†L179-L188】【11†L143-L147】. Agent Skills are versioned, folder-based packages of instructions (a SKILL.md plus optional code and data) that agents load on demand【20†L68-L72】【16†L98-L107】. We map UAIX components (spec pages, schemas, APIs, tools) into skill elements (instructions, scripts, assets), and propose a sample skill structure with metadata, dependencies, and a manifest. Security, licensing, and CI/CD considerations are addressed, with example SKILL.md frontmatter and snippets. Tables compare UAIX and AgentSkill elements, and flowcharts illustrate the architecture and publishing flow. Finally, we provide a step-by-step publishing checklist and high-level effort estimates for this conversion project.

UAIX Project Overview and Architecture

UAIX (Universal Artificial Intelligence Exchange) is an open standards publication site for the UAI-1 protocol, which defines a portable, auditable message format for AI-to-AI tasks【8†L179-L188】【8†L215-L223】. In practice, UAIX is implemented as a WordPress site with a custom uaix-authority-theme and plugins (uaix-core, uaix-modules, etc.) that serve content and APIs. Its public deliverables include the UAI-1 spec text, JSON Schemas, a registry, examples, validator tools, conformance packs, and distribution ZIPs (e.g. uaix-authority-theme.zip, uaix-core.zip, uaix-bridge.zip)【11†L143-L147】【35†L142-L150】. UAIX also exposes a WP REST API (/wp-json/uaix/v1/...) for machine clients (e.g. /catalog, /schemas, /validate)【24†L112-L121】【30†L79-L88】.

flowchart LR
    UAIXWebsite["UAIX Website (WordPress)"]
    UAIXWebsite --> UAIXTheme["Theme (uaix-authority-theme)"]
    UAIXWebsite --> UAIXPlugins["Plugins (uaix-core, modules, etc.)"]
    UAIXPlugins --> UAIXREST["REST API Endpoints\n(`/wp-json/uaix/v1/...`)"]
    UAIXREST --> Agents["AI Agents & Automation Tools"]
    UAIXTheme --> Users["Human Users"]
    UAIXPlugins --> UAIXData["Data: Schemas, Examples, Conformance Packs"]
    UAIXData --> UAIXREST

Figure: High-level UAIX architecture (WordPress-based site, theme, plugins, REST API, data).

UAIX’s AI Memory Package Wizard is a 6-step web UI for building starter UAI-1 “memory packages”. It presents human users with form controls and simultaneously embeds a JSON “AI digest” for agent consumption【34†L124-L132】. The figure below shows the human wizard and the corresponding agent JSON digest on the same page. This illustrates UAIX’s dual interface: a visual UI for humans, and a machine-readable API endpoint for agents on the same route【34†L124-L132】.

【22†embed_image】 Figure: UAIX AI Memory Package Wizard – human UI (left) and embedded JSON “AI digest” for agents (right)【34†L124-L132】.

In summary, UAIX is a standards publication platform. Its components include: the UAI-1 specification (text and schemas), an interactive wizard and validator UI, a WP REST API for machine access, and packaged releases (ZIPs) of themes/plugins. For our purposes, we assume the UAIX code is primarily PHP/JavaScript (WordPress) and the data is JSON and Markdown.

AgentSkills Format and Requirements

Agent Skills are portable folders of instructions and code that AI agents can load on demand【20†L68-L72】【16†L98-L107】. At minimum, a skill folder contains SKILL.md, whose YAML frontmatter provides metadata (see below). The body of SKILL.md (written in Markdown) contains the agent instructions – e.g. step-by-step procedures, examples, edge cases. Skills may include subdirectories: scripts/ (executable code), references/ (detailed docs), and assets/ (templates, images, data)【14†L283-L292】【14†L309-L317】.

Key SKILL.md frontmatter fields are:

• name (required): 1–64 chars, lowercase alphanumeric and hyphens (must match folder name)【16†L98-L107】.
• description (required): 1–1024 chars summary of task/purpose【16†L98-L107】.
• license (optional): short license name or reference to a LICENSE file【16†L98-L107】.
• compatibility (optional): environment requirements (products, packages, etc.)【16†L103-L107】.
• metadata (optional): arbitrary key/value map for extra properties (e.g. author, version)【16†L103-L107】.
• allowed-tools (optional): space-separated list of approved tools the skill may invoke (experimental)【14†L249-L258】.

Example frontmatter (simple):

---
name: uaix-exchange
description: Provides information and tools for the UAIX UAI-1 exchange standard.
license: CC-BY-4.0
metadata:
  author: UAIXProject
  version: "1.0"
---

The Markdown body follows the frontmatter and contains the instructions an agent reads when activating this skill【16†L112-L120】【14†L264-L273】. Because agents progressively disclose content, the name/description are loaded at startup, and the full body is loaded only upon activation【14†L321-L330】. Long reference material should be split into references/ files so agents load them on demand【14†L296-L305】.

In summary, an AgentSkill for UAIX will consist of:

• SKILL.md: metadata + instructions (based on UAIX docs).
• Optional scripts/: e.g. Python or Bash tools (validator calls, fetching UAIX API).
• references/: detailed UAIX guide docs (could reuse UAIX pages).
• assets/: static data (UAIX JSON schemas, example messages, images).

Mapping UAIX Components to AgentSkill Elements

Each UAIX resource is thus mapped into an appropriate skill element. For instance, the UAI-1 protocol description becomes narrative instructions in SKILL.md, while the JSON Schemas become static asset files. UAIX’s dynamic API could be accessed via helper scripts if network access is allowed. The WordPress packaging (ZIPs) has no direct analogue; instead, the skill itself is the package.

Proposed Skill File/Folder Layout

Here is a sample structure for the UAIX AgentSkill (folder uaix-exchange/):

uaix-exchange/
├── SKILL.md              # Skill metadata and instructions (required)
├── LICENSE               # License text (e.g. CC-BY-4.0)
├── scripts/              # (optional) helper code
│   ├── fetch_adoption_kit.py   # fetches UAIX adoption kit JSON
│   └── validate_message.py     # calls UAIX validator or local check
├── references/           # (optional) detailed docs
│   ├── UAI-1-Overview.md        # background on UAI-1 protocol
│   └── UAIX-APIs.md             # description of UAIX API routes
├── assets/               # (optional) schemas, examples, diagrams
│   ├── uai1-message-schema.json # UAI-1 JSON Schema
│   ├── example_conformance.json  # example message
│   └── wizard_screenshot.png     # diagram of UAIX wizard UI
└── skills.json (optional) # manifest for package metadata/deps (see below)

• SKILL.md: Frontmatter with name: uaix-exchange, description: , etc. The body might include sections like “Overview of UAI-1”, “How to Construct a Message”, and “Using UAIX Tools”.
• scripts/: Tools for actual tasks. E.g., a Python script using requests to hit https://uaix.org/wp-json/uaix/v1/validate. (Agents with code execution capability could run these.)
• references/: Longer documentation pulled from UAIX site (e.g. context budgeting, project handoff guides) so agents can load details on demand.
• assets/: Static resources: JSON schemas (e.g. for validation), lookup tables, or diagrams (like the wizard UI).
• LICENSE: The skill’s license. If UAIX content is open, we might use a Creative Commons or MIT license.
• skills.json: (Optional) A proposed manifest (see below) that lists dependencies or metadata. Not currently required by the spec, but useful for packaging.

Required Interfaces, Data Formats, and Dependencies

The UAIX skill will primarily deal in JSON (UAI-1 messages and schemas) and Markdown. Potential interfaces include:

• UAIX REST API: Agents can query UAIX live endpoints (e.g. /catalog, /schemas, /examples) using HTTP. Scripts in scripts/ can automate these calls. Example format: JSON request to https://uaix.org/wp-json/uaix/v1/validate.
• Local JSON schemas: Include UAI-1 schema in assets/ so the agent can validate messages offline.
• UAIX-specific tools: The skill might wrap calls to the UAIX validator (via API) or reference the Conformance Pack. If agents have network access, they could fetch the conformance pack via scripts/fetch_conformance_pack.py.

Dependencies: If scripts are included, specify their runtimes. For example, if using Python scripts, the frontmatter or compatibility field should note “Requires Python 3.8+ and requests library”. In an AgentSkill allowed-tools list, one could allow running Python or cURL. E.g.:

allowed-tools: Python(requests) Bash(curl)

This signals to the agent which tools may be invoked. Any dependencies (like Python packages) should be documented in compatibility. The skill might depend on having internet access to reach uaix.org; include that in compatibility if needed.

Data Formats

• JSON: All UAI-1 message payloads, schemas, registry entries, adoption kits, etc., are JSON. These can be stored in assets/ or fetched live.
• YAML: The skills.json (manifest) if used, and the SKILL.md frontmatter.
• Markdown: Documentation files in references/, and SKILL.md content.

Packaging, Metadata, Versioning, Licensing

Skill Packaging and Manifest

Agent Skills currently have no official package manifest, but a community proposal suggests adding a skills.json file alongside SKILL.md【25†L260-L268】. This manifest could declare:

• package name and version (e.g. "name": "uaix-exchange", "version": "1.0.0"),
• dependencies (URLs or git repos of other skills),
• license (e.g. "Apache-2.0" or "CC-BY-4.0"),
• scripts to run on install (if any), and
• other metadata (authors, homepage, etc.)【25†L260-L268】【28†L105-L113】.

For example, a simple skills.json might look like:

{
  "name": "uaix-exchange",
  "version": "1.0.0",
  "dependencies": [],
  "scripts": [],
  "license": "CC-BY-4.0",
  "source": "https://github.com/uaix/uaix-skill"
}

(Agentskill spec does not yet require this, but packaging tools like Tank use a manifest for publishing【28†L113-L121】【28†L210-L219】.)

Versioning and Releases

The skill should use semantic versioning (e.g. v1.0.0) to tag releases. If hosted on GitHub or similar, each tagged release corresponds to a skill package version. The metadata.version field in SKILL.md can mirror this. Release notes in UAIX’s changelog (governance track)【35†L170-L178】 can guide version bumps.

Licensing

UAIX content is published as an “open standard,” but no specific license is obvious on the site. We recommend choosing an open license for the skill. A Creative Commons (e.g. CC BY 4.0) or MIT/Apache license would be appropriate since UAIX encourages reuse【8†L179-L188】. The license frontmatter should reference the chosen license, and a full license text file can be included. If any UAIX content has its own license, it must be compatible. In SKILL.md we might write:

license: CC-BY-4.0

and put a LICENSE file.

Security and Privacy Considerations

The skill itself contains only public information (UAIX standard docs), so privacy concerns are minimal. However:

• Network calls: If scripts or workflows call UAIX APIs, ensure secure transport (HTTPS is used by UAIX). The agent environment should verify SSL certificates.
• Allowed tools: Whitelist only needed tools to minimize risk (e.g. only Python and cURL if necessary). Avoid allowing arbitrary code execution.
• Content audit: All skill instructions and data are derived from published UAIX records. No sensitive user data is handled.
• Injection risk: Careful if injecting UAIX-sourced JSON into prompts; treat schemas as data, not instructions.
• Authentication: UAIX APIs are public (no auth). If any token or credentials were needed, they must be securely managed (not applicable here).
• Safety: Provide disclaimers that the skill only aids in compliance with UAI-1, and agents should ultimately validate messages (e.g. using the validator) before claiming conformance.

In sum, treat the skill as a static documentation/resource package. Agents should apply normal sandboxing rules when executing any scripts.

Runtime and Hosting Options

An AgentSkill is typically accessed by the agent from a local filesystem or a registry. Options include:

• Local File: The user can clone the skill repo and place it in a skills directory (see Installation below).
• Skills Registry: Tools like Tank or ClawHub aim to provide hosted skill registries. You could publish the skill to such a registry (using a CLI) for discovery.
• GitHub/Git URL: Agents that support it might load skills directly from a Git repo URL (if implemented).

Agent runtime: Most agents load skills at startup (Tier 1) and on demand. The skill content can be loaded into any agent that supports AgentSkills (e.g. LangChain with the Agents extension, Anthropic Claude Agent UI, etc.). The .agents/skills/ directory is a widely-adopted convention for skill discovery【31†L153-L161】. For example, placing uaix-exchange/ under ~/.agents/skills/uaix-exchange/ would allow many agents to find it automatically【31†L153-L161】.

CI/CD and Automated Testing

To ensure quality and repeatability, we recommend setting up CI for the skill repository:

• Skill validation: Use the skills-ref tool (official AgentSkills validator) in CI to check SKILL.md syntax and frontmatter compliance【32†L1-L4】. Example: skills-ref validate ./uaix-exchange.
• Linting: If including scripts, lint them (e.g. flake8 for Python).
• Schema checks: If including JSON schemas, test that example messages validate against them.
• End-to-end: A test where an example UAI-1 message is constructed using the skill’s guidelines and submitted to the live UAIX validator endpoint (via scripts/) with expected result.
• Package integrity: If using a manifest or packaging tool, ensure the CI builds a distributable artifact (ZIP or tarball) that can be installed.

CI platforms (GitHub Actions, GitLab CI, etc.) can run these steps on push or pull request. Badges for “skill reference pass” and “tests pass” can signal health.

AgentSkills Validation and Certification Steps

AgentSkills.io itself has no formal “certification” process yet, but community best practices apply:

• Specification Compliance: Verify that the skill follows the Agent Skills spec (frontmatter fields, directory layout)【16†L98-L107】【14†L283-L292】.
• Skill Discovery: Ensure the skill can be discovered and loaded by popular agent frameworks (test with a reference implementation).
• Security Review: Confirm no dangerous permissions are granted (only needed allowed-tools), and remote calls are safe.
• Completeness: The skill instructions should be self-contained; all references in SKILL.md should point to included files or clearly accessible URLs.
• Documentation: Include a README or introduction so users (and agents) understand what the skill provides.

Some registries (like Tessl) perform automatic reviews on publish【45†L0-L4】. Using a registry’s “publish” command (if available) would bundle and validate the skill. At minimum, running skills-ref validate and addressing any errors is essential【32†L1-L4】.

User Installation and Onboarding UX

For end users (developers or agents) to install the UAIX skill:

• Local install: Copy or clone the uaix-exchange/ directory into one of the agent’s skill paths. By convention, agents scan ~/.agents/skills/ and/or a client-specific folder【31†L153-L161】. For example:

  mkdir -p ~/.agents/skills
  git clone https://github.com/uaix/uaix-exchange.git ~/.agents/skills/uaix-exchange

• Agent prompt integration: Tools like Claude or LangChain will detect the skill (via the folder name matching SKILL.md) and include “UAIX Exchange” in the agent’s skill catalog (since it has name and description). The agent then knows when to activate it.
• Bundling with agent: Organizations may package the skill with a custom agent image or bundle. In that case, include the skill directory in the docker image or environment.
• Skill discovery service: If a registry is used, the agent could fetch a list of skills from a remote service (currently ad hoc in this ecosystem).

Importantly, the onboarding instructions should emphasize the skill’s capabilities. For example, in SKILL.md we might add:

# UAIX Exchange
Use this skill to understand and construct UAI-1 messages and use the UAIX tools (validator, wizards).
The agent will load this skill when it detects tasks related to UAI-1, UAIX, or AI-to-AI communication standards.

Agents typically present the description to guide activation. Clear user docs (or a README) would complement the description.

Sample SKILL.md and Code Snippets

Below is an excerpt of what SKILL.md might contain for UAIX:

---
name: uaix-exchange
description: Knowledge and tools for the UAIX UAI-1 AI-to-AI exchange standard. Use this skill when working with UAI-1 messages, schemas, or when validating inter-agent communication.
license: CC-BY-4.0
metadata:
  author: UAIXProject
  version: "1.0"
allowed-tools: Bash(curl) Python(requests)
---

# Overview

UAI-1 is an open standard for auditable AI-to-AI messages. Each message has a JSON structure with headers (identity, provenance) and a payload. This skill helps construct and validate UAI-1 messages.

## Examples

- **Creating a UAI-1 message**: The `create_uai_message.py` script in this skill can generate a message envelope.
- **Validation**: Use `scripts/validate_message.py` to POST your message to the UAIX validator endpoint (`/wp-json/uaix/v1/validate`) and check compliance.

## Workflow

1. **Construct** your message according to UAI-1 JSON schema (`assets/uai1-message-schema.json`).
2. **Validate**: Run `python scripts/validate_message.py <your_message.json>`.
3. **Review**: If invalid, the validator will return errors from the UAIX schema registry.

For full details on UAI-1 fields, see `references/UAI-1-Overview.md`.

The snippet above shows YAML frontmatter and the start of an instructions section. The allowed-tools line (Bash and Python with requests) indicates what agents can use. In practice, the body would be more extensive, drawing from UAIX documentation pages【8†L179-L188】.

Publishing Checklist

Before releasing the skill, ensure the following steps are complete:

1. Content Compilation: Gather all UAIX materials to include (spec text, schemas, examples, how-tos). Identify any gaps.
2. Write SKILL.md: Populate metadata (name, description, license) and draft the instruction sections. Cover use-cases and steps clearly.
3. Add Assets: Include relevant JSON schemas and example files in assets/. Verify they are up-to-date with UAIX latest version.
4. Develop Scripts: Implement any helper scripts (e.g. validate_message.py). Ensure they have error handling and usage examples.
5. Validate Skill: Run skills-ref validate . to check spec compliance. Fix any frontmatter or formatting issues.
6. Set License: Choose and document an open license. Add a LICENSE file and reference it in SKILL.md.
7. Testing: In CI, test scripts (unit tests or live calls), and that examples load properly.
8. Version Tagging: Assign a version number (e.g. v1.0.0) and tag in Git. Update metadata.version accordingly.
9. CI/CD Setup: Configure automated checks (lint, validation). Optionally prepare packaging (e.g. ZIP, Docker image).
10. Documentation: Write a README.md with installation instructions, and possibly publish the skill homepage on a portal.
11. Registry/Registry Publishing: If using a registry (e.g. Tank, ClawHub), run the publish command (tank publish, etc.) or upload accordingly.
12. Announcement: Notify the UAIX and agent community (via news or social channels) that the UAIX AgentSkill is available.

Completion of these steps yields a reviewable skill package ready for distribution.

Next Steps and Effort Estimates

• Content Alignment (Medium effort): Review UAIX content to identify what belongs in the skill. (~1–2 days)
• Skill Drafting (Medium): Write SKILL.md instructions and assemble references/assets. (~2–3 days)
• Coding Helpers (Low): Develop minimal scripts (Python/cURL) to interface with UAIX API. (~1–2 days)
• Testing/CI (Low): Set up skills-ref and CI pipeline (lint, basic tests). (~1 day)
• Documentation & Packaging (Low): Prepare README, LICENSE, manifest. (~1 day)
• Publication (High): Publishing to a registry or formal channel (coordination, reviews) might involve stakeholder approval (~variable).

Overall, a medium level of effort is expected to produce a high-quality AgentSkill from UAIX, given the volume of content. Many UAIX parts are documentation (text and JSON) rather than code, so the work is largely curatorial and formatting. The interactivity (wizard, validator) means we must describe workflows rather than reimplement them.

Actionable next steps: Assign a developer/tech writer to draft the SKILL.md, use skills-ref early to check compliance, and decide on a license. Meanwhile, set up a Git repo and CI. Finally, plan for where the skill will be hosted and how agents will discover it (e.g. GitHub vs registry).

Estimated Timeline: Approximately 1–2 weeks full-time (end-to-end). Most tasks (drafting, scripting, testing) are in the low-to-medium range in size; the highest risk is ensuring completeness of UAIX content and coordinating release channels.

References: UAIX official site and docs【8†L179-L188】【11†L143-L147】【34†L124-L132】; Agent Skills specification and guidelines【16†L98-L107】【14†L249-L258】【25†L260-L268】【31†L153-L161】.