From 3a92d9fde5375bbe3dea4f5f02a4cc6591970b06 Mon Sep 17 00:00:00 2001 From: vasily Date: Tue, 13 Oct 2026 16:07:37 +0800 Subject: [PATCH] Add skill-architect adapted for the global catalog --- skills/skill-architect/SKILL.md | 93 +++++++++++++++++++ .../references/sample-skill.md | 49 ++++++++++ 2 files changed, 142 insertions(+) create mode 100644 skills/skill-architect/SKILL.md create mode 100644 skills/skill-architect/references/sample-skill.md diff --git a/skills/skill-architect/SKILL.md b/skills/skill-architect/SKILL.md new file mode 100644 index 0000000..5d182f9 --- /dev/null +++ b/skills/skill-architect/SKILL.md @@ -0,0 +1,93 @@ +--- +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. diff --git a/skills/skill-architect/references/sample-skill.md b/skills/skill-architect/references/sample-skill.md new file mode 100644 index 0000000..de5ab09 --- /dev/null +++ b/skills/skill-architect/references/sample-skill.md @@ -0,0 +1,49 @@ +# Antigravity & Jev Skill Template Blueprint + +Every skill written, refactored, or audited by the Skill Architect must match this exact structure. + +--- +name: [kebab-case-name] +description: > + A concise, 1-2 sentence explanation of what this skill accomplishes and exactly when the agent or dynamic router should activate it. +concerns: [system-one-balance] # omit if no protocols needed; see mapping below +--- + +# [Title of Skill] + +## Phase 0: Setup and Protocols +- Resolve protocols matching the `concerns` field using the mapping table at the bottom of this document. +- Review referenced protocols before generating or executing instructions. + +## Phase 1: Ingest and Check +1. Validate required inputs, file paths, or target environment settings. +2. Specify exact fallback behavior or default paths if arguments are omitted. +3. Fail open gracefully on missing dependencies without crashing the harness. + +## Phase 2: Processing (Core Logic) +- Structure workflow into sequential, numbered phases using active imperative verbs: + - "Read", "Parse", "Verify", "Mutate", "Execute", "Report". +- Avoid vague conversational fluff or open-ended speculation. +- Keep context instructions compact to respect prompt budgets. + +## Phase 3: The System One Balance & Anti-Bureaucracy Pass +- Scan generated workflow against [`.agents/protocols/system-one-balance-protocol.md`](../../protocols/system-one-balance-protocol.md). +- **Invariants**: + - Does NOT shout imperative tool lockouts (`DO NOT CALL TOOLS`). + - Does NOT interrupt routine user workflows with confirmation modals. + - Keeps instructions mechanical and actionable. + +## Phase 4: Output Execution & Verification +- Define exact output file paths, formats, and artifacts. +- Verify discovery via `jev_skill_router.py`: + ```cmd + cmd /c python .agents/hooks/jev_skill_router.py + ``` + +--- + +## Concerns → Protocol Mapping + +| Concern | Protocol File | +|:---|:---| +| `system-one-balance` | `.agents/protocols/system-one-balance-protocol.md` |