Claude Code: Skills, Hooks, Agents & MCP Servers

Tier 1: Custom Skills

Location: ~/.claude/skills/ (stowed from dots-quantum)

Skill Purpose Status CR

/deploy

Push spoke repo + trigger domus-docs rebuild via Cloudflare Pages

Implemented

CR-2026-03-25

/worklog

Create daily WRKLOG with all 8 standard partials

Implemented

CR-2026-03-25

/session

Create collaboration session log with commits, agents, modes, and teaching points

Implemented

 — 

/project

STD-001 project management — create, audit, add phases/features, update status, validate compliance

Implemented

 — 

/capture-idea

Capture idea → scaffold STD-001 project (metadata, summary, appendices, nav entry)

Implemented

 — 

/save-commands

Save CLI commands to quick-commands partial with tags, context, graduation tracking (STD-019)

Implemented

 — 

/drill

Random CLI drill from mastery curriculum (awk, sed, grep, find, xargs, jq)

Planned

-

/audit

Run audit-worklogs.sh with analysis

Planned

-

/rm-gen

Generate reMarkable workbook for specified topic

Planned

-

/commit

Enhanced commit with conventional format

Planned

-

Implemented Skill Details

/deploy (2.0 KB)

---
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]
---

Usage:

/deploy                              # Push and trigger (no new commit)
/deploy "docs: Add backup runbook"   # Commit message for uncommitted changes

Workflow:

  1. Validates repo name starts with domus-

  2. Handles uncommitted changes (commit if message provided, ask if not)

  3. Pushes spoke repo to GitHub

  4. Triggers domus-docs rebuild via empty commit + push

  5. Reports deployment URL

/worklog (3.6 KB)

---
name: worklog
description: Create daily worklog with standard partials. Generates WRKLOG file in domus-captures with correct structure.
disable-model-invocation: true
user-invocable: true
allowed-tools: Bash(date:*), Bash(mkdir:*), Bash(ls:*), Read, Write
argument-hint: [YYYY-MM-DD]
---

Usage:

/worklog                    # Create today's worklog
/worklog 2026-03-26         # Create specific date
/worklog tomorrow           # Create tomorrow's worklog

Generates file at:

~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/pages/YYYY/MM/WRKLOG-YYYY-MM-DD.adoc

Includes all 8 standard partials: urgent, morning, work-chla, personal, education, infrastructure, quick-commands, related.

/session

---
name: session
description: Create collaboration session log documenting AI-assisted work with commits, agents, modes, and teaching points.
user-invocable: true
allowed-tools: Bash(date:*), Bash(git:*), Bash(ls:*), Bash(basename:*), Read, Write
argument-hint: [YYYY-MM-DD]
---

Usage:

/session                    # Create today's session log
/session 2026-04-03         # Create specific date

Location: ~/.claude/skills/session/SKILL.md

Auto-injects dynamic context:

  • Current date and day of week

  • Current repository name

  • Today’s commits across all active repos

  • Active repo list

Generates file at:

~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/pages/sessions/SESSION-YYYY-MM-DD.adoc

Captures:

  • Collaborator — which Claude model assisted

  • Mode — delegated, coached, paired, reviewed, or autonomous

  • Commits — all commits made during the session

  • Agents used — which agents were invoked

  • Teaching points — key learnings and coaching moments

Skill Features

Dynamic Context Injection:

Commands wrapped in !command execute before Claude sees the skill, injecting live state into the prompt.

## Current State (auto-injected)
**Repository:** !`basename $(git rev-parse --show-toplevel)`
**Branch:** !`git branch --show-current`
**Status:**
!`git status --short`
**Unpushed commits:** !`git log origin/main..HEAD --oneline | wc -l`

Frontmatter Options:

---
name: deploy                          # Skill identifier
description: Deploy documentation     # Shown in / menu
disable-model-invocation: true        # Only user invokes
user-invocable: true                  # Show in / menu
allowed-tools: Bash(git:*)            # Restrict available tools
argument-hint: [commit-message]       # Autocomplete hint
context: fork                         # Run in subagent
agent: Explore                        # Agent type
model: haiku                          # Model override
---

Tier 2: Enhanced Hooks

Location: ~/.claude/settings.json (stowed from dots-quantum)

Hook Flow
Figure 1. Hook Execution Flow

Implemented Hooks

Event Matcher Action

SessionStart

*

Display "Professional Environment Active", "Output Style: Professional (No AI Attribution)", and backup file count from ~/.claude/backups/

UserPromptSubmit

*

Check if staged files match sensitive patterns (.env, .key, .pem, .credentials, .secret, .password) and warn if found

PreToolUse

Edit

Auto-backup edited file to ~/.claude/backups/auto-edit-backups/YYYYMMDD/

PreToolUse

Write

Auto-backup existing file to ~/.claude/backups/auto-write-backups/YYYYMMDD/ before overwrite (skips new files)

PostToolUse

Edit

ShellCheck validation for .sh, .bash, *.zsh files (first 10 lines of output)

PostToolUse

Edit

AsciiDoc attribute validation via ~/.claude/hooks/validate-asciidoc-attrs.sh

