Customization

ulk is designed to be extended. Agents are markdown files with YAML frontmatter — creating a new agent requires no code. Skills, install flags, and cloud sessions (Managed Agents) extend the system further.

Creating a Custom Agent

Every agent in framework/agents/ is a markdown file. The frontmatter declares the agent’s identity and behavior. The content is the prompt.

Minimum viable frontmatter

---
name: my-agent
alias: my-agent
number: 68
type: agent
description: One-line description of what this agent does.
phase: build
category: session
model: sonnet
tools:
  - Read
  - Write
  - Bash
invocation: /ulk:my-agent
---

Full frontmatter reference

---
name: my-agent
alias: my-agent
number: 68                     # Next available number (currently 68)
type: agent
description: Short description.
phase: build                   # define | plan | build | verify | review | ship | orchestrator
category: session              # orchestrators | docs | audit | session | mobile | sync | analyze | deploy | routines | test | frontend | vps
model: sonnet                  # sonnet | opus | haiku
effort: high                   # low | medium | high | xhigh (opus default)
memory: local                  # optional: enables persistent memory in ~/.claude/agent-memory-local/<name>/
caveman: false                 # optional: enables terse output mode by default
context_budget: 12000          # optional: declared token budget for Context Manifest
loads_files: docs/spec.md      # optional: files loaded at startup (for Context Manifest)
loads_skills: ux-writing       # optional: skills loaded at startup
loads_mcps: github             # optional: MCPs used
mcp_cap_strategy: truncate     # optional: truncate | summarize | paginate | none
mcp_cap_threshold: 4000        # optional: tokens at which cap applies
tools:
  - Read
  - Write
  - Edit
  - Bash
  - mcp__github__search_repositories
invocation: /ulk:my-agent
---

Phase and model guidelines

Phase	Typical model	Typical effort
`define` — brief, arch decisions	opus or sonnet	xhigh or high
`plan` — decomposition	sonnet	high
`build` — implementation	sonnet	high
`verify` — tests, conformance	sonnet	high
`review` — audits, quality	opus (deep audits) or sonnet	xhigh or high
`ship` — deploy, commit	sonnet	high
`orchestrator` — routing	opus	xhigh

Use Haiku only for read-only structural tasks with no judgment required (like Godspeed and Gandalf).

Example: a changelog writer agent

---
name: changelog-writer
alias: changelog-writer
number: 68
type: agent
description: Generate a structured CHANGELOG.md entry from recent git commits.
phase: ship
category: session
model: sonnet
tools:
  - Bash
  - Write
  - Read
invocation: /ulk:changelog-writer
---

# Changelog Writer

You generate a structured CHANGELOG.md entry from recent git commits.

## Process

1. Run `git log --oneline --since="1 week ago"` to collect recent commits.
2. Group commits by type: feat, fix, chore, docs, perf, refactor.
3. Write a dated CHANGELOG.md section in Keep a Changelog format.
4. Append the section to CHANGELOG.md without overwriting existing content.

## Output format

```markdown
## [Unreleased] — 2026-05-23

### Added
- ...

### Fixed
- ...

Keep entries concise. One line per commit. No preamble.


### Placing the agent

```bash
# Place in the appropriate category folder
cp my-agent.md framework/agents/session/68-changelog-writer.md

# Regenerate the registry and commands
node framework/cheatheet/generate-registry.cjs
node framework/cheatheet/generate-commands.cjs

# Reinstall to deploy to ~/.claude/
./install.sh

The next available agent number is 68. Agent numbers are global and preserved — do not reuse retired numbers.

Authoring rules

Full conventions: .claude/rules/agents-authoring.md

Key rules:

No preamble or recap in the agent output — do the work directly
Use CLI tools before MCP tools (CLI = 0 tokens)
Declare context_budget and loads_files in frontmatter for expensive agents
Never read CLAUDE.md at the top of every agent — only if the agent genuinely needs it
Phase grid reference: framework/agents/_shared/phase-grid.md

Install Flags Reference

install.sh is a wrapper around ulk install (Go CLI). All flags are composable.

Core

Flag	Effect
`./install.sh`	Base installation (agents + bundled skills)
`--dry-run`	Simulate without writing files
`--wizard`	Force interactive wizard even on reinstall
`--with-vps`	Add 17 VPS management agents
`--with-teams`	Enable Agent Teams (experimental)
`ulk install --audit-only`	Audit pre-install without writing to `~/.claude/` → `.ulk-reports/audit-<ts>.json`
`ulk clean`	Remove orphan files (renamed/deleted agents)
`ulk clean --dry-run`	List orphans without deleting

Token optimization

