aiblueprint-cli 1.4.99 → 1.4.100

package/agents-config/skills/hooks-manager/SKILL.md

@@ -1,21 +1,22 @@
 ---
 name: hooks-manager
-description: Create, edit, configure, and debug Claude Code hooks. Use when working with hooks, event listeners, command validation, automated workflows, notifications, or hook events such as PreToolUse, PostToolUse, Stop, SessionStart, and UserPromptSubmit.
+description: Create, edit, configure, and debug hooks for Claude Code, Codex, and Cursor. Use for lifecycle events, command validation, routing shared hooks, notifications, automation, or platform-specific hook configuration.
 ---
 
 # Hooks Manager
 
-Configure Claude Code hooks as event-driven commands or prompts. Use hooks for validation, logging, formatting, notifications, context injection, and bounded completion checks.
+Configure Claude Code, Codex, and Cursor hooks as event-driven commands or prompts. Use hooks for validation, logging, formatting, notifications, context injection, and bounded completion checks. Treat platform syntax and capabilities as distinct; do not copy a Claude configuration into Codex or Cursor without adapting it.
 
 ## Quick workflow
 
-1. Identify the scope: project `.claude/hooks.json` or user `~/.claude/hooks.json`.
-2. Select the event (`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `SessionStart`, `SessionEnd`, `PreCompact`, or `Notification`).
-3. Choose a command hook for deterministic shell logic, or a prompt hook when natural-language reasoning is required.
-4. Add a regex matcher for the tools that should trigger it.
-5. Validate the JSON with `jq` and test with `claude --debug`.
+1. Identify the target platform and load `references/router.md`.
+2. Load the platform reference: `claude-code.md`, `codex.md`, or `cursor.md`.
+3. Identify the scope and file path for that platform.
+4. Select a supported lifecycle event and adapt the shared payload/decision contract.
+5. Choose a command hook for deterministic shell logic, or a prompt hook when natural-language reasoning is required and the platform supports it.
+6. Validate the native config and run the platform-specific smoke check.
 
-## Hook shape
+## Claude-shaped example
 
 ```json
 {
@@ -43,9 +44,18 @@ Command hooks receive JSON on stdin and may return JSON on stdout. Prompt hooks
 - Keep blocking rules selective so normal work is not accidentally interrupted.
 - Ensure referenced scripts are executable.
 
+## Shared router
+
+When the user asks for a hook that should work across agents, define one portable script with a small adapter per platform. Keep platform-specific event names, input fields, output decisions, exit codes, timeouts, and config paths in the references rather than pretending the formats are identical. Report unsupported features explicitly.
+
 ## References
 
-- `references/hook-types.md`: events, input/output, and blocking behavior.
+- `references/router.md`: select a platform, map shared lifecycle intent, and avoid unsupported assumptions.
+- `references/claude-code.md`: Claude settings, events, handlers, and `/hooks` verification.
+- `references/codex.md`: Codex config layers, `hooks.json`, trust, and restart/worktree caveats.
+- `references/cursor.md`: Cursor `.cursor/hooks.json`, hook scripts, and native response mapping.
+- `references/research-sources.md`: first-party documentation sources and refresh policy.
+- `references/hook-types.md`: shared event concepts, input/output, and blocking behavior.
 - `references/command-vs-prompt.md`: choose command versus prompt hooks.
 - `references/matchers.md`: regex and MCP matcher patterns.
 - `references/input-output-schemas.md`: event schemas and response fields.

package/agents-config/skills/hooks-manager/assets/codex-icon.svg

@@ -1,5 +1,16 @@
-<svg role="img" aria-label="hooks-manager skill icon" width="64" height="64" viewBox="0 0 64 64" xmlns="http://www.w3.org/2000/svg">
-  <rect width="64" height="64" rx="16" fill="#868259"/>
-  <path d="M20 22h24v6H20v-6Zm0 14h16v6H20v-6Zm0 14h24v6H20v-6Z" fill="#fff"/>
-  <circle cx="44" cy="39" r="7" fill="#868259" stroke="#fff" stroke-width="4"/>
+<!-- @license lucide-static v1.24.0 - ISC -->
+<svg role="img" aria-label="hooks-manager skill icon"
+  class="lucide lucide-settings"
+  xmlns="http://www.w3.org/2000/svg"
+  width="128"
+  height="128"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#F5F5F5"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M9.671 4.136a2.34 2.34 0 0 1 4.659 0 2.34 2.34 0 0 0 3.319 1.915 2.34 2.34 0 0 1 2.33 4.033 2.34 2.34 0 0 0 0 3.831 2.34 2.34 0 0 1-2.33 4.033 2.34 2.34 0 0 0-3.319 1.915 2.34 2.34 0 0 1-4.659 0 2.34 2.34 0 0 0-3.32-1.915 2.34 2.34 0 0 1-2.33-4.033 2.34 2.34 0 0 0 0-3.831A2.34 2.34 0 0 1 6.35 6.051a2.34 2.34 0 0 0 3.319-1.915" />
+  <circle cx="12" cy="12" r="3" />
 </svg>

package/agents-config/skills/hooks-manager/references/claude-code.md

@@ -0,0 +1,32 @@
+# Claude Code Hooks
+
+Claude Code stores project hooks in `.claude/settings.json` or `.claude/settings.local.json`, user hooks in `~/.claude/settings.json`, managed policy settings, and plugin hooks in `hooks/hooks.json`. Skill and agent frontmatter can also scope hooks to the active component. A standalone `.claude/hooks.json` is not the native settings surface.
+
+The native shape is `hooks.<event>[]`, then matcher groups, then handlers:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check.sh", "timeout": 30 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Supported handlers include `command`, `http`, `mcp_tool`, `prompt`, and experimental `agent` handlers, but support varies by event. Command hooks receive JSON on stdin; exit code `2` is the blocking error path for most events. Structured JSON on exit 0 can also return `decision`, `continue`, `systemMessage`, or `hookSpecificOutput`; do not mix exit-2 blocking with JSON output because the JSON is ignored. Use `/hooks` to inspect the active configuration and `claude --debug` for execution details.
+
+Important event facts:
+
+- `PreToolUse` matches `tool_name`; use handler `if` rules such as `Bash(git *)` for argument-aware filtering.
+- `UserPromptSubmit`, `Stop`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, and similar lifecycle events do not use tool matchers.
+- `SessionStart` supports `startup`, `resume`, `clear`, and `compact` sources.
+- `Stop` and `SubagentStop` must check `stop_hook_active` to prevent loops.
+- HTTP failures are non-blocking; a 2xx response must carry the JSON decision if it needs to block.
+
+Official reference: https://code.claude.com/docs/en/hooks

package/agents-config/skills/hooks-manager/references/codex.md

@@ -0,0 +1,23 @@
+# OpenAI Codex Hooks
+
+Codex implements Claude-style lifecycle hooks behind the `CodexHooks` feature. It discovers hook configuration from its config layers, including user-level `~/.codex/hooks.json` and project-level `.codex/hooks.json`. The current upstream runtime declares these event names: `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, and `Stop`.
+
+The config uses Claude-style `hooks` JSON with matcher groups and handlers. Handlers can include command, prompt, or agent declarations in the upstream schema. Keep the policy script portable and adapt field names at the boundary. Validate JSON before starting a session and restart Codex after changing hook configuration when the running session does not reload it.
+
+Matchers are meaningful for `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `SessionStart`, `SessionEnd`, `SubagentStart`, and `SubagentStop`. They are not meaningful for `UserPromptSubmit` and `Stop`.
+
+Operational checks:
+
+1. Confirm the active config layer and project root.
+2. Check the installed Codex version and hook schema.
+3. Validate `hooks.json` with `jq`.
+4. Run the smallest safe lifecycle/tool event and inspect the hook log.
+5. Re-test from a normal repository and a git worktree; project hook discovery can differ by version.
+
+Codex uses the same event names as Claude in `hooks.json`, but feature availability and output behavior are versioned. Do not assume Claude-only environment variables or a Claude exit-code path; inspect the installed schema/runtime and write a Codex-native adapter.
+
+Official sources:
+
+- https://github.com/openai/codex/tree/main/codex-rs/hooks
+- https://github.com/openai/codex/blob/main/codex-rs/hooks/src/lib.rs
+- https://github.com/openai/codex/blob/main/codex-rs/features/src/lib.rs

package/agents-config/skills/hooks-manager/references/cursor.md

@@ -0,0 +1,18 @@
+# Cursor Hooks
+
+Cursor hooks are configured in `.cursor/hooks.json` for a project or `~/.cursor/hooks.json` for the user. The official Cursor hooks surface includes lifecycle/tool events such as `sessionStart`, `sessionEnd`, `preCompact`, `stop`, `beforeSubmitPrompt`, `preToolUse`, `postToolUse`, `postToolUseFailure`, `subagentStart`, `subagentStop`, and `workspaceOpen`; the exact set can evolve by Cursor IDE/CLI version.
+
+Use a command script that reads JSON from stdin and emits the Cursor-native response. The config normally includes a top-level `version` and an event-to-handler map, for example `{ "version": 1, "hooks": { "preToolUse": [{ "command": "./.cursor/hooks/check.sh", "timeout": 5 }] } }`. Keep the shared policy separate from the adapter. Cursor uses camelCase lifecycle names and can use response fields such as `followup_message` rather than Claude’s `decision` contract.
+
+Validation checklist:
+
+1. Confirm the hook file is in `.cursor/hooks.json` or `~/.cursor/hooks.json`.
+2. Confirm the event and payload keys against the installed Cursor version.
+3. Run the hook script directly with a fixture payload.
+4. Trigger the smallest safe edit/tool flow and verify the log or follow-up output.
+5. Treat beta behavior, tool-specific gaps, and unsupported blocking/context-injection events as `NOT VERIFIABLE` until a live Cursor run proves them.
+
+Cursor references:
+
+- https://cursor.com/docs/hooks
+- https://cursor.com/changelog/1-7

package/agents-config/skills/hooks-manager/references/hook-types.md

@@ -1,4 +1,6 @@
-# Hook Types and Events
+# Shared Hook Concepts
+
+These are semantic concepts, not a universal schema. Use the platform references for the exact event spelling and blocking contract.
 
 | Event | Fires | Can block? |
 | --- | --- | --- |
@@ -8,6 +10,6 @@
 | `Stop` / `SubagentStop` | Before an agent stops | Yes |
 | `SessionStart` / `SessionEnd` | At session boundaries | No |
 | `PreCompact` | Before context compaction | Yes |
-| `Notification` | When Claude needs input | No |
+| `Notification` / native notification event | When the agent needs input | Usually no |
 
-Blocking responses should include `decision: "block"` and a useful `reason`. Stop hooks must honor `stop_hook_active` to avoid infinite loops.
+Blocking responses must use the target platform's contract. Claude/Codex commonly use `decision` and `reason`; Cursor may use a native follow-up or approval field. Stop hooks must honor the target platform's loop-prevention field, such as Claude's `stop_hook_active`.

package/agents-config/skills/hooks-manager/references/input-output-schemas.md

@@ -1,8 +1,8 @@
 # Input and Output Schemas
 
-Common hook input includes `session_id`, `transcript_path`, `cwd`, `permission_mode`, and `hook_event_name`. Tool events also include `tool_name` and `tool_input`; prompt submission includes `prompt`.
+Claude and Codex commonly provide `session_id`, `transcript_path`, `cwd`, `permission_mode`, and `hook_event_name`. Tool events commonly include `tool_name` and `tool_input`; prompt submission commonly includes `prompt`. Cursor payloads and response fields are platform-specific and must be checked against its current docs.
 
-Blocking output:
+Claude/Codex-style blocking output:
 
 ```json
 {"decision":"block","reason":"Explain what must change"}

package/agents-config/skills/hooks-manager/references/research-sources.md

@@ -0,0 +1,25 @@
+# Hook Documentation Sources
+
+This reference records the first-party sources used to maintain the platform references. Re-check them when a platform version changes.
+
+## Claude Code
+
+- [Hooks reference](https://code.claude.com/docs/en/hooks): configuration scopes, matcher behavior, events, handler types, input/output, exit codes, HTTP/MCP hooks, `/hooks`, and debugging.
+- [Hooks guide](https://code.claude.com/docs/en/hooks-guide): practical setup, stdin/stdout behavior, and common workflows.
+
+## OpenAI Codex
+
+- [Codex hook runtime](https://github.com/openai/codex/tree/main/codex-rs/hooks): upstream hook implementation and schema modules.
+- [Hook event declarations](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/lib.rs): current event names and matcher-capable event list.
+- [Codex feature flags](https://github.com/openai/codex/blob/main/codex-rs/features/src/lib.rs): the `CodexHooks` feature declaration.
+- [Codex configuration](https://github.com/openai/codex/blob/main/docs/config.md): managed-hook policy controls.
+
+## Cursor
+
+- [Cursor hooks](https://cursor.com/docs/hooks): native hook configuration and current platform behavior.
+- [Cursor Hooks beta announcement](https://cursor.com/changelog/1-7): hooks for auditing, blocking commands, and extending the Agent loop.
+- [Cursor hook catalog](https://cursor.com/marketplace/hooks/pretooluse): first-party marketplace visibility for supported hook events.
+
+## Router policy
+
+The router treats event names and response fields as platform contracts. Shared logic can be reused, but every adapter must be validated against the target agent's current docs, installed version, and one safe live event.

package/agents-config/skills/hooks-manager/references/router.md

@@ -0,0 +1,32 @@
+# Hook Router
+
+Use this routing table before editing a hook:
+
+| Target | Project scope | User scope | Load |
+| --- | --- | --- | --- |
+| Claude Code | `.claude/settings.json` or `.claude/settings.local.json` | `~/.claude/settings.json` | `claude-code.md` |
+| Codex | `.codex/hooks.json` | `~/.codex/hooks.json` | `codex.md` |
+| Cursor | `.cursor/hooks.json` | `~/.cursor/hooks.json` | `cursor.md` |
+
+## Shared intent mapping
+
+| Intent | Claude Code | Codex | Cursor |
+| --- | --- | --- | --- |
+| before a tool | `PreToolUse` | `PreToolUse` | `preToolUse` |
+| permission request | `PermissionRequest` | `PermissionRequest` | native permission event if available |
+| after a tool | `PostToolUse` | `PostToolUse` | `postToolUse` |
+| prompt submitted | `UserPromptSubmit` | `UserPromptSubmit` | `beforeSubmitPrompt` |
+| compaction | `PreCompact` / `PostCompact` | `PreCompact` / `PostCompact` | `preCompact` |
+| agent/session finished | `Stop`, `SubagentStop`, `SessionEnd` | `Stop`, `SubagentStop`, `SessionEnd` | `stop`, `subagentStop`, `sessionEnd` |
+
+The mapping is semantic, not a copy/paste schema. Read the platform reference and inspect the installed version before writing config. If an event or response field is not supported, use a portable command that logs/observes instead of claiming it can block.
+
+## Portable adapter pattern
+
+Keep policy logic in one executable that accepts JSON and emits a small internal decision. Add thin platform adapters for field extraction and response formatting:
+
+```text
+platform hook -> adapter -> shared policy -> adapter response
+```
+
+Use platform-native config files and paths. Never make a hook depend on a Claude-only variable such as `$CLAUDE_PROJECT_DIR` without providing a fallback for Codex and Cursor.

package/agents-config/skills/hooks-manager/references/troubleshooting.md

@@ -1,8 +1,8 @@
 # Troubleshooting
 
-1. Run `claude --debug` and confirm the event and matcher were found.
-2. Check the config location: `.claude/hooks.json`, `~/.claude/hooks.json`, or the plugin hook file.
-3. Validate syntax with `jq . .claude/hooks.json`.
+1. Run the target agent's debug/diagnostic mode and confirm the event and matcher were found (`claude --debug` for Claude Code).
+2. Check the platform reference for the config location: Claude settings, `.codex/hooks.json`, `~/.codex/hooks.json`, `.cursor/hooks.json`, or `~/.cursor/hooks.json`.
+3. Validate the target JSON file with `jq`.
 4. Confirm matcher case and regex escaping; `bash` does not match `Bash`.
 5. Run command hooks directly with representative JSON on stdin.
 6. Check script permissions, dependencies such as `jq`, trusted paths, and timeout values.

package/agents-config/skills/merge/agents/openai.yaml

@@ -0,0 +1,10 @@
+interface:
+  display_name: "Merge"
+  short_description: "Intelligently merge branches with context-aware conflict..."
+  icon_small: "./assets/codex-icon.svg"
+  icon_large: "./assets/codex-icon.svg"
+  brand_color: "#764627"
+  default_prompt: "Use $merge to help with this task."
+
+policy:
+  allow_implicit_invocation: false

package/agents-config/skills/merge/assets/codex-icon.svg

@@ -0,0 +1,17 @@
+<!-- @license lucide-static v1.24.0 - ISC -->
+<svg role="img" aria-label="merge skill icon"
+  class="lucide lucide-git-merge"
+  xmlns="http://www.w3.org/2000/svg"
+  width="128"
+  height="128"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#F5F5F5"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <circle cx="18" cy="18" r="3" />
+  <circle cx="6" cy="6" r="3" />
+  <path d="M6 21V9a9 9 0 0 0 9 9" />
+</svg>

package/agents-config/skills/oneshot/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: oneshot
 description: Implement one focused code change quickly with minimal exploration and targeted validation. Use for small bug fixes, single feature edits, config updates, or explicit "$oneshot" requests.
+disable-model-invocation: true
+metadata:
+  opencode/autoinvoke: "false"
+  opencode/slash: "true"
 argument-hint: <feature-description>
 ---
 

package/agents-config/skills/oneshot/agents/openai.yaml

@@ -0,0 +1,10 @@
+interface:
+  display_name: "Oneshot"
+  short_description: "Implement one focused code change quickly with minimal..."
+  icon_small: "./assets/codex-icon.svg"
+  icon_large: "./assets/codex-icon.svg"
+  brand_color: "#CF80EF"
+  default_prompt: "Use $oneshot to help with this task."
+
+policy:
+  allow_implicit_invocation: false

package/agents-config/skills/oneshot/assets/codex-icon.svg

@@ -0,0 +1,18 @@
+<!-- @license lucide-static v1.24.0 - ISC -->
+<svg role="img" aria-label="oneshot skill icon"
+  class="lucide lucide-sparkles"
+  xmlns="http://www.w3.org/2000/svg"
+  width="128"
+  height="128"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#F5F5F5"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M11.017 2.814a1 1 0 0 1 1.966 0l1.051 5.558a2 2 0 0 0 1.594 1.594l5.558 1.051a1 1 0 0 1 0 1.966l-5.558 1.051a2 2 0 0 0-1.594 1.594l-1.051 5.558a1 1 0 0 1-1.966 0l-1.051-5.558a2 2 0 0 0-1.594-1.594l-5.558-1.051a1 1 0 0 1 0-1.966l5.558-1.051a2 2 0 0 0 1.594-1.594z" />
+  <path d="M20 2v4" />
+  <path d="M22 4h-4" />
+  <circle cx="4" cy="20" r="2" />
+</svg>

package/agents-config/skills/prompt-creator/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Prompt Creator"
+  short_description: "Expert prompt engineering for creating effective prompts for..."
+  icon_small: "./assets/codex-icon.svg"
+  icon_large: "./assets/codex-icon.svg"
+  brand_color: "#60524E"
+  default_prompt: "Use $prompt-creator to help with this task."

package/agents-config/skills/prompt-creator/assets/codex-icon.svg

@@ -0,0 +1,16 @@
+<!-- @license lucide-static v1.24.0 - ISC -->
+<svg role="img" aria-label="prompt-creator skill icon"
+  class="lucide lucide-pen-line"
+  xmlns="http://www.w3.org/2000/svg"
+  width="128"
+  height="128"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#F5F5F5"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M13 21h8" />
+  <path d="M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z" />
+</svg>

package/agents-config/skills/rules-manager/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Rules Manager"
+  short_description: "Create, edit, and maintain AGENTS.md and .agents/rules/ —..."
+  icon_small: "./assets/codex-icon.svg"
+  icon_large: "./assets/codex-icon.svg"
+  brand_color: "#2F5B3E"
+  default_prompt: "Use $rules-manager to help with this task."

package/agents-config/skills/rules-manager/assets/codex-icon.svg

@@ -0,0 +1,23 @@
+<!-- @license lucide-static v1.24.0 - ISC -->
+<svg role="img" aria-label="rules-manager skill icon"
+  class="lucide lucide-notebook-tabs"
+  xmlns="http://www.w3.org/2000/svg"
+  width="128"
+  height="128"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#F5F5F5"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M2 6h4" />
+  <path d="M2 10h4" />
+  <path d="M2 14h4" />
+  <path d="M2 18h4" />
+  <rect width="16" height="20" x="4" y="2" rx="2" />
+  <path d="M15 2v20" />
+  <path d="M15 7h5" />
+  <path d="M15 12h5" />
+  <path d="M15 17h5" />
+</svg>

package/agents-config/skills/skill-manager/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skill-manager
-description: Create or edit Claude, Codex, and Cursor skills/rules. Use for SKILL.md, .cursor/rules, AGENTS.md, skill prompts, frontmatter, references, scripts, and discovery rules.
+description: Create, edit, audit, or prune Claude, Codex, and Cursor skills/rules. Use for SKILL.md, .cursor/rules, AGENTS.md, prompts, frontmatter, references, scripts, discovery, and predictable skill design.
 ---
 
 # Skill Manager
@@ -19,11 +19,16 @@ Pick the platform first, then read the matching reference file:
 - Codex      → see [references/codex.md](references/codex.md)
 - Cursor     → see [references/cursor.md](references/cursor.md)
 - Description quality → see [references/description-recommandation.md](references/description-recommandation.md)
+- Skill-writing vocabulary → see [references/skill-writing-glossary.md](references/skill-writing-glossary.md)
 
 If unsure which the user wants, ask. Default to Claude Code when working under `~/.claude/` or `.claude/`, Codex when under `~/.agents/` or `.agents/`, Cursor when under `.cursor/`.
 
 ## Core principles (all platforms)
 
+### Optimize for predictability
+
+A skill should make the agent follow the same process on repeated runs, even when the outputs differ. Treat predictability as the root quality; token cost and maintainability improve when the process is explicit and lean.
+
 ### Concise is key
 
 The context window is shared with the system prompt, conversation, other skills' metadata, and the user request. Only add context the agent doesn't already have. Challenge each line: does it justify its tokens?
@@ -44,12 +49,38 @@ Three loading levels:
 
 Keep references one level deep. Reference them by name in SKILL.md so the agent knows when to open them.
 
+### Design the information hierarchy
+
+Put ordered actions in steps and definitions or rules in reference sections. End important steps with a checkable completion criterion; vague criteria invite premature completion. Inline what every execution branch needs and move branch-specific material behind a context pointer whose wording says when to load it.
+
+Split a skill only when the split earns its cost:
+
+- **By invocation:** a distinct leading word must trigger the new skill independently.
+- **By sequence:** hiding later steps prevents the agent from rushing the current step.
+
+Every model-invoked skill spends context load through its description. Every user-only skill spends human cognitive load because the user must remember it. When user-only skills become hard to remember, add one router instead of making every skill model-invoked.
+
+### Use leading words
+
+A leading word is a compact pretrained concept such as `tight loop`, `tracer bullet`, or `handoff`. Reuse the same term in the description and body so it anchors both invocation and execution. Prefer one strong term over repeated prose that restates the same behavior.
+
+### Prune aggressively
+
+Keep each meaning in one authoritative place. Audit every sentence with the no-op test: would removing it change agent behavior? Delete no-ops instead of polishing them. Watch for:
+
+- **Duplication:** the same rule appears in several places.
+- **Sediment:** stale instructions remain because removal feels risky.
+- **Sprawl:** every line may be relevant, but the active path carries too much context.
+- **Negation:** naming forbidden behavior makes it more available; state the positive target and reserve prohibitions for hard guardrails.
+- **Negative space:** omitted decisions silently fall back to model priors; decide whether each omission is intentional.
+- **Premature completion:** sharpen the completion criterion before splitting the sequence.
+
 ### Online research routing
 
 When a skill or agent needs online research, name the exact research skill to use instead of relying on vague web-search language:
 
-- Use `/Users/melvynx/.agents/skills/find-docs/SKILL.md` for current technical documentation, API references, config options, SDKs, CLIs, cloud services, and code examples.
-- Use `/Users/melvynx/.agents/skills/exa-search/SKILL.md` for broader online research, recent information, source discovery, similar pages, URL extraction, or cited web answers.
+- Use `~/.agents/skills/find-docs/SKILL.md` for current technical documentation, API references, config options, SDKs, CLIs, cloud services, and code examples.
+- Use `~/.agents/skills/exa-search/SKILL.md` for broader online research, recent information, source discovery, similar pages, URL extraction, or cited web answers.
 - Mention default harness tools for local code, file, git, shell, and browser inspection.
 - Keep built-in `WebSearch` and `WebFetch` as fallback tools unless the user explicitly asks for them.
 - For restricted agents, include `Skill` and `Bash` in the tool list when these skills need to run local CLIs.
@@ -107,6 +138,17 @@ For researched guidance and examples, see [references/description-recommandation
 
 **Canonical personal skills:** `~/.agents/skills/` is the single source of truth (git repo `Melvynx/agents-config`). It is an official user-level root for both Cursor and Codex, so they read it directly. Write new personal skills only under `~/.agents/skills/<name>/`.
 
+### Codex profile activity icons
+
+Codex's Profile activity view does not resolve standalone skill icons from `agents/openai.yaml`. It resolves known built-in skill icons or the logo of a matching installed plugin. After creating, renaming, or changing the icon metadata of a personal skill, sync the identity-only personal plugin wrappers:
+
+```bash
+bun ~/.agents/scripts/sync-codex-profile-icons.ts --install
+bun ~/.agents/scripts/audit-codex-profile-icons.ts
+```
+
+The wrappers intentionally contain no executable skills, so they provide `logo` / `logoDark` metadata without duplicating skill discovery. Keep `~/plugins` linked to `~/.agents/plugins/plugins`; the sync script creates the link when absent.
+
 Per the official Cursor docs ([cursor.com/docs/skills](https://cursor.com/docs/skills)), user-level roots are `~/.agents/skills/` and `~/.cursor/skills/`, plus compat dirs `~/.claude/skills/` and `~/.codex/skills/`. `~/.cursor/skills-cursor/` is NOT a documented path; do not use it.
 
 Because `~/.agents/skills/` is read directly, the only symlinks needed are the compat dirs for agents that do not read `~/.agents/skills/` themselves:

package/agents-config/skills/skill-manager/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Skill Manager"
+  short_description: "Create or edit Claude, Codex, and Cursor skills/rules"
+  icon_small: "./assets/codex-icon.svg"
+  icon_large: "./assets/codex-icon.svg"
+  brand_color: "#48AAB0"
+  default_prompt: "Use $skill-manager to help with this task."

package/agents-config/skills/skill-manager/assets/codex-icon.svg

@@ -0,0 +1,23 @@
+<!-- @license lucide-static v1.24.0 - ISC -->
+<svg role="img" aria-label="skill-manager skill icon"
+  class="lucide lucide-notebook-tabs"
+  xmlns="http://www.w3.org/2000/svg"
+  width="128"
+  height="128"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#F5F5F5"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M2 6h4" />
+  <path d="M2 10h4" />
+  <path d="M2 14h4" />
+  <path d="M2 18h4" />
+  <rect width="16" height="20" x="4" y="2" rx="2" />
+  <path d="M15 2v20" />
+  <path d="M15 7h5" />
+  <path d="M15 12h5" />
+  <path d="M15 17h5" />
+</svg>