| name | add-block |
| description | Add a new block type to a block-diagram style app with runtime behavior, UI/editor integration, serialization, tests, docs, examples, and verification. |
Codex Runtime Rules
These Z Skills are native Codex workflows derived from github.com/zeveck/zskills at commit 14dea81da487b2904ea7d69a27295f1869206cdf. They are invoked by natural language or by naming the skill; examples that look like slash commands are only shorthand for the skill name.
Use Codex behavior first:
- Read the current repository before acting. Prefer existing project scripts, config, and conventions over the upstream examples.
- Never use Claude-only tools or assumptions: no
CronCreate, CronList, CronDelete, Agent/Task tool syntax, allowed-tools, .claude/settings.json, or automatic Claude hooks.
- Use sub-agents only when the user explicitly asks for agents, parallel work, or delegation, or when the user explicitly invokes a Z Skill step whose workflow requires an independent reviewer, devil's-advocate critique, or fresh verification context. Keep those skill-required agents bounded to that workflow step. If agents are unavailable or the work is too tightly coupled, run inline, disclose lower assurance before or in the result, and do not auto-land unless the user accepts it.
- For isolation, create git worktrees explicitly with normal
git worktree commands. Do not rely on an isolation: "worktree" parameter.
- Config lookup order is project
.agents/zskills-config.json first, then project zskills-config.json, then legacy .codex/zskills-config.json, then legacy .claude/zskills-config.json only if already present. Do not create new .claude runtime config for Codex.
- Scheduling is not automatic in Codex. If the user asks for recurring runs, explain the schedule and ask before installing any local cron/system scheduler. For normal turns, perform the requested work now.
- Helper assets live at project
.agents/zskills-support by default. Use project-local scripts/* first; fall back to $CODEX_HOME/zskills-support only for explicit global installs or legacy setups.
- Preserve Codex safety rules: do not revert unrelated work, stage files by name, avoid destructive git commands, and verify from actual diffs/tests.
Detailed upstream text is archived in references/upstream-claude-adapted.md for edge cases and future diffs. Load it only when the concise workflow below is insufficient.
Add Block
Workflow
- Confirm the target project actually has a block registry/model system. If not, adapt the concept to the local architecture or stop.
- Identify the block category, ports, parameters, runtime semantics, serialization, codegen needs, and UI/editor representation.
- Implement in the established local patterns: registry, runtime/evaluator, rendering, inspector/editor UI, serialization, tests, and docs as applicable.
- For multiple blocks, build shared infrastructure first, then add blocks in small batches.
- Add focused unit tests plus integration/codegen tests if the project supports them.
- Create or update examples using
add-example semantics when useful.
- Manually verify the editor workflow if UI changed.
- Report files changed, tests, screenshots/manual checks, and any unsupported semantics.
For block-diagram repositories, load references/upstream-claude-adapted.md and complete the original 12-step checklist before landing. At minimum, cover registry/type definitions, runtime semantics, editor/rendering UI, inspector parameters, serialization/migration, codegen/export if present, examples, unit tests, integration tests, manual editor verification, documentation, and final self-audit.
Preserved Z Skills Invariants
- Require a concrete plan before broad block-system changes.
- Complete runtime, UI, serialization, tests, docs, and examples as applicable.
- Do not land with unresolved sign-off items.