PostToolUse

Write

AsciiDoc attribute validation via ~/.claude/hooks/validate-asciidoc-attrs.sh
The PostToolUse Edit matcher runs two hooks in sequence: ShellCheck first, then attribute validation. The PostToolUse Write matcher runs attribute validation only.

AsciiDoc Attribute Validator

Location: ~/.claude/hooks/validate-asciidoc-attrs.sh (172 lines)

Features:

  • Extracts {attribute} references from edited .adoc files

  • Walks directory tree to find component’s antora.yml

  • Checks if attributes are defined

  • Skips 100+ built-in AsciiDoc attributes (toc, icons, etc.)

  • Warns on undefined custom attributes

  • Exit code 0 always (warns only, never blocks)

Planned Hooks

Hook Trigger Status

Xref Validator

PostToolUse (Edit *.adoc)

Planned

Build Verifier

PreCommit (domus-*)

Planned

Hook Events Reference

Event When Can Block?

SessionStart

Session begins

Yes

UserPromptSubmit

Before prompt processed

Yes

PreToolUse

Before tool executes

Yes

PostToolUse

After tool succeeds

No

Notification

Claude needs attention

No

Stop

Claude finishes

Yes

Exit Codes

  • Exit 0: Action proceeds (stdout added to context)

  • Exit 2: Action blocked (stderr shown to Claude)

  • Other: Action proceeds (stderr logged)

Custom Agents

Claude Code agents are markdown files with YAML frontmatter that define specialized behaviors, tool restrictions, and model selection. Agents live in .claude/agents/ directories at two scopes.

Global Agents

Location: ~/.claude/agents/ (stowed from dots-quantum/claude/.claude/agents/)

Global agents are available in every repository. They are managed as stow packages in the dots-quantum dotfiles repo and symlinked into ~/.claude/agents/ on all machines.

Agent Purpose Model Allowed Tools

doc-auditor

Audits AsciiDoc documentation for staleness, broken xrefs, missing attributes, orphaned partials, hardcoded values, and include chain issues across all domus-* repos.

haiku

Read, Glob, Grep, Bash

adoc-linter

Audits AsciiDoc for hardcoded values, missing attributes, syntax issues, convention violations. Read-only — reports findings only.

haiku

Read, Glob, Grep

build-fixer

Runs Antora build, parses all warnings/errors, fixes every one, verifies clean build. Zero tolerance.

sonnet

Read, Write, Edit, Glob, Grep, Bash

project-modularizer

Splits monolithic PRJ files (>100 lines) into reusable partials following the Kora lego-piece pattern.

sonnet

Read, Write, Edit, Glob, Grep, Bash

reviewer

Read-only documentation reviewer. Checks STD-001 compliance, AsciiDoc quality, xref paths. Reports only — no edits.

haiku

Read, Glob, Grep
doc-auditor key details

  • Read-only audit — reports findings in Critical/Warning/Info categories with file:line references

  • Memory enabled — records common issues and patterns between audits (memory: user)

  • Scoped to domus-* — knows paths to domus-captures and domus-infra-ops module roots

  • Max turns: 15, Effort: medium

  • Checks: staleness detection, attribute validation against antora.yml, xref resolution, orphaned partials, nested include chains, hardcoded values

Project-Scoped Agents (domus-captures)

Location: <repo>/.claude/agents/

Project-scoped agents are only available when Claude Code is running inside that repository. These agents contain repo-specific knowledge (file paths, conventions, build commands).

adoc-linter, build-fixer, and project-modularizer exist in both global and project scope. The global versions (dots-quantum) provide baseline behavior across all repos; the project-scoped versions (domus-captures) contain repo-specific paths and conventions. When running inside domus-captures, the project-scoped versions take precedence.
Agent Purpose Model Allowed Tools

worklog-creator

Creates daily worklog from git commits, session context, and tracker partials. Adds to nav, verifies build.

sonnet

Read, Write, Edit, Glob, Grep, Bash

build-fixer

Runs Antora build, parses all warnings/errors, fixes every one, verifies clean build. Zero tolerance.

sonnet

Read, Write, Edit, Glob, Grep, Bash

carryover-updater

Increments day counts in all tracker partials (work/adhoc, priorities, personal/adhoc, blocker dashboard). Updates last-updated dates.

haiku

Read, Edit, Grep, Bash

adoc-linter

Audits AsciiDoc for hardcoded values, missing attributes, syntax issues, convention violations. Read-only — reports findings only.

haiku

Read, Glob, Grep

project-modularizer

Splits monolithic PRJ files (>100 lines) into reusable partials following the Kora lego-piece pattern.

sonnet

Read, Write, Edit, Glob, Grep, Bash

workflow-documenter

Documents completed workflows and use cases into the Claude Code Features project as reusable partials.

sonnet

Read, Write, Edit, Glob, Grep, Bash

worklog-creator

