agent-desktop/docs/plans/2026-03-02-feat-scalable-skill-architecture-clawhub-publishing-plan.md

title	type	status	date	origin
feat: scalable skill architecture with ClawHub auto-publishing	feat	completed	2026-03-02	docs/brainstorms/2026-03-02-clawhub-skill-publishing-brainstorm.md

feat: scalable skill architecture with ClawHub auto-publishing

Overview

Restructure the skills/ directory into a nested hierarchy (core → platform → app references), sync stale skill content from .agents/ to skills/, add ClawHub metadata to all SKILL.md files, create a symlink script for local development, and wire CI auto-publishing to ClawHub on every release.

(see brainstorm: docs/brainstorms/2026-03-02-clawhub-skill-publishing-brainstorm.md)

Problem Statement

1. Skills are stale — skills/agent-desktop/ has 50 commands documented, but .agents/skills/agent-desktop/ has 54 (notifications added Feb 27). Git-tracked version lags.
2. macOS skill not publishable — lives in .claude/skills/agent-desktop-macos/ (gitignored), not in skills/
3. No publishing pipeline — ClawHub integration doesn't exist. Manual publish only.
4. No scaffolding — adding a new platform or app-specific skill has no clear pattern or automation.

Proposed Solution

Directory Structure (Target)

skills/
├── agent-desktop/                  # Core skill (platform-agnostic)
│   ├── SKILL.md                    # Commands, observe-act loop, ref system, JSON contract
│   └── references/
│       ├── commands-observation.md
│       ├── commands-interaction.md
│       ├── commands-system.md
│       └── workflows.md
│
├── agent-desktop-macos/            # macOS platform skill
│   ├── SKILL.md                    # TCC, AX API, smart activation chain, surfaces, NC
│   └── references/
│       └── notifications.md        # NC lifecycle, dismiss strategies (extracted from SKILL.md)
│
scripts/
└── link-skills.sh                  # Symlinks skills/ → .claude/skills/ for local dev

CI Pipeline Addition

New publish-skills job in .github/workflows/release.yml after publish-npm.

Acceptance Criteria

• skills/agent-desktop/ synced to match .agents/skills/agent-desktop/ (54 commands, notifications section)
• skills/agent-desktop-macos/ created from .claude/skills/agent-desktop-macos/ (git-tracked)
• references/macos.md removed from core skill (moved to platform skill)
• Core skill SKILL.md reference table updated (no macos.md row)
• ClawHub metadata added to all SKILL.md frontmatters (version, tags, requirements)
• scripts/link-skills.sh created and working
• publish-skills job added to .github/workflows/release.yml
• npm postinstall prompts user to install Claude Code skills (with platform auto-detection)
• All SKILL.md files reviewed using /skill-creator skill for best practices
• All existing tests still pass
• Clippy clean, fmt clean

Build Guidance

Use the /skill-creator skill when writing or updating any SKILL.md file. It provides best practices for frontmatter structure, trigger keywords, reference file organization, and description quality. Invoke it before finalizing each skill to ensure the content meets Claude Code skill standards.

Implementation

Phase 1: Sync & Restructure Skills Directory

1.1 Sync core skill from .agents/ to skills/

The .agents/skills/agent-desktop/ directory is the most up-to-date version (54 commands, includes notifications). Copy it over the stale skills/agent-desktop/.

Files to sync:

Source (.agents/skills/agent-desktop/)	Destination (skills/agent-desktop/)
SKILL.md	SKILL.md (overwrite — adds notifications section)
references/commands-observation.md	references/commands-observation.md
references/commands-interaction.md	references/commands-interaction.md
references/commands-system.md	references/commands-system.md (adds notification commands)
references/workflows.md	references/workflows.md

After sync, delete: skills/agent-desktop/references/macos.md — this content moves to the platform skill.

Update: skills/agent-desktop/SKILL.md reference table — remove the macos.md row.

1.2 Move macOS skill to skills/

mkdir -p skills/agent-desktop-macos/references/
cp .claude/skills/agent-desktop-macos/SKILL.md skills/agent-desktop-macos/SKILL.md

If the macOS SKILL.md contains a Notification Center section that's large enough to be a reference, extract it to skills/agent-desktop-macos/references/notifications.md and reference it from the SKILL.md table. Otherwise keep it inline.

Phase 2: Add ClawHub Metadata

2.1 Core skill frontmatter

# skills/agent-desktop/SKILL.md
---
name: agent-desktop
version: 0.1.8
tags: desktop-automation, accessibility, ai-agent, gui-automation, cli
requirements:
  - agent-desktop
description: >
  Desktop automation via native OS accessibility trees...  
---

2.2 macOS skill frontmatter

# skills/agent-desktop-macos/SKILL.md
---
name: agent-desktop-macos
version: 0.1.8
tags: desktop-automation, macos, accessibility, ax-api, tcc-permissions
requirements:
  - agent-desktop
description: >
  macOS platform details for agent-desktop...  
---

Phase 3: Create Scaffolding Scripts

3.1 scripts/link-skills.sh

#!/usr/bin/env bash
# Links skills/ directories to .claude/skills/ for local Claude Code use.
# Run after clone or when adding new skills.

set -euo pipefail

REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
CLAUDE_SKILLS="$REPO_ROOT/.claude/skills"

mkdir -p "$CLAUDE_SKILLS"

