Skip to content

docs: point the custom-* skills row at its activation on-ramp - #436

Merged
KbWen merged 1 commit into
mainfrom
fix/292-custom-skill-onramp-pointer
Sep 7, 2026
Merged

docs: point the custom-* skills row at its activation on-ramp#436
KbWen merged 1 commit into
mainfrom
fix/292-custom-skill-onramp-pointer

Conversation

@KbWen

@KbWen KbWen commented Sep 7, 2026

Copy link
Copy Markdown
Owner

Summary

Closes the documentation half of #292 — the split the issue's own triage analysis recommended shipping standalone as a tiny-fix.

docs/INSTALL.md's "Customizing without conflicts" table had a one-cell asymmetry between two sibling extension seams:

  • "Connect an external knowledge base" points at knowledge_sources: in .agentcortex/context/private/downstream-capabilities.yaml.
  • "Add your own skills" told the adopter where to put a custom-* skill and that it survives upgrades — but not that survival is not activation.

Verified against the code, an undeclared custom-* skill is genuinely second-class:

  • .agent/workflows/bootstrap.md:405 — a skill id resolves only via the §3.6 rule table, the compact index, or a custom-* id declared in downstream-capabilities.yaml §skills; anything else is "unknown → ignore". So an undeclared custom-* id is never auto-recommended and cannot be pinned from user-preferences.yaml.
  • docs/adr/ADR-007-...:33-38 states the same outright ("Custom skills are second-class … cannot auto-activate").

The row now says so and points at the existing opt-in on-ramp, mirroring the shape of its sibling row (pointer + ADR link + the on-match cap).

Adopter delta: an adopter reading INSTALL now learns from the same table that a custom-* skill needs a one-line declaration to become activatable. Engine behaviour is unchanged — no new detector, no auto-discovery (still rejected by ADR-007), no always-on cost.

This deliberately does not build the runtime bootstrap detector the issue proposes; that half stays demand-gated per the issue's own report-trigger framing, so #292 is referenced, not closed.

Evidence

Validator — bash .agentcortex/bin/validate.sh:

[PASS] token lifecycle drift: within slack
Summary: pass=99 warn=4 fail=0 skip=3
Agentic OS integrity check passed
[exited with code 0]

Pinned test module (docs/INSTALL.md carries substring assertions in this file, so it was re-run rather than assumed doc-safe):

$ python -m pytest tests/ci/test_deploy_tiering.py -q
38 passed, 1 skipped in 343.50s (0:05:43)

Table integrity re-checked after the edit (14 table rows before and after; single-line diff, no merged rows). Link target docs/adr/ADR-007-downstream-capability-declaration-seam.md confirmed to exist.

Scope: 1 file, 1 line changed, doc-only.

Refs #292

🤖 Generated with Claude Code

The "Add your own skills" row in the INSTALL.md extension-points table
told adopters where to put a custom skill and that it survives upgrades,
but not that it stays inert until declared. Its sibling row (external
knowledge base) already points at downstream-capabilities.yaml; this
closes the one-cell asymmetry.

Refs #292

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@KbWen
KbWen merged commit 564fae9 into main Sep 7, 2026
17 checks passed
@KbWen
KbWen deleted the fix/292-custom-skill-onramp-pointer branch September 7, 2026 13:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant