Define entry vs internal skills for lean agent context

[luongnv89]

Type

Feature (high confidence)

Description

Skill bundles often need one user-facing workflow while pulling in many supporting pieces (templates, reference docs, subagent prompts, or sibling skills). Today, every installed SKILL.md tends to appear in the agent's available-skills list (name + description), which grows context and routing noise even when only one skill should be explicitly invokable.

Concepts (names open for discussion):

• Entry / root / surface skill — meant to be invoked by the user (or chosen as the primary trigger for a workflow).
• Internal / dependency / hidden skills — should run only as part of an entry skill's process, not as standalone peers in the catalog.

Goal: Keep the LLM context lean by surfacing entry skills by default while still installing and loading internals on disk when the entry skill's instructions say to read them or spawn subagents.

Current ASM context:

• Bundles (data/bundles/*.json, asm bundle install) group installable skills but do not define which skill is the catalog entry.
• PRD §7.2 dependencies in SKILL.md is planned for install resolution, not visibility.
• Strong workflows already use a single SKILL.md plus references/ and templates/ (e.g. issue-creator) — that pattern avoids extra catalog entries without new metadata.

Design space (intentionally open — seeking opinions):

1. Authoring-only: One entry SKILL.md, everything else non-skill assets under the same folder.
2. expose / visibility frontmatter on separate skill packages; ASM omits expose: false from default agent-facing lists.
3. Bundle manifest roles (entry vs internal) deciding what gets surfaced after asm bundle install.
4. Two install roots (surface vs library) so agents that only scan one directory never see internals.

These can be combined. Related problems: skill similarity / wrong routing (#18), sandbox / subset activation (#92) — complementary but not a substitute for entry vs internal at bundle design time.

Open questions for discussion:

• Should "internal" skills be installable alone via asm install (escape hatch) or discouraged in UX?
• Who enforces visibility — ASM only, or each agent harness (Claude, Cursor, pi, …)?
• SKILL.md v2 dependencies vs separate bundle manifest vs both?
• How do shared internal skills work across multiple entry skills in different bundles?

Related issues:

• [FEATURE] Audit skill similarity to detect conflicting trigger descriptions #18 — Audit skill similarity (routing overlap)
• Add sandbox mode to selectively enable skills for agents #92 — Sandbox mode (session-level whitelist)
• Add intent-based smart skill search #103 — Intent-based search (discovery, not bundle structure)
• PRD §7.2 — Skill dependencies (install tree)

Reporter Context
feature request: a thought on how to design skill set (bundle).

Problem: sometimes we only need 1 entry skill, then that entry skill can call a whole bunch of different skills, then follow the chain down can have many different skills would be invoke.

So the skill to be directly invoke on the surface -> we can call them entry skill, or root, or the first skill, they are meant to be invoke explicitly by user (but also can be invoke by model).

Those skills down into the line after the first skill, they should not be invoke alone, and only should be invoke in the process of the first skill -> hidden skills / dependence skills, etc.

The idea is to keep the LLM context lean, we can just let the model know about the first skill, does not need to load the hidden skills.

what can be a good solution here?

Acceptance Criteria

• A short design doc or PRD section compares at least two approaches (e.g. in-repo assets only vs metadata + bundle roles) with tradeoffs for ASM and agent harnesses (medium confidence)
• Community can comment on naming (entry / internal vs alternatives) and enforcement layer (ASM vs per-agent) before implementation is locked (high confidence)
• If implemented: asm bundle install and/or skill metadata can express which skills are user-facing vs internal, with a documented default for existing bundles (medium confidence)
• If implemented: default skill discovery / list output excludes internal skills unless an explicit flag (e.g. --all / --include-internal) is used (medium confidence)
• Documentation explains when to use one entry skill + references/ vs multiple packaged skills with internal visibility (medium confidence)

Metadata

Priority: medium
Effort: L
Suggested model: GPT-5.5 Medium · Opus 4.8 Low (CursorBench 3.1, 2026-06-12 — advisory)
Labels: feature, enhancement, skill-discovery

[luongnv89]

My take: start with an authoring convention, then add explicit metadata for the cases that really need separate skill packages.

Default guidance should still be: one user-facing SKILL.md per workflow, with templates, references, subagent prompts, examples, etc. living under that skill folder. That solves most context-bloat cases today without new ASM behavior.

For cases where separate skill packages are useful, I would make visibility explicit instead of inferred:

---
name: issue-resolver
visibility: public # default
# dependencies still mean install resolution, not catalog exposure
dependencies:
  - issue-analysis
---

---
name: duplicate-detector
visibility: internal
---

The key distinction: dependencies should answer "what else must be installed?" while visibility answers "should this appear in the default user/agent-facing catalog?" A dependency is not always internal; some dependencies may also be valid standalone entry skills.

Bundle manifests can also add roles like entry / internal for better bundle UX, but I would not make bundle role the only source of truth because skills can be installed outside bundles. Skill-level metadata should travel with the skill.

Compatibility-wise, default should be visible/public so existing skills keep working. Internal skills should remain installable and inspectable, but be omitted from default surfaced lists/search unless the user asks for all/internal skills. ASM can enforce this in its own list/search/catalog/install behavior; downstream agent harnesses that blindly scan every SKILL.md may need a layout/filename convention or can only support it best-effort.

Preferred path:

1. Document the simple pattern first: entry SKILL.md + non-skill assets.
2. Add skill-level visibility metadata with default public.
3. Keep dependency resolution separate from visibility.
4. Optionally add bundle-level entry / internal roles as UX sugar.
5. Provide escape hatches like --all / --include-internal, plus warnings when an entry skill references a missing internal dependency.

[luongnv89]

Adding a mechanism angle to complement the visibility proposal above.

Worth noting we already have most of the enforcement substrate for "internal" skills — it's the library → activation mechanism (src/library.ts, src/config.ts).

• Library skills install to ~/.config/agent-skill-manager/library/skills — outside the agent-scanned ~/.claude/skills. So a library skill that is installed but not activated sits on disk (readable, spawnable as a subagent) yet never enters the agent's available-skills catalog.
• activateLibrarySkill symlinks it into ~/.claude/skills; deactivateLibrarySkill removes the symlink. That's precisely "loadable on disk, absent from the catalog" — the exact property this issue wants for internals.

So the two layers fit together cleanly:

• visibility: internal (proposed metadata) = the declaration — travels with the skill, source of truth, works outside bundles.
• library + activation (exists today) = the mechanism — internals stay in the library unactivated; entry skills get activated into the catalog. An entry skill's instructions can still read/subagent-spawn an unactivated internal by absolute path.

Concretely, visibility: internal could just mean "install to library, do not auto-activate," and --include-internal / --all would activate them. No new isolation primitive needed — we'd be wiring the proposed metadata to a mechanism that already ships.

To keep the distinctions clean (re: the open questions):

• dependencies (PRD §7.2) and visibility are shipped vs proposed — dependencies answers "install what?", visibility answers "surface what?". A dependency can still be a valid standalone entry skill.
• Shared internals across bundles work naturally here: one library copy, activated by whichever entry skill's flow needs it, with no duplicate catalog entries.

Open question this raises: should activation be per-session (entry skill activates its internals on invocation, deactivates after) rather than install-time? That would keep the catalog leanest but couples activation to runtime — overlaps with the sandbox idea in #92.

---

Update — the "must work on every harness" requirement actually settles which mechanism is load-bearing.

The constraint "no harness (Claude, Cursor, codex, pi, …) surfaces hidden skills; only entry skills are indexed at session start" is decisive because foreign harnesses don't read ASM's metadata — at session start each one just globs its own skills dir (~/.claude/skills, ~/.codex/skills, ~/.pi/skills, …) for SKILL.md. ASM has no runtime hook in that scan. So visibility:/bundle roles can be the declaration, but they can never be the enforcement — a foreign harness will never honor a flag it doesn't parse.

That means hiding has to be physical: an internal skill must simply not be present as a SKILL.md under the scanned dir at session start. Two portable ways to achieve that:

1. Authoring convention — one entry SKILL.md + everything else as non-SKILL.md assets (references/, templates/, subagent prompts) in the same folder. Universal, ships today, zero metadata. Limit: internals aren't separately-packaged skills.
2. Library + non-activation — internals live in ~/.config/agent-skill-manager/library/skills, outside every harness's scanned dir, and are never activated. Universal regardless of how a given harness scans (recursive or not, keyed on SKILL.md or not) because the file just isn't in the tree it walks. Still readable / subagent-spawnable by absolute path. This is the only route that satisfies both "separately-packaged internals" and "works on all harnesses."

What this rules out as a standalone solution: a frontmatter flag alone (foreign harnesses ignore it), and "nest a real SKILL.md deeper to dodge indexing" (harness-dependent and fragile — depends on each scanner's depth behavior; matches the "best-effort layout/filename convention" caveat raised above).

So the clean partition is: visibility/bundle role = install-time declaration that decides placement; library non-activation = the physical, harness-agnostic enforcement. visibility: internal ⇒ "place in library, don't activate"; --include-internal / per-session activation is the escape hatch.

[Keesan12]

The entry-vs-internal skill split is a really important design line. As these systems grow, the user shouldn't have to understand the whole machinery — but the run still needs structure, boundaries, and proof.

MartinLoop is my attempt at that outer layer. Not another skill manager or agent, but the management system around agents: give the work a budget, define done, verify the result, and leave a receipt.

Would love your take: https://github.com/Keesan12/martin-loop