Checks if today’s worklog exists at pages/YYYY/MM/WRKLOG-YYYY-MM-DD.adoc. If not, creates it from existing worklog templates. Gathers context from git log --since="yesterday" across active repos and reads tracker partials (priorities, personal/adhoc). Builds the worklog with standard partial includes (urgent, morning, work-chla, personal, education, infrastructure, quick-commands), adds it to the nav partial nav/chronicle-YYYY.adoc, and verifies a clean build.

build-fixer

Runs make 2>&1 and parses JSON output for "level":"warn" and "level":"error". Categorizes warnings (missing attributes, broken xrefs, heading sequence, unterminated blocks, table syntax, cross-component xrefs). Fixes every warning with no exceptions. Clears cache (rm -rf .cache build), rebuilds, and repeats until zero warnings. Never adds attribute-missing: skip as a workaround. Comments out cross-component xrefs with // TODO: instead of deleting them.

carryover-updater

Reads four tracker partials and increments all numeric day counts: trackers/work/adhoc.adoc, trackers/work/priorities.adoc, trackers/personal/adhoc.adoc, trackers/tables/blocker-dashboard.adoc. Updates // Last updated: comments to today’s date. Does not modify resolved/completed items. Calculates from origin dates in antora.yml if available.

adoc-linter

Performs 10 checks: hardcoded values (IPs, hostnames, ports, MACs, VLANs), missing :description: or :revdate: headers, :toc: attributes (forbidden — Antora UI handles TOC), markdown syntax mixed in, heading level jumps, missing subs=attributes+ on code blocks with {attributes}, unescaped curly braces in prose, broken xrefs, large code blocks (>10 lines) that should be examples, and reusable tables that should be partials. Reports as a numbered list with file:line references. Does not make changes.

project-modularizer

Reads the target PRJ file and identifies section boundaries (summary, problem, architecture, roadmap, risks). Creates partials at partials/projects/<project-slug>/. Extracts each section with // Partial: and // Included by: header comments. Creates missing sections if warranted (decisions, risks, metadata). Rewrites the main PRJ file as a slim assembly of include:: directives. Files under 100 lines are not modularized. Never loses content — every line from the original must exist in a partial.

workflow-documenter

Documents completed Claude Code workflows into the Features project as reusable partials. Asks or infers what happened in a session: which skills, hooks, agents, and rules were involved, what triggered the workflow, and what the outcome was. Creates a partial at partials/projects/claude-code/wf-{slug}.adoc following a structured template (Scenario, Components Used, Execution Flow, Result, Teaching Point). Adds the include:: directive to the workflows page. Every workflow must include a Teaching Point with a transferable principle, real metrics and commit hashes, and components that map to actual Claude Code features.

Usage

Agents are dispatched explicitly by name using the /agent command:

# Explicit dispatch
/agent doc-auditor          # Run documentation audit
/agent worklog-creator      # Create today's worklog
/agent build-fixer          # Fix all build warnings
/agent carryover-updater    # Increment tracker day counts
/agent adoc-linter          # Lint AsciiDoc files (read-only)
/agent project-modularizer  # Split PRJ file into partials
/agent workflow-documenter  # Document a completed workflow

Agent Design Principles

  • Focused specialization — each agent does one thing well

  • Tool restrictions — linters and auditors are read-only (no Write or Edit); builders and creators get full tool access

  • Model selection — haiku for fast read-only tasks (linting, auditing, incrementing counters), sonnet for complex work requiring writes and multi-step reasoning

  • Build verification — agents that write files must verify zero warnings before completing

  • Convention enforcement — all agents follow domus-captures AsciiDoc rules (no :toc:, no AI attribution, attributes not hardcoded)

  • Scope separation — global agents (dots-quantum) for cross-repo concerns, project agents for repo-specific workflows

Planned Agents

Agent Purpose Priority

commit-reviewer

Reviews staged changes before commit, checks for security issues and convention violations

P1

cli-drill-master

Generates awk/sed/jq challenges, grades answers, tracks progress

P2

pattern-recognizer

Analyzes worklogs for skill gaps and learning velocity patterns

P2

nav-sync

Scans pages/ for files not in nav.adoc and adds them

P2

Agent File Structure

Agent files use YAML frontmatter followed by the system prompt in markdown:

---
name: agent-name
description: One-line description (Claude uses this for dispatch)
tools: Read, Glob, Grep, Bash        # Tool restrictions
model: haiku                          # haiku | sonnet | opus
memory: user                          # Optional: persist learnings
maxTurns: 15                          # Optional: limit agent turns
effort: medium                        # Optional: low | medium | high
color: cyan                           # Optional: terminal output color
---

# Agent Title

System prompt defining the agent's behavior, process, and rules.

Agents are stored in .claude/agents/<name>.md — one file per agent.

  • Global: ~/.claude/agents/ (stowed from dots-quantum/claude/.claude/agents/)

  • Project: <repo>/.claude/agents/

MCP Servers (Planned)

Server Capabilities Status Priority

netapi MCP

Query ISE sessions, Vault PKI, DNS records

Planning

P1

Antora MCP

Validate xrefs, check playbook, list components

Planning

P1

gopass MCP

Query paths/metadata (NEVER secrets)

Planning

P2

rmapi MCP

List/organize reMarkable documents

Planning

P2