Flag	Effect
`--with-context-mode`	Store verbose outputs in SQLite, return compact pointers (-$8 to -$24/month)
`--with-caveman-output-skill`	Install `/caveman` terse output mode (-79% report tokens)
`--with-session-defaults`	Write `CLAUDE_CODE_DISABLE_1M_CONTEXT=1` + `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80` to `~/.claude/settings.json`
`--with-caveman-shrink`	MCP proxy that compresses tool descriptions (-60% cache write cost)

Skills — opt-in bundles

Flag	Installs
`--with-figma-mcp`	Configure Figma MCP server
`--with-hue-skill`	`/hue` design language generator
`--with-caveman-skill`	`/caveman-compress` (CLAUDE.md compression, -46%)
`--with-tech-debt-skill`	`/tech-debt-audit` (file:line cited, TECH_DEBT_AUDIT.md)
`--with-web-design-skill`	`/web-design-guidelines` (Vercel Web Interface Guidelines code review)
`--with-ux-movement-skill`	`ux-movement-design` (UX Movement corpus, 319 articles)
`--with-laws-of-ux-skill`	`laws-of-ux-design` (30 Laws of UX audit)
`--with-visual-explainer-skill`	8-command skill: Mermaid diagrams, diff-review, slides, recap
`--with-ehmo-web-skill`	`web-platform-guidelines` (WCAG 2.2, 70+ rules)
`--with-kami-skill`	`kami` (professional documents: One-Pager, Long Doc, Resume, Slides)
`--with-logo-generator-skill`	SVG+PNG logo generator via Gemini API (requires `GEMINI_API_KEY`)
`--with-cwb-app-icon`	AppIcon generator for iOS/macOS (requires OpenAI key)
`--with-nothing-design`	Nothing design system skill
`--with-a11y-skills`	RAWeb/RAAM accessibility skills
`--with-addy-skills`	Addy Osmani performance skills
`--without-obsidian-skills`	Opt out of bundled Obsidian skills (5 bundled by default)

Memory and hooks

Flag	Effect
`--with-memory-loop`	Install memory loop hooks (SessionStart/Stop)
`--with-auto-dream`	REM-style memory consolidation (24h + 5 sessions → background cycle)
`--with-xavier-hook`	Auto-run Xavier context verification at session start
`--with-accountability`	Audit trail for all file mutations → `.ulk-reports/accountability.jsonl`
`--with-cli-telemetry`	CLI usage tracking → `./framework/tools/cli-report.sh`

Infrastructure

Flag	Effect
`--with-managed-agents`	Cloud sessions: `ant` CLI + orchestrators + env templates
`--with-code-graph`	Code Review Graph MCP (Python 3.10+, Tree-sitter + SQLite)
`--with-obscura`	Obscura headless browser (Rust, parallel scraping)
`--with-mini-browser`	`mb` stateful browser CLI (primary for login/form/multi-step)
`--with-sentinel`	Hook cascade: xavier+ed209 pre-push, killbill+ed209 pre-deploy
`--with-container-clis`	Docker, kubectl, helm, k9s, lazydocker
`--with-monitoring-clis`	vegeta, hyperfine, gping, mtr
`--with-ai-clis`	ollama, apfel, aider, llm
`--with-doc-clis`	mdbook, vale, markdownlint-cli2, pandoc
`--with-mobile-clis`	xcrun, bundler, fastlane, expo, eas-cli

Skills

Skills are reusable instruction sets installed in ~/.claude/skills/. They are invoked as slash commands and can be loaded by agents via the loads_skills: frontmatter field.

Bundled skills (installed by default)

Skill	Invocation	Purpose
figma-implement-design	`/figma-implement-design [url]`	Figma → code
figma-use	`/figma-use`	Figma session setup
figma-generate-design	`/figma-generate-design`	Code/brief → Figma
swift-swiftui-pro	`/swiftui-pro`	SwiftUI patterns
swift-concurrency-pro	auto	Swift concurrency
obsidian-markdown	auto	Obsidian frontmatter + wikilinks
obsidian-bases	auto	.base files
obsidian-cli	auto	Vault CLI interaction
json-canvas	auto	.canvas files
defuddle	auto	URL → clean Markdown (fallback)
context-audit	`/context-audit`	Token health score 0-100
symbols	`/symbols list\|view\|refs`	LSP TypeScript/JavaScript navigation
architecture-diagram	`/architecture-diagram`	HTML+SVG architecture diagrams

External skills registry

Skills declared in framework/skills-sources.json are not vendored in the repo. They are fetched via:

ulk skills list                  # List declared external skills
ulk skills update                # Fetch/install all external skills
ulk skills update --dry-run      # Simulate without installing

Current external skills:

