dirigence/reliquary
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
reliquary/docs/workpad/reports/2026-05-11-17-skill-engines-cross-tool.md
T
g4borg 1b5a7638d7 🧠 Add brain-dump docs for skill adaptation 
Add exploratory and design docs for porting dirigent skills to
reliquary, including:
- Explore port options for the gitea skill (in-plugin vs vendored)
- Document activation mechanics across Claude Code and cross-tools
- Include an orchestration comparison between dirigent and reliquary
  approaches
- Add research on glob negation and flag-file activation patterns
- Create uv-detection goals and skill-engines cross-tool reports
- Provide a research plan for future porting work and risk notes
2026-05-11 23:01:30 +02:00

146 lines
14 KiB
Markdown
Raw Permalink Blame History

# Skill Engines Across Coding-Agent Harnesses
**Date:** 2026-05-11
**Question:** How do non-Claude coding agents handle "skills" / reusable instruction modules, and what frontmatter / activation conditions do they expose? Does the user's "boolean-condition flag-file activation" design port cross-tool, or is it Claude-only?
---
## 1. OpenAI Codex CLI
### What it does
Codex CLI is the closest cousin to Claude Code. It supports **AGENTS.md** as memory, plus a parallel set of extension surfaces: **Skills**, **Plugins**, **Hooks**, **Subagents**, **Rules**, and **MCP servers**. The skill system is explicitly modeled on the Agent Skills open standard, so SKILL.md authoring is near-identical to Claude's.
### What activation conditions it supports
- **AGENTS.md discovery** — hierarchical walk from repo root down to cwd, picking up at most one of `AGENTS.override.md`, `AGENTS.md`, or any name in `project_doc_fallback_filenames`. No frontmatter on AGENTS.md itself. ([Codex AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md))
- **SKILL.md frontmatter** — required: `name`, `description`. Docs explicitly say: *"Do not include any other fields in YAML frontmatter."* UI metadata, invocation policy, and tool deps go in a sibling `agents/openai.yaml`. ([Codex Skills](https://developers.openai.com/codex/skills))
- **Path-glob activation for skills** — **NOT YET SHIPPED.** Tracked as feature request [openai/codex#19671](https://github.com/openai/codex/issues/19671), which proposes the same `paths:` frontmatter Claude already has.
- **Rules** — a `.rules` Starlark file under `rules/` directories (user / team / project layers). This is an execution-policy mechanism (used by `codex execpolicy check`), not a context-injection mechanism. ([Codex Rules](https://developers.openai.com/codex/rules))
- **InstructionsLoaded-equivalent hooks** — also not shipped; tracked as [openai/codex#21675](https://github.com/openai/codex/issues/21675) ("Codex Rules: per-session cache for additionalContext (Claude Code InstructionsLoaded parity)").
### Relevance to flag-file design
Codex has a real skill system and pre-loads `name` + `description` exactly like Claude, so description-driven activation ports cleanly. But path-scoped activation is a missing feature, and there is **no documented mechanism today for boolean conditions, file-presence triggers, or negation** on skill loading. A flag-file design would have to be encoded entirely inside the `description` string ("Use when …") and rely on the model to read it; Codex would not enforce it.
---
## 2. Google Gemini CLI
### What it does
Gemini CLI uses **GEMINI.md** as its memory file with a richer import system than AGENTS.md, plus an **Extensions** system that bundles MCP servers, prompts, custom commands, hooks, sub-agents, and (per the docs) "agent skills". ([Gemini extensions](https://google-gemini.github.io/gemini-cli/docs/extensions/))
### What activation conditions it supports
- **GEMINI.md hierarchical loading** — concatenates files found by walking the workspace tree; also discovers GEMINI.md files in directories tools touch, up to a trusted root. ([Gemini-md docs](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md))
- **`@file.md` imports** — splits big GEMINI.md into smaller files, relative or absolute paths. Same syntax as Claude's `@path` imports.
- **Extension manifest (`gemini-extension.json`) fields** — `name`, `version`, `mcpServers`, `contextFileName`, `excludeTools`. **No activation conditions, no path scoping, no boolean triggers.** Extensions load globally on startup.
- **No frontmatter on GEMINI.md itself** documented.
### Relevance to flag-file design
Activation is effectively "always-on per directory" (via tree-walk) or "always-on per extension". There is **no conditional / flag-file mechanism**. The directory-discovery model is the only scoping primitive — you'd have to place a `GEMINI.md` in a specific subdir to scope advice to it.
---
## 3. Cursor / Windsurf / Aider / Continue
### Cursor (`.cursor/rules/*.mdc`)
Four activation modes via frontmatter ([Cursor rules guide](https://www.morphllm.com/cursor-rules-best-practices), [community reference](https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/cursor-rules-reference.md)):
- `alwaysApply: true` — every conversation
- `globs: <patterns>` — auto-attach on matching file open
- `description: …` — agent-requested (model decides from text)
- Manual `@rule-name`
Fields: `description`, `globs`, `alwaysApply`. **No boolean conditions, no negation, no file-presence triggers**, no path-negation. A proposed `mode` field for targeting Agent/Plan/Debug/Ask is still just a [feature request](https://forum.cursor.com/t/mode-frontmatter-field-in-mdc-rules-for-built-in-mode-targeting-agent-plan-debug-ask/157675).
### Windsurf (`.windsurf/rules`)
Explicit `trigger:` field with four enumerated values ([Windsurf rules guide](https://design.dev/guides/windsurf-rules/), [.windsurfrules guide](https://www.claudemdeditor.com/windsurfrules-guide)):
- `always_on`
- `manual`
- `model_decision` (description-driven)
- `glob` (with companion `globs:` field)
Hard char budget: 12,000 per workspace rule, 6,000 global. Rules exceeding budget are silently dropped. **No boolean conditions or flag-file triggers**; `trigger` is a single enum, not a composable predicate.
### Aider
A flat **CONVENTIONS.md** (any file you pass via `--read`). No frontmatter, no scoping, no skill system. Always-on or nothing. ([Aider conventions](https://aider.chat/docs/usage/conventions.html))
### Continue.dev
`.continue/rules/*.md` with YAML frontmatter supporting `name`, `globs`, `alwaysApply`, `description` — same triad as Cursor. ([Continue rules](https://docs.continue.dev/customize/deep-dives/rules)) AGENTS.md root-file support is still an [open issue](https://github.com/continuedev/continue/issues/6716).
### Bottom line for this tier
All four converge on the **same activation primitives**: always-on, manual, glob, or description-driven. **None** support boolean logic, negation, or file-existence predicates.
---
## 4. Claude Code: other activation mechanisms beyond `paths`
Citations all from [code.claude.com/docs/en/memory](https://code.claude.com/docs/en/memory), [hooks](https://code.claude.com/docs/en/hooks), and [skills](https://code.claude.com/docs/en/skills).
### What it does and what activates
- **`@path/to/file` imports in CLAUDE.md** — relative or absolute, recursive up to 5 hops. Imported files always load at session start. Not conditional.
- **`` !`<command>` `` dynamic context injection** — runs shell pre-render in skills (and the bash-and-skip-it custom command files). Output is inlined before Claude sees the skill. This **is** the closest native primitive to a flag-file: you can write `` !`test -f .reliquary/flag && echo active || echo inactive` `` and branch instructions on the result. Shell-gated, but real.
- **Path-tree CLAUDE.md walking** — ancestors load eagerly, descendants load lazily when files in them are read. The descendant case is effectively a file-presence trigger ("Claude opened a file under `foo/` → `foo/CLAUDE.md` loads").
- **`.claude/rules/*.md` with `paths:` frontmatter** — same glob mechanism as skills, but loads as rule rather than command. ([Path-specific rules](https://code.claude.com/docs/en/memory))
- **SKILL.md frontmatter beyond `paths`** — `name`, `description`, `when_to_use`, `argument-hint`, `arguments`, `disable-model-invocation`, `user-invocable`, `allowed-tools`, `model`, `effort`, `context: fork`, `agent`, `hooks`, `paths`, `shell`. Notably **no boolean condition field, no `requires:`, no `unless:`, no negation.**
- **`hooks.SessionStart` / `UserPromptSubmit` / `InstructionsLoaded` / 6 others** with `additionalContext` — a hook script can inspect the filesystem (`test -f`, `cat`, `git status`) and inject arbitrary context strings dynamically. This is the **most powerful conditional-activation primitive in Claude Code**: it runs deterministic shell logic and returns `additionalContext` which Claude reads as if it were a system message. ([Hooks docs](https://code.claude.com/docs/en/hooks))
- **`skillOverrides`** in `.claude/settings.local.json` — four states per skill (`on` / `name-only` / `user-invocable-only` / `off`). User-level toggle, not condition-based.
- **`skillListingBudgetFraction`** — fraction of context window (default 1%) used for skill descriptions; affects whether descriptions get truncated, not whether skills load.
- **`maxSkillDescriptionChars`** — per-entry cap (default 1,536).
- **`disableSkillShellExecution`** — disables `` !`cmd` `` injection org-wide (managed-settings escape hatch).
- **`claudeMdExcludes`** — glob-based negative filter, but at the memory-file level, not skill level.
### Relevance to flag-file design
Claude Code is the **only surveyed harness** that natively supports a boolean / file-presence activation primitive — and it does so through two channels:
1. **Inline `` !`shell` `` inside a skill** (skill is "listed" unconditionally, but its body becomes a no-op when the flag is absent).
2. **A SessionStart hook** that injects (or doesn't inject) a snippet of `additionalContext` based on `test -f .reliquary/flag`.
Neither is a frontmatter-declarative `requires-file:` field — those don't exist in any surveyed tool — but both are usable today, and the InstructionsLoaded hook in particular gives Claude something no other harness offers.
---
## Comparison table
| Tool | Memory file | Skill concept | Frontmatter activation fields | Boolean / file-presence triggers |
| --- | --- | --- | --- | --- |
| Claude Code | CLAUDE.md (+ `@imports`, tree-walk, `.claude/rules/`) | Yes (SKILL.md, full system) | `paths`, `description`, `when_to_use`, `disable-model-invocation`, `user-invocable`, `context`, `hooks`, +more | **Yes**, via `` !`cmd` `` injection and SessionStart/InstructionsLoaded hooks |
| Codex CLI | AGENTS.md (hierarchical, override files) | Yes (SKILL.md; only `name`/`description` allowed) | `name`, `description` (paths is requested, not shipped) | No |
| Gemini CLI | GEMINI.md (tree-walk, `@file` imports) | Via extensions (manifest-bundled) | `name`, `version`, `mcpServers`, `contextFileName`, `excludeTools` — extension-level only | No |
| Cursor | `.cursor/rules/*.mdc` | Rules (no separate skill) | `description`, `globs`, `alwaysApply` | No |
| Windsurf | `.windsurf/rules` | Rules (no separate skill) | `trigger` (enum: always_on / manual / model_decision / glob), `globs` | No |
| Aider | CONVENTIONS.md | None | None | No |
| Continue.dev | `.continue/rules/*.md` | Rules | `name`, `globs`, `alwaysApply`, `description` | No |
---
## Recommendation
**Of the surveyed harnesses, Claude Code is the only one that supports boolean-condition / flag-file activation today**, via two non-frontmatter routes: inline `` !`shell` `` inside a SKILL.md, and a SessionStart/InstructionsLoaded hook that conditionally returns `additionalContext`. No tool — including Claude — exposes a declarative `requires-file:` or boolean-predicate frontmatter field.
**Cross-tool portability of the user's flag-file design: limited.**
- Description-driven activation ("Use when project has a `.reliquary/` directory") works as a soft hint everywhere that has a skill/rule concept (Claude, Codex, partially Cursor/Windsurf/Continue), but the model decides — not the harness.
- Hard, harness-enforced flag-file gating is Claude-only. Codex would need either the proposed [#19671](https://github.com/openai/codex/issues/19671) (path globs) or [#21675](https://github.com/openai/codex/issues/21675) (InstructionsLoaded parity) to land before it could replicate the pattern.
- The portable lowest common denominator is: ship the skill, give it a tight `description` that names the flag file, and document a manual `/skill-name` invocation as the cross-tool fallback. Claude users additionally get a hook that auto-activates it.
If the user wants real enforcement now, lean on the Claude InstructionsLoaded hook + `disable-model-invocation: true` skills, and treat Codex/Gemini/Cursor as "best-effort, description-driven" targets.
---
## Sources
- [Claude Code memory docs](https://code.claude.com/docs/en/memory)
- [Claude Code hooks docs](https://code.claude.com/docs/en/hooks)
- [Claude Code skills docs](https://code.claude.com/docs/en/skills)
- [Codex AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md)
- [Codex Skills](https://developers.openai.com/codex/skills)
- [Codex CLI features](https://developers.openai.com/codex/cli/features)
- [Codex Rules](https://developers.openai.com/codex/rules)
- [openai/codex#19671 — path globs for skills](https://github.com/openai/codex/issues/19671)
- [openai/codex#21675 — InstructionsLoaded parity](https://github.com/openai/codex/issues/21675)
- [Gemini-md docs](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md)
- [Gemini extensions](https://google-gemini.github.io/gemini-cli/docs/extensions/)
- [Cursor mdc best practices (Morph)](https://www.morphllm.com/cursor-rules-best-practices)
- [Cursor mdc rules reference (community)](https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/cursor-rules-reference.md)
- [Cursor mode field feature request](https://forum.cursor.com/t/mode-frontmatter-field-in-mdc-rules-for-built-in-mode-targeting-agent-plan-debug-ask/157675)
- [Windsurf rules guide (design.dev)](https://design.dev/guides/windsurf-rules/)
- [.windsurfrules guide](https://www.claudemdeditor.com/windsurfrules-guide)
- [Aider conventions](https://aider.chat/docs/usage/conventions.html)
- [Continue.dev rules](https://docs.continue.dev/customize/deep-dives/rules)
- [continuedev/continue#6716 — AGENTS.md support](https://github.com/continuedev/continue/issues/6716)
Reference in New Issue View Git Blame Copy Permalink