Log in

Publishing a Skill

Author a skill in Claude Code or via the CLI, push it to your org, review, and publish.

Skills are authored on your local machine, pushed to your org as a draft, reviewed in the web app, and published to the org-wide library. There are two ways to do the local authoring half: with the Headways skill commands inside Claude Code, or with the headways CLI directly. Pick whichever fits your editor flow — both land in the same place.

Prerequisites

  • Member role or higher in your Headways workspace
  • Headways CLI installed (npm install -g headways) and authenticated (headways login)
  • For the Claude Code path: Claude Code installed, and the /headways-skill-prep and /headways-skill-contribute skills available locally (they ship with the desktop app's CLI install)

Using Skills

This is the path inside Claude Code. Two slash commands cover authoring → contribution: /headways-skill-prep prepares a skill folder for submission, and /headways-skill-contribute uploads it.

Where local skills live

Claude Code auto-loads any skill folder under ~/.claude/skills/<slug>/. A skill folder is a SKILL.md file plus optional sibling files (capabilities.yaml, hooks.yaml, connections.yaml, custom scripts).

To make a new skill available locally:

~/.claude/skills/
└── <your-slug>/
    ├── SKILL.md            # required — frontmatter + body
    ├── capabilities.yaml   # optional but recommended
    ├── hooks.yaml          # optional
    └── connections.yaml    # optional (only if your skill calls MCP tools)

Open Claude Code in any project; the skill becomes available as /<your-slug>. You can iterate on the body and test it live before contributing.

Step 1: /headways-skill-prep

Once the skill works locally, run:

/headways-skill-prep ~/.claude/skills/<your-slug>/

headways-skill-prep walks the folder and:

  • Validates the slug (^[a-z0-9-]+$, 1–64 chars)
  • Shortens the description field to the 90-character submission gate if needed (proposes options, waits for your call)
  • Moves TRIGGER lists out of the description into a ## Triggers section
  • Generates capabilities.yaml — declares the external services and resources your skill touches (matches the CapabilitiesBlockSchema the platform expects)
  • Generates hooks.yaml — empty for slash-command skills, populated for hook-driven ones
  • Generates connections.yaml if your skill uses MCP tools or shell commands that map to a connector (e.g., gh → github)
  • Lints for hardcoded user paths, secrets, and other rejection causes

Prep makes no network calls. Safe to re-run.

Step 2: /headways-skill-contribute

When prep is clean:

/headways-skill-contribute ~/.claude/skills/<your-slug>/

headways-skill-contribute:

  1. Pre-flights CLI auth, slug availability, and bundle integrity
  2. Shows you the diff (slug, headline, file list, target org) and waits for y/N
  3. Runs headways skills import <path> --slug <your-slug> — creates the Skill record + draft SkillVersion (v0.0.1)
  4. Asks whether to submit for review immediately or leave as draft
  5. If submitting: posts to /v1/skills/<slug>/versions/<v>/submit — the draft enters in_review

After this step the skill is visible in the org at Skills > [your skill] in in_review status, ready for a reviewer.

Iterating on a draft

If review comes back with changes:

# Edit ~/.claude/skills/<slug>/SKILL.md locally
# Re-run prep if structural changes
/headways-skill-prep ~/.claude/skills/<slug>/

# Push edits to the existing draft (does not create a new draft)
headways skills push <slug>

headways skills push updates the in-place draft. Re-submit with /headways-skill-contribute (or call the submit endpoint directly) when ready.

Using CLI

The raw CLI flow — useful if you author skills outside Claude Code, in your editor of choice, or want fine-grained control.

Step 1: Author the skill

Scaffold a new skill:

headways skills new

This prompts for a name, description, and category, then creates a local skill file. Alternatively, import an existing prompt or context file:

headways skills import ./my-prompt.md

The skill file is a Markdown document with YAML frontmatter for metadata. Edit it in your preferred editor to define the skill's instructions, context, and intended use.

Step 2: Push to your org

Once the skill is ready, push it to your organization:

headways skills push <slug>

This uploads the skill as a draft. The slug is the identifier from step 1 (visible in the frontmatter and confirmed in the CLI output).

Step 3: Submit for review

In the web app, navigate to Skills > [your skill] and click Submit for Review. The skill enters the governance gate:

  1. It is validated against your org's protection rules
  2. Assigned reviewers are notified
  3. Any rule violations (e.g., required reviewers not met) are surfaced before submission

Review and publish

This step is the same regardless of which path you took above. Reviewers open the skill in the web app and either approve or reject it with comments. Once approved:

  • The skill is published to the org-wide library
  • Team members can install it via headways sync start or the desktop app
  • Run events begin flowing into insights

Best practices

  • Keep skills focused on one workflow — avoid kitchen-sink prompts
  • Include context about why each instruction matters, not just what to do
  • Push incremental improvements as new versions; every push creates a reviewable version
  • Use /headways-skill-prep before every contribute — it catches the submission-gate failures before they reach review