Skill slug	Source	Purpose
`ux-writing`	content-designer/ux-writing-skill	Microcopy, error messages, voice & tone
`macos-design-guidelines`	ehmo/platform-design-skills	Apple HIG — macOS
`ios-design-guidelines`	ehmo/platform-design-skills	Apple HIG — iOS
`ipados-design-guidelines`	ehmo/platform-design-skills	Apple HIG — iPadOS
`watchos-design-guidelines`	ehmo/platform-design-skills	Apple HIG — watchOS
`tvos-design-guidelines`	ehmo/platform-design-skills	Apple HIG — tvOS
`android-design-guidelines`	ehmo/platform-design-skills	Material Design 3 / Jetpack Compose

Adding a custom skill

Skills can be sourced from any GitHub repository that follows the Claude Code skills format:

# Install via npx skills add (Claude Code skills registry)
npx skills add <github-url> --skill <slug>

# Or declare in framework/skills-sources.json for team-wide management

To declare a skill in framework/skills-sources.json:

{
  "sources": [
    {
      "url": "https://github.com/example/my-skill",
      "slug": "my-skill",
      "description": "What this skill does"
    }
  ]
}

Then: ulk skills update to install.

Agent Teams (Experimental)

Agent Teams allow multiple agents to work concurrently on related tasks, with an orchestrator coordinating outputs. Enabled via:

./install.sh --with-teams

Configuration is via .claude/settings.local.json (not committed — per-user). See framework/ for configuration examples.

Agent Teams are experimental and subject to change with Claude Code updates.

Managed Agents (Cloud Sessions)

Managed Agents run ulk sessions in the cloud without a local machine. They are triggered by API, cron schedule, or webhook.

Activation

./install.sh --with-managed-agents
node framework/cheatheet/generate-managed-agents.cjs    # Generate YAML from agent frontmatter
# Deploy via ant CLI → .ulk/managed-agents/ids.json

Available agents (5 ported)

Agent	Trigger	Environment
sargeras (45)	Weekly cron (Monday)	ulk-audit (read-only)
ed209 (52)	Monthly cron	ulk-audit (read-only)
lovecraft (47)	Daily cron (08:00)	ulk-dev (read-write)
2b3 (08)	Daily cron (18:00)	ulk-dev (read-write)
ci-guard (54)	`check_suite.completed` (failed)	ulk-ci (read-only)

All Managed Agents run on Sonnet (fastest, most economical for autonomous sessions). Opus is reserved for interactive local sessions.

Invoking from CLI

ulk ma sargeras "Audit the repo — 10 axes, write report to docs/audits/"
ulk ma ed209 "Security audit framework/agents/ — OWASP top 10"
ulk ma 2b3 "End-of-day checkpoint — commit current changes"

Trigger handlers

Two ready-to-deploy handlers in framework/managed-agents/triggers/:

cron-daily.ts — Vercel Cron or AWS Lambda EventBridge:

# GET /api/routines/cron-daily → triggers lovecraft (08:00) + 2b3 (18:00)

webhook-github.ts — GitHub check_suite.completed:

# Configure in GitHub Settings → Webhooks
# Payload URL: https://your-app.vercel.app/api/webhooks/github
# Events: Check suites

Required environment variables: ANTHROPIC_API_KEY, ULK_IDS_JSON (content of .ulk/managed-agents/ids.json). For the GitHub webhook: also GITHUB_WEBHOOK_SECRET and GH_TOKEN (host-side only, never in the sandbox).

Cost estimates

Agent	Frequency	Cost/run	Monthly estimate
sargeras	Weekly	~$0.30–0.50	~$1.20–2.00
ed209	Monthly	~$0.20–0.40	~$0.20–0.40
lovecraft	Daily	~$0.05–0.10	~$1.50–3.00
2b3	Daily	~$0.05–0.10	~$1.50–3.00
ci-guard	Per failure	~$0.10–0.20	Variable

Constraints

Not all agents can be ported to Managed Agents. Agents that use AskUserQuestionTool or read ~/.claude/ without externalization require refactoring. Checklist: framework/agents/_shared/managed-agents-protocol.md.

Full managed agents guide: docs/guides/managed-agents.md

Doc Mode

ulk supports three documentation modes, selected via doc-mode: in CLAUDE.md frontmatter:

Mode	Description	When to use
`faru`	Default since 2026-05-18. One card per folder in `docs/backlog/YYYY-MM-DD-TYPE-SLUG/CARD.md`	New projects, agent-first workflow
`coexist`	Transition mode: session tasks in `docs/todo.md`, specs/kata in `docs/backlog/`	Migrating from obsidian
`obsidian`	Legacy. `docs/07-spec/spec.md` + `docs/todo.md`	Existing projects with established structure

Auto-detection: if docs/backlog/ exists → faru. If docs/07-spec/spec.md or docs/todo.md exists without a backlog → obsidian. Fresh project → faru.

To opt out of faru at install:

./install.sh --without-faru