---
name: skill-architect
description: >
  Inventories, creates, refactors, and audits global agent skills using structured blueprints and the System One balance protocol.
  Use when asked to create, edit, audit, or reorganize skills in the global-skills repository.
concerns: [system-one-balance]
---

# Skill Architect Protocol

The Skill Architect manages the global skill catalog in
[`~/Projects/work/global-skills/skills/`](../). All agents on this host
consume it: Antigravity via `~/.gemini/config/skills.json`, and OpenCode,
Codex, and Claude Code via symlinks maintained by `sync-skills.sh`.
JEV-specific skills stay in the JEV repo and are out of scope here.
Harness-specific copies are not authored.

---

## Phase 0: Setup and Protocols
1. Read referenced protocols matching the `concerns` field in YAML frontmatter.
2. For `system-one-balance`, consult
   [`~/Projects/work/JEV/.agents/protocols/system-one-balance-protocol.md`](/home/vasily/Projects/work/JEV/.agents/protocols/system-one-balance-protocol.md).
3. Review the canonical template in
   [`references/sample-skill.md`](references/sample-skill.md).

---

## Phase 1: Ingest and Check
1. Determine the task mode:
   - **Create**: New skill name specified, target directory does not yet exist.
   - **Update / Refactor**: Existing skill directory found, modifications requested.
   - **Audit**: Review existing skill catalog for compliance with the balance protocol.
2. Validate skill naming:
   - Must be `kebab-case` (e.g. `skill-architect`, `deliver-file`).
   - Lowercase alphanumeric characters and hyphens only.
   - Reject names that collide with skills in the JEV catalog
     (`~/Projects/work/JEV/.agents/skills/`); the sync script shadows JEV
     copies and warns.
3. Validate prompt trigger:
   - Ensure `description` in YAML frontmatter is a crisp, 1-2 sentence specification of what the skill does and the exact scenarios when the agent should activate it.

---

## Phase 2: Processing

### Case A: Create New Skill
1. Create directory: `~/Projects/work/global-skills/skills/[skill-name]/`.
2. Author `SKILL.md` following the [sample-skill blueprint](references/sample-skill.md):
   - Valid YAML frontmatter (`name`, `description`, `concerns`).
   - **Phase 0**: Setup and Protocols.
   - **Phase 1**: Ingest and Check (pre-flight checks, input validation).
   - **Phase 2**: Processing (numbered active imperative steps).
   - **Phase 3**: The System One Balance Pass.
   - **Phase 4**: Output Execution & Verification.
3. Create auxiliary directories if required:
   - `references/` for blueprints, schema specs, or reference catalogs.
   - `examples/` for input/output demonstrations.
4. Run `~/Projects/work/global-skills/sync-skills.sh` to propagate the
   skill to every agent.

### Case B: Update Existing Skill
1. Read `~/Projects/work/global-skills/skills/[skill-name]/SKILL.md`.
2. Apply requested functional changes while preserving the 5-phase structure.
3. Verify that YAML frontmatter retains valid `name` and `description` fields.

### Case C: Audit Skill Catalog
1. Scan all directories under `~/Projects/work/global-skills/skills/`.
2. Check for:
   - Valid YAML frontmatter.
   - Absence of imperative tool bans (`DO NOT CALL TOOLS`).
   - Clean mechanical instructions without fluff.

---

## Phase 3: The System One Balance Pass
Before writing or committing any `SKILL.md`:
1. Check against the System One balance protocol (Phase 0 link).
2. **Eliminate Bureaucracy**:
   - Ensure the skill does not command the agent to lock down read tools.
   - Ensure the skill does not force confirmation modals for routine tasks.
   - Ensure instructions are actionable, sequential, and concise.

---

## Phase 4: Output Execution & Verification
1. Save `SKILL.md` under the skill directory in the global catalog.
2. Run `~/Projects/work/global-skills/sync-skills.sh` and confirm the
   skill appears as a symlink in every target:
   ```sh
   ls -l ~/.agents/skills/[skill-name] ~/.codex/skills/[skill-name] ~/.claude/skills/[skill-name]
   ```
3. Commit the change in the global-skills repository.