CR-2026-03-25: Claude Code /deploy Skill Implementation

Change Summary

Field Value

Change ID

CR-2026-03-25-deploy-skill-001

Requested By

Self (PRJ-claude-code-features)

Target Date

2026-03-25

Systems Affected

~/.claude/skills/deploy/, domus-* spoke repos, domus-docs hub

Risk Level

Low (automation of existing manual workflow)

Rollback Time

< 1 minute (delete skill directory)

Change Window

Any (personal development environment)

Category

Normal (follows full process)

Business Justification

Problem Statement

Deploying documentation changes requires a multi-step workflow:

  1. Commit spoke repo - Stage, commit with conventional format

  2. Push spoke repo - Push to origin/main

  3. Trigger rebuild - Push empty commit to domus-docs

  4. Push domus-docs - Push trigger commit to origin/main

This manual process:

  • Takes ~45 seconds per deployment

  • Requires remembering exact paths and commands

  • Creates cognitive load during documentation flow

  • Results in inconsistent commit messages

  • Often forgotten (changes pushed but rebuild not triggered)

Current Workflow (Manual)

# In spoke repo (e.g., domus-captures)
git add -A
git commit -m "docs: Add new runbook"
git push origin main

# Trigger rebuild (must remember exact path)
git -C /home/evanusmodestus/atelier/_bibliotheca/domus-docs commit --allow-empty -m "chore: Trigger rebuild"
git -C /home/evanusmodestus/atelier/_bibliotheca/domus-docs push origin main

Solution: /deploy Skill

Single command that handles the entire workflow:

/deploy                              # Push and trigger rebuild
/deploy "docs: Add new runbook"      # With commit message (if uncommitted changes)

Benefits (Quantified)

Benefit Measurement Value

Time savings

45s → 5s per deploy

~40 seconds saved per deploy

Reduced errors

No forgotten rebuild triggers

100% rebuild rate

Consistency

Standardized commit format

Clean git history

Flow preservation

Single command, no context switch

Improved focus

Learning reinforcement

Skill shows commands executed

Pattern internalization

ROI Estimate: 5 deploys/day × 40s = 3.3 minutes/day = 20 hours/year recovered

Technical Specification

Skills Architecture Overview

Claude Code skills are markdown files with YAML frontmatter stored in:

Scope Path Use Case

Personal

~/.claude/skills/<name>/SKILL.md

All projects

Project

.claude/skills/<name>/SKILL.md

Single repo only

Skill Placement Decision

Recommendation: Personal scope (~/.claude/skills/deploy/)

Rationale:

  • Deploy workflow applies to ALL domus-* spoke repos

  • Avoids duplicating skill in each repo

  • Single maintenance point

  • User’s CLAUDE.md already documents personal config approach

File Structure

~/.claude/skills/
└── deploy/
    └── SKILL.md              # Skill definition

SKILL.md Specification

---
name: deploy
description: Deploy documentation changes. Push spoke repo and trigger domus-docs rebuild via Cloudflare Pages.
disable-model-invocation: true
user-invocable: true
allowed-tools: Bash(git:*), Bash(echo:*)
argument-hint: [commit-message]
---

Frontmatter Fields:

Field Value Rationale

name

deploy

Invoked as /deploy

description

Full description

Shown in skill menu, helps Claude understand when to suggest

disable-model-invocation

true

Only user triggers deploy (not automatic)

user-invocable

true

Appears in / autocomplete menu

allowed-tools

Bash(git:*), Bash(echo:*)

Restrict to git commands only (security)

argument-hint

[commit-message]

Shows hint in autocomplete

Skill Logic

Deployment Flow
/deploy invoked
    │
    ├─► Check: Is this a domus-* spoke repo?
    │       └─► No: Exit with helpful message
    │
    ├─► Check: Any uncommitted changes?
    │       ├─► Yes + no message: Prompt for message
    │       └─► Yes + message provided: Commit with message
    │
    ├─► Push spoke repo to origin/main
    │
    ├─► Create empty commit in domus-docs
    │       └─► Message: "chore: Trigger rebuild (<spoke-name>)"
    │
    ├─► Push domus-docs to origin/main
    │
    └─► Report: URLs and status

Variable Substitutions

Variable Description

$ARGUMENTS

Commit message if provided

$0

First argument (commit message)

Environment Detection

Skill detects current repo via:

basename $(git rev-parse --show-toplevel)

Valid spoke repos (domus-* pattern):

  • domus-captures

  • domus-infra-ops

  • domus-ise-linux

  • domus-linux-ops

  • domus-netapi-docs

  • domus-python

  • domus-secrets-ops

  • domus-nvim (has embedded docs)

Official Documentation References

Resource URL

Claude Code Skills Guide

docs.anthropic.com/en/docs/claude-code/skills

Skills Frontmatter Schema

github.com/anthropics/claude-code/…​/skills.md

Allowed Tools Syntax

docs.anthropic.com/…​/settings#permissions