g4borg
1b5a7638d7
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
83 lines
6.5 KiB
Markdown
83 lines
6.5 KiB
Markdown
# Verification of skill-activation-mechanics report
|
|
|
|
Date: 2026-05-11
|
|
Subject: Independent fact-check of `2026-05-11-17-skill-activation-mechanics.md` against cited sources.
|
|
|
|
## Verdict summary
|
|
|
|
| Claim | Verdict |
|
|
|---|---|
|
|
| 1. `paths:` frontmatter field exists on docs page | VERIFIED |
|
|
| 2. Full frontmatter field list | VERIFIED |
|
|
| 3. Dynamic context injection via `` !`cmd` `` plus `shell:` field | VERIFIED |
|
|
| 4. The five issue numbers exist and discuss what the report claims | VERIFIED (with one caveat — see #17204) |
|
|
| 5. `.claude/rules/` `paths` glob format, no negation | VERIFIED |
|
|
|
|
All major load-bearing claims hold up. The report is accurate.
|
|
|
|
---
|
|
|
|
## Claim 1: `paths:` frontmatter field exists — VERIFIED
|
|
|
|
Source: https://code.claude.com/docs/en/skills
|
|
|
|
The frontmatter reference table on the official Skills doc page contains a `paths` row. Exact quoted description:
|
|
|
|
> `paths` — Glob patterns that limit when this skill is activated. Accepts a comma-separated string or a YAML list. When set, Claude loads the skill automatically only when working with files matching the patterns. Uses the same format as [path-specific rules](/en/memory#path-specific-rules).
|
|
|
|
The report quotes this verbatim (modulo minor formatting). VERIFIED.
|
|
|
|
## Claim 2: Full frontmatter field list — VERIFIED
|
|
|
|
The docs page lists exactly these frontmatter fields in the reference table:
|
|
|
|
`name`, `description`, `when_to_use`, `argument-hint`, `arguments`, `disable-model-invocation`, `user-invocable`, `allowed-tools`, `model`, `effort`, `context`, `agent`, `hooks`, `paths`, `shell`.
|
|
|
|
This is identical to the list in the report. No invented fields. VERIFIED.
|
|
|
|
The report's one-line summaries of each field are faithful paraphrases of the official descriptions (e.g. `name` "Lowercase letters, numbers, and hyphens only (max 64 characters)"; `description` cap "truncated at 1,536 characters"; `context: fork` "forked subagent context"; `shell` "Accepts `bash` (default) or `powershell`").
|
|
|
|
## Claim 3: Dynamic context injection `` !`cmd` `` plus `shell:` field — VERIFIED
|
|
|
|
Source: same Skills docs page, section "Inject dynamic context".
|
|
|
|
Quote:
|
|
|
|
> The `` !`<command>` `` syntax runs shell commands before the skill content is sent to Claude. The command output replaces the placeholder, so Claude receives actual data, not the command itself.
|
|
|
|
And from the frontmatter table for `shell`:
|
|
|
|
> Shell to use for `` !`command` `` and ` ```! ` blocks in this skill. Accepts `bash` (default) or `powershell`. Setting `powershell` runs inline shell commands via PowerShell on Windows. Requires `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`.
|
|
|
|
The docs also document fenced multi-line `` ```! `` blocks as an alternative. The workaround the report proposes (consolidating into one skill body and branching on `` !`ls` `` output) is consistent with how the docs describe the feature. VERIFIED.
|
|
|
|
## Claim 4: The five GitHub issues — VERIFIED (minor caveat on #17204)
|
|
|
|
All five issues exist at the cited URLs and discuss the claimed topic.
|
|
|
|
- **#17204** — Title: "Documentation: .claude/rules/ frontmatter format incorrect - globs works, paths with quotes/YAML list does not". Caveat: this is about `.claude/rules/` frontmatter format, not SKILL.md, and the report's wording "lists every syntax that does and does not work for `paths`/`globs`" is accurate (the issue tabulates working vs broken forms: `globs: ...` and unquoted `paths: ...` work; quoted strings and YAML lists do not). The report's broader inference — "None of the tested forms involve negation. The author would surely have tried it if it were a feature" — is supported: negation is never mentioned. Since SKILL.md `paths` "Uses the same format as path-specific rules" per the docs, citing this rules-format issue to bound SKILL.md `paths` behaviour is fair.
|
|
- **#21858** — Title: "[BUG] paths: frontmatter in user-level rules (~/.claude/rules/) is ignored". Matches report's "`paths` ignored at user level".
|
|
- **#23478** — Title: "Path-based rules (.claude/rules/ with paths: frontmatter) are not loaded on Write tool — only on Read". Matches report's "`paths` not triggered on Write tool, only Read".
|
|
- **#23569** — Title: "[BUG] Path-conditional rules (paths: frontmatter) ignored when loaded via git worktree resolution". Matches report's "`paths` ignored under worktree path resolution".
|
|
- **#16853** — Title: "[BUG] Path-scoped rules in `.claude/rules/` not automatically loaded when working with matching files". Matches report's "`paths` not auto-loading on matching file work".
|
|
|
|
All five concern `.claude/rules/` paths (the same format SKILL.md `paths` reuses), not SKILL.md directly. The report's framing as "evidence the feature is not mature enough to expect undocumented negation to work" is sound but worth noting: these are rules-side bugs cited as a proxy for skills-side maturity. VERIFIED.
|
|
|
|
## Claim 5: `.claude/rules/` `paths` glob format, no negation — VERIFIED
|
|
|
|
Source: https://code.claude.com/docs/en/memory, section "Path-specific rules".
|
|
|
|
Quoted documentation of the glob format:
|
|
|
|
> Use glob patterns in the `paths` field to match files by extension, directory, or any combination... You can specify multiple patterns and use brace expansion to match multiple extensions in one pattern.
|
|
|
|
Documented patterns: `**/*.ts`, `src/**/*`, `*.md`, `src/components/*.tsx`, and brace-expansion form `src/**/*.{ts,tsx}`. All positive. No `!pattern`, `-` exclude, or any other negation operator is mentioned anywhere on the Memory page or the Skills page. VERIFIED.
|
|
|
|
---
|
|
|
|
## New findings not in the original report
|
|
|
|
1. **The Skills docs explicitly say `paths` "Uses the same format as path-specific rules"**, hyperlinking the Memory page anchor. This makes the report's reuse claim explicit (and slightly stronger than the report frames it — it is not just convention, it is a documented equivalence).
|
|
2. **#17204 is itself a bug about format parsing**: quoted strings and YAML lists in `paths:` are documented but reportedly broken in `.claude/rules/`, with only the undocumented `globs:` field and bare-unquoted `paths:` working reliably. If this same parsing bug applies to SKILL.md `paths`, the YAML-list form the docs recommend may not actually work in practice. The report does not surface this. **Worth investigating before relying on `paths: ["a", "b"]` in SKILL.md.**
|
|
3. The Skills docs also document a settings escape hatch — `disableSkillShellExecution: true` — that disables `` !`cmd` `` injection. If a managed environment sets this, workaround #2 in the report (branching skill body on `` !`ls` `` output) silently degrades. The report should flag this dependency.
|