NodeSpace skill instructions don't establish it as the source of truth for docs/specs — only teaches how to call functions #2272

Activity

1. mstomar125

   added

   enhancementNew feature or requestNew feature or request

   on Aug 24, 2026
2. mstomar125

   self-assigned this

   on Aug 24, 2026
3. malibio commented on Aug 24, 2026

   

   malibio

   on Aug 24, 2026

   Collaborator

   More actions

   Investigation: the fix needs to happen in the frontmatter description, not (only) the body

   Working through this alongside #1958 surfaced a mechanism issue that changes what "add explicit instructions to the skill" has to mean in practice.

   The body is not the discovery surface

   Under the Agent Skills standard (agentskills.io), skills load by progressive disclosure:

   1. Discovery — agents load only name + description at startup (~100 tokens)
   2. Activation — the full SKILL.md body is read into context when a task matches the description
   3. Execution — scripts/ / references/ load on demand

   So instructions added to the body change what an agent understands after it has already decided to load the skill. They have no effect on whether it loads. An agent about to write a spec never reaches them.

   This matters because on the user-launched path (the user starts Claude Code/Codex themselves; see #1958 for scope) the skill is the only channel — there is no per-session context assembly to compensate. If the description doesn't match, NodeSpace never enters the session at all.

   The current description has no docs/specs vocabulary

   The installed description is generated at packages/skill/src/agents.ts:16-27. Its trigger vocabulary is entirely personal-memory framing:

   "remember something for later", "recall what was decided or discovered earlier", "save notes/tasks/findings/decisions", "search prior context at the start of a task", "check nodespace", "what did we save"

   There is no spec, ADR, architecture, design, requirements, or planning vocabulary anywhere in it. An agent about to write an ADR has nothing to match against — which is precisely the gap this issue describes, sitting one layer below where the issue proposes to fix it.

   Two further problems in the same place

   1. The description is Claude-Code-only. agents.ts:31-54 prepends CLAUDE_CODE_SKILL_FRONTMATTER for Claude Code alone; the Codex, Gemini, and OpenCode entries carry no skillFrontmatter. Under the standard, name and description are required — a skill folder without them is malformed. Since all four of these harnesses now read the Agent Skills format natively, NodeSpace currently ships a spec-invalid skill to three of its four targets, where it may not be discoverable at all.

   2. The definition itself under-sells the product, not just the "when". SKILL.md's opening line — the first thing any agent reads on activation — is:

   "NodeSpace is a local-first knowledge graph that stores notes, tasks, and structured data on your machine. It persists across sessions."

   Accurate, but it positions NodeSpace as a notes app with an API; the same sentence would fit Obsidian. Compare strategy/vision.md ("What NodeSpace Is") in nodespace-docs:

   "NodeSpace is context infrastructure for AI-native development... Repositories contain what was built. NodeSpace contains why it was built, how it should be built, and what agents need to know to build it correctly."

   And Principle 1 (strategy/principles.md): "Code is artifact. Context is infrastructure."

   Nothing in the shipped skill carries that framing. An agent reading the current opening has no reason to think specs, ADRs, or architecture decisions belong in NodeSpace rather than a README. So this issue's scope should widen slightly: the definition needs fixing too, not only the "when to use it" guidance. They're the same fix — an agent told NodeSpace holds "why it was built" needs much less separate instruction to check it before writing a spec.

   Proposed description

   Spec constraints: description max 1024 chars; the spec's own guidance is that it "should describe both what the skill does and when to use it" and "should include specific keywords that help agents identify relevant tasks."

   ---
   name: nodespace
   description: >
     Context infrastructure for AI-native development. Read and write the
     NodeSpace knowledge graph — the durable record of why a system was built
     and how it should be built: specs, architecture decisions, ADRs, designs,
     plans, standards, tasks, and findings. Use before writing or changing a
     spec, ADR, design doc, or plan; when you need the reasoning or constraints
     behind existing code; when recording a decision or discovery that should
     outlive this session; or when asked to "check nodespace".
   allowed-tools: Bash(nodespace:*)
   ---

   Treat this as a starting point, not a final answer — description wording is a tuned, measured artifact (see #1958, "Settled" item 2: descriptions are hand-tuned and explicitly excluded from generation). It should be iterated against real activation behavior, not merged on aesthetics.

   Portability constraint on frontmatter

   The spec allows exactly six fields: name, description, license, compatibility, metadata, allowed-tools. Claude Code accepts additional ones (argument-hint, disable-model-invocation, user-invocable, disallowed-tools), but non-Claude-Code distribution paths hard-error on unknown keys rather than ignoring them:

   Unexpected key(s) in SKILL.md frontmatter: argument-hint.
   Allowed properties are: allowed-tools, compatibility, description, license, metadata, name
   

   The current frontmatter already stays within the six. Worth preserving deliberately, since the skill is intended for a public import repo consumed across many harnesses.

   Also note name must match the parent directory name. Install dirs are skills/nodespace/, so name: nodespace is correct — keep them in sync.

   Suggested scope for this issue

   • Rewrite the frontmatter description to carry docs/specs/architecture/planning vocabulary (this is the actual trigger; the body change alone cannot fix the reported problem)
   • Ship spec-compliant frontmatter for all four harnesses, not Claude Code only
   • Update SKILL.md's opening definition to the vision framing (repo holds what; NodeSpace holds why and how)
   • Add the "when to reach for it" guidance this issue originally asked for, in a section protected from regeneration (Make the graph the source of truth for the NodeSpace skill, and decide how guidance reaches external agents #1958)
   • Verify the new description actually changes activation behavior by hand, per Make the graph the source of truth for the NodeSpace skill, and decide how guidance reaches external agents #1958's manual harness test — do not assume it works because it reads well

   Note on evidence

   Do not justify description wording by citing NodeSpace's internal agent retrieval measurements. Those were produced by NodeSpace's own in-process agent loop and say nothing about how Claude Code or Codex match a skill description. #1958 carries the same warning and a manual test plan; this issue's description change should be validated the same way.

   Dependency

   This is currently untestable end-to-end: @nodespaceai/skill 404s on npm (#2271 — #1184 was closed as completed without the package ever being published), so a user cannot install the skill at all today. Fixing distribution is a prerequisite for verifying any of the above in a real harness.
4. malibio commented on Aug 24, 2026

   

   malibio

   on Aug 24, 2026

   Collaborator

   More actions

   Folding this into #1958 and closing as superseded — not because the ask is wrong, but because the fix and #1958's design are the same artifact.

   The investigation above showed the change has to land in the frontmatter description (the discovery surface), alongside a definition rewrite in the body, alongside the decision about where guidance lives at all. Splitting those across two issues invites implementing a description against assumptions #1958 later overturns.

   #1958 now carries all of it verbatim: the description/body distinction, the current description's missing docs/specs vocabulary, the vision-framing definition rewrite, the proposed starting-point description, the six-field portability constraint, the all-four-harness frontmatter gap, and the CLAUDE.md follow-on dependency. Acceptance criteria were added for each.

   @mstomar125 — reassigning the work rather than dropping it; the substance is intact in #1958.

   Note also that none of this is verifiable end-to-end until #2283 lands (@nodespaceai/skill 404s, so the skill cannot currently be installed in a real harness).
5. malibio

   closed this as not plannedon Aug 24, 2026