⚡ TidyFactor Registry & Multi-Platform Distribution REST API (v1)

Authoritative Machine-Readable API Specification for discovering, installing, auditing, and batch-deploying TidyFactor AI Agent Skills across autonomous IDE environments (Google Antigravity, Claude Code, Cursor, Codex, Windsurf).

---

🏛️ Overview & Architecture

The TidyFactor Self-Hosted Distribution API (/api/v1/*) provides a zero-dependency, high-performance, edge-cacheable registry service. It allows CLI binaries (@tidyfactor/cli), IDE extensions, and automation scripts to interact with the TidyFactor skill catalog programmatically.

graph TD
    CLI["💻 TidyFactor CLI / Any Client"]
    API["🌐 tidyfactor.com /api/v1/*"]
    REG["📄 registry.json (SSOT Catalog)"]
    PACKS["📦 packs.json (Curated Bundles)"]
    CDN["💾 /downloads/skills/*.skill (Static CDN)"]

    CLI -->|GET /api/v1/skills| API
    CLI -->|GET /api/v1/packs| API
    CLI -->|GET /api/v1/install.sh| API
    API --> REG
    API --> PACKS
    API -->|Redirect / Proxy| CDN

Global Headers & Policies

Policy	Value / Behavior
Base URL	https://tidyfactor.com/api/v1
Authentication	None (Public read-only registry)
CORS	Access-Control-Allow-Origin: * (Enabled globally)
Data Format	application/json; charset=UTF-8
Caching Policy	Cache-Control: public, max-age=300 (5 minutes edge TTL)
Character Encoding	Strict UTF-8 with unescaped Unicode and forward slashes

---

📋 Endpoint Summary Table

Method	Endpoint	Cache Policy	Description
GET	/api/v1/skills	max-age=300	Full catalog of all 12 registered community skills with versions & checksums.
GET	/api/v1/skills/{id}	max-age=300	Detailed metadata, checksum, dependencies, and install one-liners for a specific skill.
GET	/api/v1/skills/search	max-age=60	Full-text fuzzy search across skill names, tags, categories, and descriptions.
GET	/api/v1/packs	max-age=300	Curated skill bundles for batch installation (design, saas, growth, etc.).
GET	/api/v1/install.sh	max-age=600	Direct POSIX shell one-liner installer for Linux and macOS environments.
GET	/api/v1/install.ps1	max-age=600	Direct PowerShell one-liner installer for Windows environments.

---

🔍 Endpoint Specifications

1. GET /api/v1/skills

Retrieves the complete catalog of all production AI Coding Agent skills.

Request

curl -fsSL https://tidyfactor.com/api/v1/skills

Response (200 OK)

{
  "registry_version": "1.0.0",
  "skills_count": 12,
  "skills": [
    {
      "id": "tidyfactor-cinematic",
      "name": "TidyFactor Cinematic",
      "npm_package": "@tidyfactor/cinematic",
      "version": "3.6.0",
      "description": "Universal AI Agent Skill for building single-file, scroll-driven luxury landing pages (Apple x Cartier aesthetic) with zero build step.",
      "category": "Frontend Experience",
      "color": "000000",
      "archive_url": "https://tidyfactor.com/downloads/skills/tidyfactor-cinematic.skill",
      "sha256": "8f3b2a1c...",
      "install_oneliner_sh": "curl -fsSL https://tidyfactor.com/api/v1/install.sh | bash -s -- tidyfactor-cinematic",
      "install_oneliner_ps1": "irm https://tidyfactor.com/api/v1/install.ps1 | iex -Skill tidyfactor-cinematic"
    }
  ]
}

---

2. GET /api/v1/skills/{id}

Retrieves complete manifest information and distribution assets for an individual skill.

Request Parameters

• id (required): The canonical skill ID (e.g. tidyfactor-next or shorthand next).

curl -fsSL https://tidyfactor.com/api/v1/skills/tidyfactor-next

Response (200 OK)

{
  "id": "tidyfactor-next",
  "name": "TidyFactor Next",
  "npm_package": "@tidyfactor/next",
  "version": "1.4.0",
  "description": "Production multi-tenant SaaS engine on Next.js 16, React 19, TypeScript strict, and Supabase.",
  "category": "Engineering",
  "color": "000000",
  "archive_url": "https://tidyfactor.com/downloads/skills/tidyfactor-next.skill",
  "sha256": "e2c4f1a0...",
  "install_oneliner_sh": "curl -fsSL https://tidyfactor.com/api/v1/install.sh | bash -s -- tidyfactor-next",
  "install_oneliner_ps1": "irm https://tidyfactor.com/api/v1/install.ps1 | iex -Skill tidyfactor-next"
}

Error Response (404 Not Found)

{
  "error": "Skill not found",
  "id": "unknown-skill"
}

---

3. GET /api/v1/skills/search?q={query}&limit={n}

Searches skills across multiple metadata fields.

Query Parameters

• q (string, required): Search query string (minimum 2 characters).
• limit (int, optional, default: 50, max: 200): Max number of returned results.

curl -fsSL "https://tidyfactor.com/api/v1/skills/search?q=saas&limit=5"

Response (200 OK)

{
  "data": [
    {
      "id": "tidyfactor-next",
      "name": "TidyFactor Next",
      "version": "1.4.0",
      "category": "Engineering"
    }
  ],
  "query": "saas",
  "searchType": "fuzzy",
  "count": 1
}

---

4. GET /api/v1/packs

Returns official curated packs for one-click multi-skill injection into agent workspaces.

Request

curl -fsSL https://tidyfactor.com/api/v1/packs

Response (200 OK)

{
  "packs": [
    {
      "id": "design",
      "name": "Design & Frontend Triad",
      "description": "Complete frontend luxury experience, prototype, and styling stack.",
      "skills": ["tidyfactor-cinematic", "tidyfactor-design", "tidyfactor-styler", "tidyfactor-skill-architect"]
    },
    {
      "id": "saas",
      "name": "SaaS Starter Kit",
      "description": "Multi-tenant Next.js, design systems, direct-response marketing, and automated docs.",
      "skills": ["tidyfactor-next", "tidyfactor-design", "tidyfactor-styler", "tidyfactor-marketing", "tidyfactor-doc"]
    },
    {
      "id": "engineering",
      "name": "Full-Stack Engineering",
      "description": "Modern PHP monoliths, HTMX hypermedia, Vanilla SPAs, static starters, and documentation.",
      "skills": ["tidyfactor-php", "tidyfactor-htmx", "tidyfactor-js", "tidyfactor-html", "tidyfactor-doc"]
    }
  ],
  "count": 3
}

---

5. GET /api/v1/install.sh & GET /api/v1/install.ps1

Dynamic shell execution scripts for instant terminal execution without Node.js runtime.

POSIX Shell One-Liner (macOS / Linux)

# Install all 12 skills into current workspace (.agents/skills/)
curl -fsSL https://tidyfactor.com/api/v1/install.sh | bash

# Install a specific skill
curl -fsSL https://tidyfactor.com/api/v1/install.sh | bash -s -- tidyfactor-design

PowerShell One-Liner (Windows)

# Install all 12 skills into current workspace (.agents/skills/)
irm https://tidyfactor.com/api/v1/install.ps1 | iex

# Install a specific skill
irm https://tidyfactor.com/api/v1/install.ps1 | iex -Skill tidyfactor-design

---

📦 Direct CDN Downloads

All skill archive bundles are compiled into standalone .skill packages (ZIP format containing SKILL.md, references/, memory/, workflows/, and tools/) and served directly via CDN:

Package Asset	CDN URL
Master Suite Bundle (All 12 Skills)	https://tidyfactor.com/downloads/skills/tidyfactor-skills-suite.zip
Individual Skill Package	https://tidyfactor.com/downloads/skills/{skill_id}.skill
Canonical NPM Package	https://www.npmjs.com/package/@tidyfactor/cli