Skill/plugin improvements

[mindsocket]

Logged from a session using the skill. Quoted sections are LLM input.

• Skill uses bunx structured-context instead of sctx commands. Change to using sctx throughout, and add instruction to check installed version. A match on plugin minor version and package minor version (eg 0.9.*) indicates compatibility. We'll need to work out if skills know what version they are from the plugin or bake that in (ideally without hardcoding version) - the point below suggests some awareness from "skill's system-reminder header".
• Skill tries to search for config or schemas (?) in the package instead of using cli. Search(pattern: "**/*.json", path: "~/.claude/plugins/cache/structured-context/structured-context/0.8.3")
• Skill appears to reference old version 0.8.3 ?

  Why I ran that search: I was looking for bundled partial schema files (like _sctx_base.json,
  _wardley_mapping.json) which the skill docs mention can be inspected with bunx structured-context
  schemas show <filename>. I assumed they'd be on the filesystem somewhere accessible. That was
  unnecessary — the right approach is to use the CLI itself (bunx structured-context schemas show
  <filename>) which knows where its own bundled assets live.

  Why 0.8.3: I blindly used the path from the skill's system-reminder header (Base directory for this
   skill: .../0.8.3/...). That's fragile — the version is baked into the cache path and will go stale
   when the plugin updates. I should have either used a glob to find the actual installed path, or
  more importantly, just not searched the plugin cache directory at all and relied on the CLI.

  The underlying mistake: I was trying to do filesystem discovery of internal plugin structure when
  the tool already provides the right interface (schemas show, docs, etc.). Using the CLI as intended
   would have been both more reliable and version-agnostic.

  For your improvements log: this suggests the skill prompt could more explicitly steer agents away
  from filesystem exploration of the plugin directory and toward the CLI interface for schema
  discovery.

• sandbox issue -> audit for temp usage and consider alternative approach or permissions that would alleviate:

⏺ Bash(bunx structured-context schemas show --space auspol 2>&1)
  ⎿  Error: Exit code 1
     error: bun is unable to write files to tempdir: PermissionDenied
     [rerun: b3]

• skill needs to know about schemas list command instead of reaching straight for show subcommand:

⏺ Bash(bunx structured-context schemas show _wardley_mapping.json 2>&1 && echo "===" && bunx
      structured-context schemas show _wardley_doctrine.json 2>&1)
  ⎿  Error: Exit code 1
     Schema not found: .../_wardley_mapping.json

     Hint: Use ./ or / prefix for local paths (e.g. ./schemas/my_schema.json),
           or use --space to show a space's configured schema.
     [rerun: b5]

The Orientation section lists schemas show --space and schemas show <filename> as the two schema
  discovery tools, but never mentions schemas list. It should appear there — right before schemas
  show <filename> — since the natural workflow is:

  1. schemas list → discover what bundled partials exist
  2. schemas show <filename> → inspect a specific one

  Without schemas list, I had to guess filenames (e.g. _wardley_mapping.json), which predictably
  failed. The command fills an obvious gap in the orientation flow.

• ensure that schema authoring guide includes schemas show --raw option for getting at original schema content

I don't — I assumed schemas show only output formatted text. --raw presumably gives the actual JSON
   schema file, which would be much more useful for understanding how to compose a new schema from
  existing partials. Let me use it.

• add Bash(sctx *) permissions to the plugin config, but only for non-destructive commands (yes: docs, schemas, validate; no: template-sync; tbd: render)

• add a way to check if a schema is valid. That might work already with schemas show ..., if so we could just document that. Introducing a schemas validate ... would be more explicitly helpful.

• ensure that including an entire node type using ref and schema ids is documented as supported (both in core package docs and skill docs for schema authoring) - eg oneOf: [ { "$ref": "local://myschema/_mypartial#/$defs/mytype"}, ...] works in the list of node definitions.

Two things would have told me directly:

  1. In the schemas show output explanation — the skill
  describes schemas show --space as showing "the loaded
  schema registry" but doesn't explain what [local]
  entries mean or how they get there. A single line like:
   "Local partials co-located with the schema file are
  auto-discovered and registered by their $id — reference
   them in $ref using that ID" would have made the
  mechanism obvious from the registry output alone.
  2. In the schema authoring reference (docs schema or
  references/schema-authoring.md) — there's no example of
   a local $ref using a local:// ID. The only $ref
  examples shown are sctx:// bundled partials. An example
   pairing a partial definition with its usage in a
  consuming schema's oneOf would have made the pattern
  clear without needing to guess or test.

  The first is the higher-value fix — the registry
  section is visible output that an agent will always see
   after running schemas show, so annotating what [local]
   means there is a natural discovery path. The second is
   useful but secondary since schema authoring docs are
  only consulted when building schemas.

• consider whether schemas show needs to show either or both unresolved and resolved (before and after partials applied), what is a sane default, what cli options make sense, and what hints to give in output (never in --raw or --json output though, for hopefully obvious reasons)

• encourage the use of partials for schema development if there's any prospect (and usually there is) of reuse or alternative compositions of fields, nodes etc to make a full schema that's different, or to make schemas that combine from multiple areas (eg strategy + knowledge). This was also noted in a new comment on Add adjacent models? #7 .

  • for this, relationships should be encouraged to be "pushed" down to the common denominator. eg if a partial defines 2 entities and they're definitely always going to be related a certain way, then include the relationship in the partial too. Hierarchies don't currently support this as they can't be merged like relationships can so need to be assembled at the top level. Indeed there's an unresolved problem noted elsewhere that only one schema involved in a full schema can define a hierarchy.
  • Also the docs/skill resources need to explicitly call out that metadata, subject to certain hierarchy limitations, can and should be added to partials (eg relationships, aliases)

On the skill gap: The skill's "Embedded nodes and Relationships" section only frames relationships through the
  lens of embedded parsing (heading matchers, tables, fieldOn direction for embedding). It doesn't mention that:

  1. Partials can carry $metadata (including relationships), not just $defs — making them genuinely self-contained
   units
  2. Relationships can be declared for frontmatter wikilink array properties (non-embedded), and this causes them
  to appear in schemas show output and enables link validation

  Both are worth adding to the skill — #1 especially, since it changes the mental model of what a partial is
  (closer to a full mixin than just a type library).

[mindsocket]

Fixed in 841a27d: skill updated to use sctx throughout, version compatibility check added, schemas list added to orientation, and a warning against filesystem exploration of the plugin cache directory.