Skip to content

Support installing complete skill directories with arbitrary nested resources #21

Closed

Description

@ASI2030

Problem

SkillX can discover and publish nested SKILL.md files and now exposes references/ and scripts/ metadata, but the current consumer command does not install a skill directory. skillx use prints the stored SKILL.md content and optional reference/script metadata to stdout.

Production skills often require arbitrary nested resources beyond those two folders: modules/, assets/, browser adapters, configuration files, templates, tests, and package metadata. Registering such a skill succeeds at the metadata layer, but using it cannot reproduce the runnable source tree.

Public reproduction

Source skill:

https://github.com/ASI2030/Fact-Check-X/tree/main/skills/fact-check-x-complete

The skill has 94 files. Its entry point depends on nested modules and browser runtime assets. The current path:

npx skillx-sh use ASI2030/Fact-Check-X/fact-check-x-complete --raw --include-refs --include-scripts

can expose the instruction content plus reference/script metadata, but cannot deliver the required modules/ and other nested files. The command is therefore useful for discovery and inspection, but it is not a complete installation path for this class of skill.

This follows directly from the current implementation:

  • registration fetches the subfolder SKILL.md as the stored skill content;
  • resource enrichment only recognizes references/**/*.md and scripts/**;
  • skillx use renders content and metadata to stdout and does not write a directory tree.

Expected capability

  1. Publish an immutable source commit and a complete file manifest for the selected skill directory.
  2. Add a true install command that writes the complete tree while preserving relative paths and safe file modes.
  3. Support arbitrary nested resources, not only references/ and scripts/.
  4. Verify the installed file count and hashes against the manifest.
  5. Distinguish “view/use content” from “install runtime” in the CLI and marketplace UI.
  6. Reject path traversal, unsafe symlinks, oversized files, secrets, and unsupported executable modes during packaging/install.

A source-backed archive or commit-pinned Git tree would both work. Until a complete-tree install exists, multi-file skills should be labelled as discovery-only when their runtime cannot be reproduced.

Activity

  1. clark-cant commented on Sep 21, 2026

    @clark-cant

    Triage update — checked against main (d093fa6), and this is confirmed: SkillX can register a skill directory's metadata but cannot reproduce its source tree.

    Confirmed on main

    1. Registration stores only the subfolder SKILL.md. apps/web/app/lib/github/fetch-github-skill.ts → fetchSubfolderSkill() fetches exactly ${skillPath}/SKILL.md and derives the slug as owner + last path segment. Nothing else in the folder is fetched or stored.
    2. skillx use renders to stdout only. packages/cli/src/commands/use.ts → displaySkill() in use-display.ts prints the stored content plus, with --include-refs/--include-scripts, a references/scripts metadata block. --raw just wraps the same content in BEGIN/END markers. There is no writeFile/mkdir/createWriteStream anywhere under packages/cli/src, and the command set is config | find | publish | report | search | use — there is no install command.
    3. Resource enrichment is path-narrow. scripts/fetch-skill-refs-scripts.mjs (lines ~147-157) recognises only ${skillPath}/references/** ending in .md and non-.md files under ${skillPath}/scripts/**. Anything else — modules/, assets/, templates, browser adapters, package metadata — is never captured. That matches your Fact-Check-X case (94 files) exactly.

    So for multi-file skills the outcome is what your repro shows: discovery plus content/metadata inspection work, but --raw --include-refs --include-scripts cannot reproduce the runnable tree.

    Roadmap fit — this is Phase 2 + Phase 3, not a standalone patch

    The six expected-capability points map almost one-to-one onto the marketplace roadmap (#31):

    The identity problem this creates is the same invariant that the slug-collision issue (#25) runs into: a leaf-only slug plus a single stored SKILL.md cannot represent a directory. The clean path is to land this with Phase 2/3 rather than as an isolated fix.

    Recommendation: accept, needs design — do not implement standalone

    Keeping this open as the umbrella requirement for complete-directory install.

    Posted by the github-maintain skill at 2026-09-21T11:07:11Z

  2. mrgoonie commented on Sep 22, 2026

    @mrgoonie
    Contributor

    Ghi nhận từ lượt /ak-vibe --ship (issue #25 và #24)

    Comment này ghi rõ phần nào thuộc epic và phần nào không, để epic không bị hiểu là đã xong.

    Đã làm và đã merge (thuộc epic, là nền tảng identity): canonical skill identity (source_repo, source_path), slug suy ra từ identity, alias layer skill_aliases kèm migration 0010_sour_runaways.sql, seed pipeline dùng chung một luật với runtime, và CLI org/repo/skill giữ full path. Bằng chứng đầy đủ nằm ở comment của #25 và trong PR #43.

    Chưa làm trong lượt này — scope điều chỉnh, không phải đã implement: phần agent-native discovery và compatibility của epic. Các issue roadmap #31–#38 vẫn mở, và phase 1 (#33) chưa được triển khai trong lượt /ak-vibe --ship này vì mục tiêu của lượt chỉ gồm #25 và #24. Vì vậy epic vẫn nên ở trạng thái mở cho tới khi các phase đó hoàn thành.

    Phát hiện thêm nên đưa vào epic (chưa fix, ngoài scope lượt này): apps/web/app/routes/search.tsx chưa được đăng ký trong routes.ts (dead route, có từ trước); apps/web/app/routes/api.search.ts và search.tsx vẫn parse URL/JSON mà không có try/catch (có từ trước, linter flag).

  3. zuey-cloud-harness commented on Oct 11, 2026

    @zuey-cloud-harness
    Contributor

    This whole-directory install blocker is carried by immutable whole-tree registry #34 and targeted AgentKit publisher #54, then generic SkillX install/locked sync #35 and AgentKit consumer https://github.com/bestagentkits/agentkit/issues/2277. Preserve a 94-file nested resources regression fixture (modules/assets/references/scripts), complete file manifest and hashes, archive/path/symlink safety, and no code execution on skillx use. Until full-tree installation exists, skillx use should remain labelled as discovery/inspection. Cross-repo epic https://github.com/bestagentkits/agentkit/issues/2274.

  4. clark-cant commented on Nov 3, 2026

    @clark-cant

    Status re-verify at 2c1d2ba (2026-11-03) — the dependency chain this issue was waiting on has shipped

    Last touched 2026-10-11, when the recommendation was "land this with Phase 2/3 rather than as an isolated fix". Both of those are now closed (#34 2026-10-21, #35 2026-10-20), and the tree, manifest and installer work went in with them. Re-checked every acceptance point against main:

    Requirement Evidence on main
    Arbitrary nested resources packages/skill-tree/ — entry-collector.ts, tree.ts, path-rules.ts, tar and zip readers (tar-reader.ts, tar-sparse.ts, zip-reader.ts)
    Regression fixture apps/web/tests/fixtures/full-tree-94/modules/nested/a/b/c/deep-*.md — the 94-file nested tree requested here is in the repo, not planned
    Complete file manifest with hashes packages/contracts/src/release-manifest.ts plus fixtures/release-manifest-v2.json; receipts in packages/cli/src/lib/install/install-state.ts
    Archive/artifact delivery GET /api/v1/releases/:digest/artifact streams the uploaded tar same-origin from R2 (routes/api.v1.release-artifact.ts, releases/release-read.ts)
    Path/symlink/oversize safety install/safe-fs.ts (containedPath), skill-tree/src/path-rules.ts, collision.ts, tests in install/install-safety.test.ts and skill-tree/test/path-fuzz.test.ts
    Nothing deleted out from under the user install/tree-proof.ts — unprovenFiles/retireOld account for every entry and move unproven ones to a backup before the swap
    Install/update/sync with a lockfile install/planner.ts, install-engine.ts, journal-recovery.ts, lock-file.ts, sync-locked.ts, shipped in #168
    No code execution on skillx use commands/use-display.ts only prints content and links; execution is not on that path

    The one remaining gap is narrower than the issue title. A release-backed skill now installs its whole directory. A legacy seed listing still does not: discoveryOnlyNotice() in commands/use-display.ts:47 returns a DISCOVERY-ONLY banner whenever a listing carries references or scripts but has no published release — "the other files are not installed or pinned". So the residual work is publishing releases for the seed catalogue, not building a multi-file installer.

    Suggestion: close this as satisfied and track the residue elsewhere. The umbrella requirement (arbitrary nested resources installed as a directory, with manifest, hashes and safety) exists. If the legacy seed listings matter, a separate issue scoped to "backfill releases for seed listings" would keep this one from reading as unstarted when it is not.

    No branch or PR is in flight against #21; nothing here needs code from this issue.

    Generated by the github-maintain skill at 2026-11-03

  5. clark-cant commented on Nov 5, 2026

    @clark-cant

    Closing as satisfied at 2c1d2ba — the umbrella capability shipped; the residue belongs in its own issue

    Re-checked the acceptance points against the tree rather than against the landing PR descriptions, and nothing has moved since the last note here: git log c95ab77..2c1d2ba is #173 (docs) plus #174 (CLI visibility), neither of which touches an install path.

    Requirement Verified on main
    Immutable source + complete file manifest packages/contracts/src/release-manifest.ts and src/fixtures/release-manifest-v2.json (per-file path, sha256, size, mode)
    A real install that writes the tree packages/cli/src/lib/install/ — planner.ts, install-engine.ts, apply-transaction.ts, journal-recovery.ts
    Arbitrary nested resources packages/skill-tree/ — entry-collector.ts, tree.ts, path-rules.ts, tar-reader.ts, zip-reader.ts
    The 94-file regression fixture apps/web/tests/fixtures/full-tree-94/ — counted 94 files, including modules/, assets/, references/, scripts/
    Verify count and hashes install receipts in install/install-state.ts, plus install/fetch-verify.ts
    Distinguish use from install commands/use-display.ts keeps use read-only; the tree write lives in install / sync --locked
    Path traversal, symlinks, oversize, modes install/safe-fs.ts (containedPath), skill-tree/src/path-rules.ts, skill-tree/src/collision.ts, install/install-safety.test.ts, skill-tree/test/path-fuzz.test.ts; install/tree-proof.ts (unprovenFiles / retireOld) accounts for every entry before the swap
    No code execution on skillx use use-display.ts prints content and links only

    What is genuinely left is data, not code. A release-backed skill now installs its whole directory. A legacy seed listing that has references or scripts but no published release still prints the DISCOVERY-ONLY banner from discoveryOnlyNotice() (packages/cli/src/commands/use-display.ts:55). Closing that gap means publishing releases for the seed catalogue — a backfill task with no installer dependency, and a poor fit for this thread because it makes a shipped capability read as unstarted.

    Closing on that basis. A follow-up "backfill releases for seed listings" issue is the right home for the residue; reopen here if you would rather keep both in one place.

    Generated by the github-maintain skill at 2026-11-05

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions