[Feature] Surface adopter's pre-existing skills + the custom-* on-ramp at bootstrap

[KbWen]

Scenario

An adopter deploys Agentic OS into a repo that already has skills installed — their own, or from other packs (.claude/skills/, .cursor/rules/, community skill repos). Today those skills coexist safely (deploy never overwrites them; custom-* is a reserved namespace), but the adopter has no signal that they can make those skills activatable inside the gated workflow.

Current handling (by design)

• Coexistence is solid: deploy.sh never overwrites pre-existing files (.acx-incoming sidecars), and the framework only ever touches its own skill set — foreign skills are left untouched.
• There is an on-ramp, but it's invisible: ADR-007 lets an adopter declare their own custom-* skills in .agentcortex/context/private/downstream-capabilities.yaml to union them into auto-activation (capped at load_policy: on-match, gate-safe). Nothing surfaces this on-ramp at deploy/bootstrap.
• Auto-discovery is deliberately rejected (ADR-007): auto-activating undeclared third-party skill descriptions is an untrusted-activation surface. Any solution must stay opt-in.

Proposal (opt-in detector, NOT auto-activation)

A present-only bootstrap/deploy advisory: when an adopter skill directory (.claude/skills/, etc.) is detected and populated, surface a one-line pointer to the existing custom-* + downstream-capabilities.yaml on-ramp. It never reads, executes, or activates a foreign skill — it just makes the manual on-ramp discoverable.

Why this issue exists (report-trigger, not a pre-build)

Per evidence-before-adding we won't add an always-on detector without demand. Comment if: you adopted Agentic OS with existing skills and (a) didn't realize you could declare them, or (b) want bootstrap to point you at the on-ramp. That demand promotes this from idea to build.

[KbWen]

Triage Analysis — #292 Surface pre-existing skills + the custom-* on-ramp at bootstrap

Automated daily triage. Read-only diagnosis; no code changed. All claims below verified against files at 14ac9d9 (v1.8.23).

1. Priority Assessment

Backlog row #101 (docs/specs/_product-backlog.md:70) — P3, feature, Pending. This is a report-trigger issue, opened 2026-06-28 to gather adopter signal before building, per the issue-exposure policy recorded at _product-backlog.md:165.

The trigger has not fired in 57 days: zero comments, zero linked references. A code-search probe for the framework's own fingerprints returns only this repo:

gh search code 'downstream-capabilities.yaml'  -> ["KbWen/agentic-os"]
gh search code '"⚡ ACX" AGENTS.md'            -> []

Caveat, stated honestly: copy-in adoption is invisible to code search, so this is evidence of no visible adopter, not proof of none. But it does mean the population that could file the report is, as far as is observable, empty — the trigger cannot fire on its own schedule.

Its sibling report-trigger #291 (backlog #100) was closed 2026-08-17 with a sharpened reopen trigger and its signal home moved to the backlog row. #292 is the last member of that 2026-06-28 pair still standing open.

2. Root Cause Analysis — the on-ramp really is invisible

The issue's premise holds; every leg is verifiable:

• Coexistence is solid. deploy.sh:271-272 / :294-295 never overwrite a pre-existing or locally-modified file — the incoming version is written to a visible <file>.acx-incoming sidecar. Foreign skills are untouched.
• A custom-* skill is genuinely second-class until declared. It is not in the §3.6 rule table, so it is never auto-recommended; and bootstrap.md:405 (§3.6a step 3) validates pinned IDs against the rule table / compact index or a custom-* id declared in downstream-capabilities.yaml §skills — an undeclared custom-* id is "unknown → ignore". Net effect: an undeclared custom skill can only be reached by the user naming it in chat. ADR-007:34 states this outright.
• Nothing points at the on-ramp. bootstrap.md:115-116 (§1b) is present-only by design: absent file → "zero reads, zero tokens; record Downstream-Capabilities: none … and skip." Correct for token cost, but it means an adopter who never creates the file never learns it exists.

3. A separate, demand-independent gap found while verifying (worth splitting out)

The issue frames the fix as a runtime detector. But there is already a static surface that should carry the pointer and does not — and fixing it needs no adopter report at all:

docs/INSTALL.md:203-208 is the "Extension points" table. Compare two rows:

line	row	points at downstream-capabilities.yaml?
206	"Add your own skills" → .agents/skills/custom-<name>/SKILL.md	no
208	"Connect an external knowledge base" → knowledge_sources: in .agentcortex/context/private/downstream-capabilities.yaml	yes

Row 206 tells an adopter where to put a custom skill and that it survives upgrades — but not that it stays inert with respect to auto-activation and pinning until it is declared. Row 208, the sibling seam in the same file, does exactly the right thing. This is a one-cell documentation asymmetry, not a missing feature.

Recommended split: ship the row-206 pointer as a standalone tiny-fix (1 file, doc-only, no engine change, no new always-on surface), and keep the runtime detector demand-gated. That discharges the discoverability half of this issue's title at zero cost and leaves only the "detect an adopter's populated .claude/skills/ at bootstrap" half genuinely waiting on demand.

4. Risk & Trade-offs

• Building the detector now would violate this repo's own evidence-before-adding rule — an always-on presence check on .claude/skills/, .cursor/rules/, etc. is a permanent per-bootstrap cost paid by every adopter to serve a report that has not arrived. The issue body already concedes this.
• Scope discipline. The proposal must stay advisory. It is not an ADR-007 non-goal (ADR-007:161-162 scopes out auto-discovery / auto-activation of undeclared skills, not a pointer) — but any implementation must never read, parse, execute, or activate a foreign skill. Reading a foreign skill's description to decide whether to mention it would cross straight into the rejected surface.
• Doc-fix risk is near zero. Row 206 is additive prose in a non-pinned section; rollback is a one-line revert. (One gotcha for whoever ships it: docs/INSTALL.md is pinned by tests/ci/test_deploy_tiering.py — substring assertions at :642, :749-752, and :1178-1183. Adding a table cell does not touch them, but re-run that module rather than assuming a doc edit is test-free.)

5. Estimated Scope

• Doc-only split (recommended now): 1 file — docs/INSTALL.md:206. Classification: tiny-fix.
• Full detector (still demand-gated): ~3-4 files — .agent/workflows/bootstrap.md (a new present-only advisory branch), .agent/config.yaml (an opt-out/threshold key), .agentcortex/bin/validate.sh and .ps1 (cross-platform parity is mandatory), plus INSTALL/guide text. Classification: feature.

6. Blocked By

Nothing technically blocks it — downstream-capabilities.yaml §skills (ADR-007) is already shipped and validate_downstream_capabilities.py already enforces the custom-* + on-match caps, so the detector would have a stable target today. The block is demand, not dependency.

Recommended disposition

Following the #291 precedent (and the #85 Cursor precedent it cites): close with a reopen trigger, moving the signal home to backlog row #101 — a standing open [Feature] issue with no adopter and no build intent reads as unfinished work when it is actually a parked hypothesis. Suggested reopen trigger, sharpened so it can discriminate:

An adopter reports that they deployed Agentic OS into a repo with pre-existing skills and either (a) did not discover downstream-capabilities.yaml §skills, supplying which surface they did read first (INSTALL, README, bootstrap output, or the agent itself), or (b) asks for bootstrap to point at it. Item (a)'s answer is the discriminator: if they read INSTALL, the doc fix in §3 discharges it and no detector is warranted.

Closing is left to the maintainer — this run is diagnosis only and does not close issues on its own.

[KbWen]

Doc split shipped — PR #436

Following the §3 recommendation in the triage analysis above (ship the discoverability half as a standalone tiny-fix, keep the runtime detector demand-gated), opened #436.

What changed: one cell — the "Add your own skills" row of the docs/INSTALL.md extension-points table. It now states that survival is not activation (an undeclared custom-* skill is never auto-recommended and cannot be pinned) and points at the skills: declaration in .agentcortex/context/private/downstream-capabilities.yaml, with the load_policy: on-match cap and the ADR-007 link — matching the shape its sibling knowledge_sources: row already had.

Re-verified before writing, not taken from the earlier comment:

• .agent/workflows/bootstrap.md:405 — undeclared custom-* id is still "unknown → ignore"; a declared one resolves.
• docs/adr/ADR-007-...:33-38 — "custom skills are second-class … cannot auto-activate".

Evidence: validate.sh → pass=99 warn=4 fail=0 skip=3, exit 0. tests/ci/test_deploy_tiering.py (which pins INSTALL.md substrings) → 38 passed, 1 skipped.

Still open after this merges: the runtime half — detecting a populated adopter skill directory (.claude/skills/, .cursor/rules/) at bootstrap and surfacing the pointer there. That stays parked behind the reopen trigger in the analysis above, since building an always-on presence check without an adopter report would violate evidence-before-adding. The PR uses Refs #292, not Closes, so this issue stays open on merge.