for skill_dir in "$REPO_ROOT"/skills/*/; do
  name=$(basename "$skill_dir")
  target="../../skills/$name"
  link="$CLAUDE_SKILLS/$name"

  if [ -L "$link" ]; then
    rm "$link"
  fi

  ln -s "$target" "$link"
  echo "Linked: .claude/skills/$name → skills/$name"
done

Phase 4: Post-Install Skill Prompt

4.1 Extend npm/scripts/postinstall.js

After the binary download succeeds, detect the platform and prompt the user to install the agent-desktop Claude Code skills. This runs in the terminal so we can use stdin.

// npm/scripts/postinstall.js — append after binary install success

function promptSkillInstall() {
  const os = require('os');
  const { execSync } = require('child_process');

  // Check if Claude Code CLI is available
  try {
    execSync('claude --version', { stdio: 'ignore' });
  } catch {
    log('Tip: Install Claude Code skills for agent-desktop with:');
    log('  claude /plugin marketplace add lahfir/agent-desktop');
    return;
  }

  // Detect platform for the right skill
  const plat = os.platform();
  const platformSkill = {
    darwin: 'agent-desktop-macos',
    win32: 'agent-desktop-windows',
    linux: 'agent-desktop-linux',
  }[plat];

  log('');
  log('Claude Code skills available for agent-desktop!');
  log('Install with:');
  log('  claude /plugin marketplace add lahfir/agent-desktop');
  if (platformSkill) {
    log(`  claude /plugin install ${platformSkill}@lahfir-agent-desktop`);
  }
  log('');
}

promptSkillInstall();

Design decision: Print install instructions rather than auto-running claude commands. Postinstall scripts should not modify the user's Claude Code config without explicit consent. The user copies and runs the commands themselves.

4.2 Platform detection mapping

os.platform()	Core skill	Platform skill
darwin	agent-desktop	agent-desktop-macos
win32	agent-desktop	agent-desktop-windows
linux	agent-desktop	agent-desktop-linux

Phase 5: CI Auto-Publishing

5.1 Add publish-skills job to release.yml

Add after the publish-npm job:

# .github/workflows/release.yml
  publish-skills:
    needs: [release-please]
    if: needs.release-please.outputs.release_created == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "22"

      - name: Install ClawHub CLI
        run: npm i -g clawhub

      - name: Publish all skills to ClawHub
        run: |
          clawhub sync \
            --root skills/ \
            --all \
            --bump patch \
            --changelog "Release ${{ needs.release-please.outputs.tag_name }}"          
        env:
          CLAWHUB_TOKEN: ${{ secrets.CLAWHUB_TOKEN }}

5.2 Add CLAWHUB_TOKEN to GitHub repo secrets

Manual step: generate token at clawhub.ai, add to repo settings → Secrets → Actions.

Files Changed

File	Change
skills/agent-desktop/SKILL.md	Sync from .agents/, add ClawHub metadata, remove macos.md reference
skills/agent-desktop/references/commands-system.md	Sync from .agents/ (adds notification commands)
skills/agent-desktop/references/macos.md	Delete (moved to platform skill)
skills/agent-desktop-macos/SKILL.md	New — moved from .claude/skills/, add ClawHub metadata
skills/agent-desktop-macos/references/notifications.md	New — NC details extracted if SKILL.md is too large
scripts/link-skills.sh	New — symlink automation
npm/scripts/postinstall.js	Add skill install prompt after binary download
.github/workflows/release.yml	Add publish-skills job

Ongoing Convention: Skills Updated With Every Feature

This plan establishes a permanent convention: every new feature, command, or platform change must update the corresponding skill files. This is enforced via:

1. Memory rule — added to MEMORY.md under "Skill Maintenance (MANDATORY)" so it's loaded into every conversation context. Claude will automatically update skills as part of feature work.
2. PRD addendum — docs/prd-addendum-skill-maintenance.md has detailed per-phase rules.
3. /skill-creator skill — used when writing or updating any SKILL.md to ensure quality.

Change Type	Skill Update Required
New CLI command	Add to skills/agent-desktop/references/commands-*.md
New platform adapter	Create skills/agent-desktop-{platform}/SKILL.md + references/
App-specific quirk discovered	Add skills/agent-desktop-{platform}/references/{app}.md
Changed CLI flags or JSON output	Update all affected skill files
New workflow pattern	Add to skills/agent-desktop/references/workflows.md

Not Changing

• crates/ — no Rust code changes
• src/ — no binary changes
• release-please-config.json — skill versions are managed by ClawHub CLI --bump, not release-please
• .gitignore — skills/ is already tracked, .claude/ is already ignored

Dependencies & Risks

• CLAWHUB_TOKEN secret required — CI job will fail without it. Must be configured before first automated release.
• ClawHub automated review — published skills go through syntax validation and permission scanning (<5 min). If rejected, need to fix and re-publish.
• First publish should be manual — run clawhub sync --root skills/ --all --dry-run locally to verify before relying on CI.

Sources

• Origin brainstorm: docs/brainstorms/2026-03-02-clawhub-skill-publishing-brainstorm.md — key decisions: nested hierarchy, CI auto-publish, platform > apps scoping
• Existing CI pattern: .github/workflows/release.yml — 4-job pipeline (release-please → build → publish-github → publish-npm)
• Skill maintenance rules: docs/prd-addendum-skill-maintenance.md
• ClawHub CLI: docs.openclaw.ai/tools/clawhub