Aptitude Publisher

Review-first CLI for validating and publishing Aptitude skills.

Install

Install the published package as a CLI tool:

uv tool install aptitude-publisher
aptitude-publisher --help

Run it without a persistent install:

uvx aptitude-publisher --help

The package installs this console command:

• aptitude-publisher
• aptitude-publisher-mcp

Configure Registry Access

Publisher uploads require a registry publish token:

export APTITUDE_PUBLISH_TOKEN=publisher-token

The packaged CLI and MCP server use https://api.aptitude-registry.dev by default. For local development or a self-hosted registry, override it:

export APTITUDE_REGISTRY_URL=http://127.0.0.1:8000

Relationship and existing-skill checks can also use a read token:

export APTITUDE_READ_TOKEN=reader-token

Performance Evaluation

Automatic Upskill case generation and evaluation currently use one OpenAI model: gpt-4.1-mini. Set OPENAI_API_KEY before inspection; do not configure multiple UPSKILL_MODELS values for publisher evaluation.

export OPENAI_API_KEY=...
export UPSKILL_PROVIDER=openai
export UPSKILL_MODELS=gpt-4.1-mini

MCP Server

Run the local stdio MCP server directly from PyPI:

uvx aptitude-publisher mcp

For a persistent installation, use aptitude-publisher mcp or the direct aptitude-publisher-mcp executable. The process waits for an MCP host; it does not display the guided terminal wizard.

{
  "mcpServers": {
    "aptitude-publisher": {
      "command": "uvx",
      "args": ["aptitude-publisher", "mcp"],
      "env": {
        "APTITUDE_PUBLISH_TOKEN": "replace-with-publish-token"
      }
    }
  }
}

aptitude_publisher_inspect_skill runs the local evaluation pipeline and writes .publisher_artifacts/ trace files. aptitude_publisher_publish_skill reruns that evaluation and can mutate registry state, so it requires an explicit slug, publish intent, and confirm_upload=true. Credentials are read only from the server environment and are never accepted as tool inputs. Admin batch upload and remote HTTP transport are outside the MCP v1 surface.

Usage

Launch the guided publisher wizard:

aptitude-publisher

Inspect a skill folder before publishing:

aptitude-publisher inspect /path/to/skill

Run the full local flow and stop before upload:

aptitude-publisher publish /path/to/skill --dry-run

Publish a skill to the configured registry:

aptitude-publisher publish /path/to/skill --intent create_skill

Upload multiple skills concurrently with an admin-scoped registry token:

export APTITUDE_ADMIN_TOKEN=admin-token
aptitude-publisher admin-batch-upload /path/to/skill-a /path/to/skill-b --intent create_skill

Batch upload runs local scans and uploads in the background with a visible progress bar, then prints only a final summary. It defaults to --scan-profile fast, --trust-tier verified, and --artifact-origin verified; pass --scan-profile full for deeper pre-upload checks. When an admin token is set, the guided wizard also offers a batch-upload path that accepts one directory containing skill folders and starts immediately with those defaults.

Publish a new version of an existing skill:

aptitude-publisher publish /path/to/skill --intent publish_version

Override identity fields when needed:

aptitude-publisher publish /path/to/skill \
  --slug my-skill \
  --version 1.0.0 \
  --publisher-identity my-team

Skill Folder Contract

A publish-ready source is a local skill folder with a required SKILL.md file. The publisher reads the SKILL.md frontmatter for registry identity, version, metadata, schemas, and relationships.

Generated files under .publisher_artifacts/ are local trace artifacts. They are not source files to author, and they are excluded from the immutable upload bundle.

What Works Today

• guided inspect, publish, and admin batch-upload wizard
• skill-root discovery from local folders or explicit paths
• registry identity derivation from SKILL.md frontmatter
• create-skill and publish-version intent handling
• relationship normalization and registry existence alerts
• metadata extraction for public skill facts and generated estimates
• SKILL.md contract validation
• LLM Guard security scanning over skill text and companion files
• Upskill-backed performance evaluation when configured
• weighted publish ranking and block/allow decisions
• deterministic tar.zst bundle creation
• registry upload with multipart artifact delivery
• admin batch upload with summary-only output

Source

Source and contributor documentation live in the project repository:

https://github.com/aptitude-stack/publisher