Publish skill

Publishing a skill to the private registry

This is the meta-skill that publishes other skills. It is intentionally limited in scope: it assumes the project layout that this blueprint's skill-package/ example uses, and refuses to invent fields it doesn't have.

When to invoke

• User says "publish this skill" / "把这个 skill 发布出去" / "register this skill in our registry" / "send this to skills hub"
• User has just finished editing a directory that contains pyproject.toml and src/<pkg>/skill_files/SKILL.md
• The user's intent is to make a skill discoverable across the organization, not just to test it locally

When NOT to invoke

• The user is editing the skill content itself (use the regular edit flow; do not auto-publish drafts)
• The user is consuming a skill (search / install / use) — that's a different flow, see the consumer scripts
• There's no pyproject.toml in the current directory — this skill cannot publish raw markdown without a packaging step
• The user is on a machine without AWS credentials — refuse to proceed and explain how to set them up

How this skill works

The work is delegated to a single Python script: scripts/publish.py. The script is parameterized — it reads defaults from ~/.skillpublish/config.toml and accepts CLI flags to override.

Always read resources/publish-skill-runbook.md before running anything. The runbook covers:

• The preflight checks the script performs (and what to do when one fails)
• How the four "knobs" (account / registry / CodeArtifact repo / namespace) decide where the skill lands
• The DRAFT → PENDING_APPROVAL → APPROVED lifecycle and who is expected to push each transition
• Common errors (record name collision, IAM AccessDenied, version immutability) and their resolutions

Defaults and overrides

The script reads ~/.skillpublish/config.toml:

[default]
region = "us-east-1"
codeartifact_domain = "skills-demo"
codeartifact_repository = "skills-prod"
registry_name = "skills-demo-registry"

If the file is absent or a field is missing, the user must pass the value as a CLI flag. Refuse to proceed if any of --domain, --repository, --registry is unresolved.

Permissions

This skill cannot bypass IAM. The script verifies:

1. AWS credentials are present (sts:GetCallerIdentity)
2. The required CLIs are on PATH (aws, twine)

But it does NOT verify upfront that the principal has every required permission — that would require listing IAM, which most publishers don't have. Instead, it lets twine upload / CreateRegistryRecord fail naturally and surfaces the error. This is intentional: failures are clearer than a synthetic permission audit.

For the full permission set required to run this skill end-to-end, see docs/09-publishing-iam.md.

Default behavior is conservative

Two safeguards by default:

• No auto-submit. The script creates the record and stops at DRAFT. The author reviews via console / get-registry-record before running with --auto-submit to advance to PENDING_APPROVAL.
• No update of existing records. If a record with the same name already exists, the script exits and tells the author to bump the version in pyproject.toml.

If the user explicitly says "submit it for approval" / "go all the way", pass --auto-submit. Otherwise leave the conservative default.

What this skill does NOT do

• It does not approve records (separation of duty — only curators can; their IAM grants UpdateRegistryRecordStatus).
• It does not delete or yank records (also a curator's domain).
• It does not create the registry, the CodeArtifact domain, or any IAM resources — those are infrastructure provisioned by cdk deploy once per account.
• It does not validate skill quality (content review, scanning, policy compliance) — those belong on the curator's checklist or in an EventBridge-triggered scanner pipeline (see Phase 2).