docs(skills): lead two skill descriptions with their activation conditions - #437
Merged
Merged
Conversation
Bootstrap-only SSoT write permitted by AGENTS.md §Non-ship SSoT write exceptions and required by bootstrap.md §1; applied through guard_context_write.py, which also rewrites the mirrored guard receipt. No other SSoT field is touched. Logged in the Work Log Drift Log. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…tions `systematic-debugging` and `production-readiness` both described their technique or benefit and left the "when" to the body and the metadata. app-init.md:200 already requires a skill `description` to carry "both capability and activation context", so the conditions now come first and the technique second. Both sentences are derived from what already exists, not invented: - systematic-debugging covers all three registry `failure_signals` (test-failure, unexpected-behavior, repeated-patch-failure), the `scope_signals` bug / flaky, and two conditions its body lists that the old description did not: the hotfix path (SKILL.md:20 "Hotfix incident response", the first When-to-Use bullet; the description carries it as the token "a hotfix") and an unexplained fix (SKILL.md:23 "fixed but I don't know why", the last one). - production-readiness leads with the phase bound so it governs BOTH arms of the sentence, matching registry `phase_scope: [review, ship]` and `phase_conditions: [enter-review-or-ship]`, which apply to the automatic and the on-request path alike. It neither widens into /implement nor suppresses the automatic recommendation, which lives in bootstrap.md:383 and routing.md:136, not in the description. It is in fact tighter than the text it replaces: "Pre-ship" is an open interval that admits /implement, "at review and ship" is a closed enumeration. Both sentences are also shorter than the first draft of this change, and that is a governed constraint rather than a style preference. `analyze_token_lifecycle.py` counts each SKILL.md by total length, once per scenario it is a candidate for plus its load and continuation multipliers -- measured at ~2.33 tokens per added character across the six scenarios. The aggregate ceiling in test_aggregate_current_total_stays_under_355k had 431 tokens of headroom at 3d36854 (354569), so the fuller wording landed at 355225 and turned the suite red. Measured, not estimated: 3d36854 baseline 354569 (headroom 431) full wording 355225 (over by 225, FAIL) this revision 354887 (headroom 113, PASS) Every activation condition either reviewer asked for is retained; the technique and benefit clauses carry the compression. Raising the ceiling was deliberately NOT done: that test's comment records four prior transitions (350k->352k->353k->354k->355k), each justified in place and the most recent labelled an owner-approved minimal bump, and this addition is not deletion-funded. The compact-index change is generated, not hand-edited: build_compact_index hashes each entry's detail_ref (trigger_runtime_core.py:757-763), so the two `content_hash` fields move and nothing else does. Skill names, bodies, phase/classification eligibility, trigger-registry conditions, load policies and permissions are unchanged. Scope and reach, stated honestly rather than implied: - Only the vendor-neutral `.agents/skills/<name>/SKILL.md` surface is edited. `.agent/skills/<name>` (Antigravity) and `agents/openai.yaml short_description` (Codex) still carry the old wording, and no validator binds the three: validate_trigger_metadata.py compares six summary fields and eight mirror fields against the registry and `description` is among neither, while the parity rule at trigger_runtime_core.py:693-698 -- the only description comparison in the tool -- is reached only for a skill shipping a per-skill manifest.yaml, which neither of these does. Left as a separate unit deliberately: `.agent/skills/**` is guard-protected (config.yaml:192) and sync_skills.sh would clobber required keys. - No live-model activation was measured, and this repo has no host skill discovery directory for the edited surface to participate in. This is a documentation-contract change with static validation only. Ref: docs/reviews/2026-09-09-cross-model-skill-handoff.md Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The handback answers the brief's section-10 request item by item: revision and base SHA, every file in the diff with a reason, the AC1-AC6 table with its unproven parts named, the five review rounds with dispositions, the cross-model matrix as a not-run table with reasons, and the remaining risks. Two findings are filed rather than folded into the product change: - #198: the three skill description surfaces are unbound and have diverged. validate_trigger_metadata.py compares seven summary and eight mirror fields and description is in neither set; the rule that would bind them only fires for a skill shipping a per-skill manifest.yaml, and no first-party skill ships one, so that check is inert repo-wide. - #199: app-init.md:200 requires descriptions to carry activation context, while analyze_token_lifecycle.py charges ~2.33 tokens per SKILL.md character. The aggregate ceiling had 431 tokens of headroom for the whole repo, so the contract is unaffordable for the remaining twelve skills. Clarifying two descriptions already consumed most of it. The compaction overflow carries the narrative sections that exceeded the 12KB active-log cap; gate receipts and evidence stay in the active log. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Ship History entry inserted at the top of the section via guard_context_write --mode replace (append is O_APPEND and would drop it at the bottom, breaking newest-first). Work Log MOVED, not copied, to the archive root; the archive index entry is chained through append_chain_entry.py and check_audit_chain.py reports the chain intact. The Ship History entry leads with the finding rather than the change: the token ratchet, not the wording, decided the final text. Clarifying two descriptions to the standard app-init.md:200 already requires measured 355225 against a 355000 ceiling that had 431 tokens of headroom for the whole repo. Filed as #199, because the remaining twelve skills cannot meet that contract until someone decides between a ceiling bump, deletion funding, or charging probe cost against frontmatter instead of the whole body. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
F2 - the handback's central conclusion was wrong. Section 7 argued that no host reads .agents/skills/*/SKILL.md for skill selection, generalising from Claude Code's .claude/skills/ convention to every host. Codex scans .agents/skills and matches on the frontmatter description; openai.yaml short_description is optional UI metadata, not the selection input. The reviewer observed its own host catalog already carrying both new descriptions while the on-disk short_description was unchanged. This repo had already said as much - check_skill_provenance.py:16 calls that frontmatter the "portable discovery contract" - and I read that file during planning without weighing it. Sections 7, 8, 9 and the AC5 row now state consumers host by host. Backlog #198 is correspondingly smaller: a consistency defect across the Antigravity stub and the UI mirror, not a selection defect. What does not change: no live A/B was run by either party, so exposure in a host catalog is not a measured trigger-rate improvement, and both skill description lines are untouched. F1 - the unit recorded an internal ship closure at ab0f48c before the required final review, against the brief's own boundary at handoff.md:26. Nothing was pushed, merged or released. The ship receipt, the archived Work Log, the Ship History entry and the audit chain are preserved unedited, because deleting them would destroy the evidence that the boundary was crossed; a correction is recorded alongside them and the unit is reopened in a follow-up Work Log pending Codex acceptance. Records only. No skill wording, metadata, ceiling or #198/#199 work. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…tance Codex re-reviewed the correction batch (df53e48) and returned PASS for both the bounded change and the F1/F2 corrections; the user then delegated the remaining records closure. Its final review and its one-line correction to handback risk item 4 - which still leaned on the refuted "vacuous experiment" premise that df53e48 missed - are committed as Codex wrote them. Both Work Logs are archived by MOVE. The reviewer's log keeps its own receipts untouched: its last receipt is review NOT READY and its acceptance lives in its prose, and AGENTS.md Write Isolation keeps each session to its own log, so no receipt was written into it on Codex's behalf. The follow-up log's plan and implement receipts were not written when that work happened on 2026-09-09. They are recorded at closure with the real current timestamp and labelled as such in its Drift Log - not backdated, per Codex's explicit instruction. The premature ship closure at ab0f48c stays in history with its forward correction alongside it. Product unchanged since 10cf38b. Carried limitation: Codex catalog exposure was observed; no paired trigger-rate experiment was run on any host. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Terminal evidence write: records the validator, audit-chain and product-diff results taken after the final lifecycle writes. Evidence text only. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
KbWen
added a commit
that referenced
this pull request
Sep 10, 2026
…cords (#438) ## Summary `/retro` for #437. That unit's durable learnings had been written into Claude-private memory, which Codex and Gemini sessions cannot read. This moves them into the repo's own record surfaces, where every host looks. **Records only.** No skill wording, workflow, rule, metadata or token-ceiling change. | Surface | Change | Why there | |---|---|---| | `current_state.md` Global Lessons | **+1** `[skill-description-cost][HIGH][editing-skill-md]` | A behavioural pattern. As a HIGH lesson it surfaces in the `/implement` pre-execution review on every host - exactly when someone is about to edit a SKILL.md | | `current_state.md` Global Lessons | **−1** `[classification-flow]` (MEDIUM, the GENESIS entry), archived | Registry was at cap 20 with zero LOW entries, so `/retro`'s LOW-only path could not free a slot. Chosen by the repo owner; `bootstrap.md:25` already encodes it as a rule | | `.agent/rules/repo-gotchas.md` §16 | +1 paragraph | A mechanical fact: the SKILL.md frontmatter `description` is consumed host-side. Codex selects on it; `openai.yaml` is UI metadata; Claude Code does not read `.agents/skills` in this layout | | Ship History | new entry + rotation of the 2 oldest into `archive/ship-history-2026.md` | The #437 ship had taken the section to 11 without rotating; owed by that unit | ### The new lesson Each character added to a `.agents/skills/*/SKILL.md` costs ~2.33 tokens against the aggregate lifecycle ceiling (~8.9x its own size), with 113 tokens of headroom. On #437 the targeted tests, both validators and two review rounds stayed green on a tree that breached it; only the full suite caught it. Backlog **#199** is the open decision. ### Why one lesson rather than four Two of #437's record errors violated lessons already in the registry (`[signal-preservation]` for a swallowed exit code, `[audit-verification]` for trusting a reviewer's claim). Adding near-duplicates to a full registry adds length, not obedience. The other two are recorded in the committed review documents and archived Work Logs. ## A defect I introduced and fixed before opening this The first version of the §16 paragraph cited `check_skill_provenance.py` by bare filename. `repo-gotchas.md` ships force-update core tier and that tool is not in the deploy set, so every adopter would have been pointed at a file they do not have - another instance of **#192**. `test_deployed_governance_referenced_tools_are_deployed` stayed green because it matches only full `.agentcortex/tools/<name>.py` paths; #192 already records that bare basenames evade it. Fixed in `80401a7` by stating the fact without the citation. ## Verification All run after the last write, against the branch tip: | Check | Result | |---|---| | `validate.sh` / `validate.ps1` | both exit 0, `pass=99 warn=4 fail=0 skip=3`, WARN sets identical | | `check_lesson_chain.py` | intact, 20 lessons | | `check_audit_chain.py` | intact, including the archive bridge record | | `test_repo_gotchas_discoverability.py`, `test_deploy_tiering.py` (whole file), `test_lesson_chain_archival.py` | 51 passed, 1 skipped | | `analyze_token_lifecycle.py` aggregate | 354887 before and after - delta 0, measured | | Directive-keyword scan of `repo-gotchas.md` | 0 hits | The 4 WARNs are pre-existing. `pass` reads 99 because no Work Log is active after archival. No subagent review was run; review is optional for quick-win and this is stated rather than implied. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
lawandtaxcarebd-byte
pushed a commit
to lawandtaxcarebd-byte/agentic-os
that referenced
this pull request
Sep 15, 2026
Seven version surfaces + CITATION date-released, CHANGELOG entry for the units merged since v1.8.26 (KbWen#425, KbWen#436, KbWen#437, KbWen#438, KbWen#435), Ship History entry with cap-10 rotation, heartbeat 172, Work Log archived and chained. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two skill
descriptionfrontmatter lines now lead with their activation conditions instead of their technique, asapp-init.md:200already requires ("description MUST include both capability and activation context"). The compact index is regenerated mechanically because it hashes each skill body.Product diff: two lines plus two generated
content_hashfields. Everything else in this PR is review, evidence and lifecycle records.systematic-debuggingproduction-readinessNames, bodies, phase and classification eligibility, trigger-registry conditions, load policies and permissions are unchanged. The
production-readinesswording is tighter than before, not looser:Pre-shipwas an open interval that admitted/implement, whileat review and shipis a closed enumeration equal tophase_scope.Two findings, filed rather than folded in
analyze_token_lifecycle.pycharges ~2.33 tokens per added SKILL.md character (~8.9x its own size, across six scenarios). The aggregate ceiling had 431 tokens of headroom for the whole repo at the base commit. The first wording measured 355225 against the 355000 ceiling and turned the suite red; this PR ships at 354887 by compressing both sentences. The ceiling was not raised. The remaining twelve skills cannot meetapp-init.md:200until someone decides between a ceiling bump, deletion funding, or charging probe cost against frontmatter rather than the whole body.SKILL.md, the Antigravity stub and theopenai.yamlUI mirror disagree, and nothing compares them. Scoped down after review:openai.yaml short_descriptionis optional UI metadata, not the selection input, so this is a consistency defect rather than a selection defect.Review
.agents/skills/*/SKILL.mdfor selection, generalising from Claude Code's.claude/skills/convention. Codex scans.agents/skillsand matches ondescription, and it observed both new descriptions in its own catalog. This repo'scheck_skill_provenance.py:16already called that frontmatter the "portable discovery contract".Full record:
docs/reviews/2026-09-09-cross-model-skill-handback.mdanddocs/reviews/2026-09-09-cross-model-skill-final-review.md.Verification
pytest tests/ci/ tests/guard/ .agentcortex/tests/on the product treetest_aggregate_current_total_stays_under_355kvalidate.sh/validate.ps1on the closed treepass=99 warn=4 fail=0 skip=3, WARN sets identicalcheck_audit_chain.pyvalidate_trigger_metadata.py,generate_compact_index.py --check,check_skill_provenance.pyThe 4 WARNs are pre-existing and unchanged by this branch.
passreads 99 rather than 117 because no Work Log is active after archival, so 18 active-log checks collapse into one SKIP.Limitations
scaffoldtier, so existing adopters keep their copies and only fresh installs receive the new wording. No adopter action needed.🤖 Generated with Claude Code