tcl-whatis/tcl-nslist skills: directive-first triggers, lib: short invocations, pre-approved permissions
The skills existed but sessions never leaned on them - grep+read wins
the tool-selection contest when descriptions are phrased as information
needs ("use when you need to know how to call...") rather than task
triggers, and grep 'succeeds' without revealing which of the repo's
coexisting module copies is loaded. Changes to convert them from
available options into workflow steps:
- SKILL.md descriptions rewritten task-first ("Use BEFORE reviewing,
testing, editing..." / "Use BEFORE writing any new Tcl helper..."),
with run-it-first wording, the multiple-module-copies rationale, and
cost stated up front (one sub-1s side-effect-free invocation).
- Invocations shortened to lib: script-path form (verified working,
~0.45s each): punk91 src script lib:developer/whatis|nslist.
- New caveat in both: prefer the Bash tool over PowerShell (attached
console can flip colour/terminal detection in punkshell children).
- AGENTS.md Repo-wide Notes entry converted from reference note to
DIRECTIVE: whatis/nslist first, grep reserved for full-text searches.
- .claude/settings.json: allow entries for both scripts (Bash +
PowerShell, punk91/bin/punk91/./bin/punk91 prefixes) so first use is
prompt-free.
.claude/skills copies re-synced from canonical .agents/skills
(diff-verified byte-identical).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
description: Use when you need to discover what exists in a Tcl namespace or package in this repo - what commands/procs a namespace exposes, whether a helper already exists before writing one, or what an ensemble's implementation namespace contains. No specific command name needed (that's tcl-whatis). Runtime listing via punkshell using punk::ns::get_ns_dicts (the machinery behind the interactive n// browser): child namespaces with loadable-package markers, commands classified by kind (proc/alias/ensemble/native/oo/imported), which commands have punk::args docs, optional whole-namespace usage synopses. Auto-loads the package; sees runtime-generated commands grep cannot.
description: Use BEFORE writing any new Tcl helper and BEFORE starting work in a punk namespace/package in this repo - to discover what already exists: what commands/procs a namespace exposes, or what an ensemble's implementation namespace contains. Run it first; reserve grep for full-text source-pattern searches - this lists the live interpreter, so it sees runtime-generated commands, aliases and imports grep cannot. Cost: one sub-1s side-effect-free punkshell invocation. Via punk::ns::get_ns_dicts (the machinery behind the interactive n// browser): child namespaces with loadable-package markers, commands classified by kind (proc/alias/ensemble/native/oo/imported), which commands have punk::args docs, optional whole-namespace usage synopses; auto-loads the package. No specific command name needed - for a named command's definition site/interface use the tcl-whatis skill.
---
# tcl-nslist
@ -14,9 +14,13 @@ auto-loads the providing package when the namespace is not yet populated.
## Command
Run from the repo root (`punk91` lives in `bin/`; any punkshell kit works):
Run from the repo root (`punk91` lives in `bin/`, so `bin/punk91` from the
Bash tool; any punkshell kit works). Cost: sub-1s, no side effects.
description: Use when you need to know how to call a Tcl command in this repo (including ensemble subcommands like 'string is'), where a proc is defined (file and line number), which module version is actually loaded, or what a proc's runtime body is. Runtime introspection via punkshell - reports resolved name, kind (proc/alias/ensemble), providing package + version, origin file, def file:line, and punk::args synopsis. Cheaper and more accurate than grep+read for interface questions, and the only option for runtime-generated procs. For namespace/package-level discovery (listing what a namespace exposes, no command name needed) use the tcl-nslist skill.
description: Use BEFORE reviewing, testing, editing, porting or relocating any Tcl command in this repo, and for any question about a command's definition site, calling interface, loaded module version, or runtime body (including ensemble subcommands like 'string is'). Run it first; reserve grep for full-text source-pattern searches - this repo has several coexisting copies of many modules and grep cannot tell you which copy is actually loaded. Cost: one sub-1s side-effect-free punkshell invocation. Reports resolved name, kind (proc/alias/ensemble), providing package + loaded version, origin file, def file:line, and punk::args synopsis; the only option for runtime-generated procs. For namespace/package-level discovery (listing what a namespace exposes, no command name needed) use the tcl-nslist skill.
---
# tcl-whatis
@ -13,9 +13,13 @@ zipfs) is actually loaded.
## Command
Run from the repo root (`punk91` lives in `bin/`; any punkshell kit works):
Run from the repo root (`punk91` lives in `bin/`, so `bin/punk91` from the
Bash tool; any punkshell kit works). Cost: sub-1s, no side effects.
description: Use when you need to discover what exists in a Tcl namespace or package in this repo - what commands/procs a namespace exposes, whether a helper already exists before writing one, or what an ensemble's implementation namespace contains. No specific command name needed (that's tcl-whatis). Runtime listing via punkshell using punk::ns::get_ns_dicts (the machinery behind the interactive n// browser): child namespaces with loadable-package markers, commands classified by kind (proc/alias/ensemble/native/oo/imported), which commands have punk::args docs, optional whole-namespace usage synopses. Auto-loads the package; sees runtime-generated commands grep cannot.
description: Use BEFORE writing any new Tcl helper and BEFORE starting work in a punk namespace/package in this repo - to discover what already exists: what commands/procs a namespace exposes, or what an ensemble's implementation namespace contains. Run it first; reserve grep for full-text source-pattern searches - this lists the live interpreter, so it sees runtime-generated commands, aliases and imports grep cannot. Cost: one sub-1s side-effect-free punkshell invocation. Via punk::ns::get_ns_dicts (the machinery behind the interactive n// browser): child namespaces with loadable-package markers, commands classified by kind (proc/alias/ensemble/native/oo/imported), which commands have punk::args docs, optional whole-namespace usage synopses; auto-loads the package. No specific command name needed - for a named command's definition site/interface use the tcl-whatis skill.
---
# tcl-nslist
@ -14,9 +14,13 @@ auto-loads the providing package when the namespace is not yet populated.
## Command
Run from the repo root (`punk91` lives in `bin/`; any punkshell kit works):
Run from the repo root (`punk91` lives in `bin/`, so `bin/punk91` from the
Bash tool; any punkshell kit works). Cost: sub-1s, no side effects.
description: Use when you need to know how to call a Tcl command in this repo (including ensemble subcommands like 'string is'), where a proc is defined (file and line number), which module version is actually loaded, or what a proc's runtime body is. Runtime introspection via punkshell - reports resolved name, kind (proc/alias/ensemble), providing package + version, origin file, def file:line, and punk::args synopsis. Cheaper and more accurate than grep+read for interface questions, and the only option for runtime-generated procs. For namespace/package-level discovery (listing what a namespace exposes, no command name needed) use the tcl-nslist skill.
description: Use BEFORE reviewing, testing, editing, porting or relocating any Tcl command in this repo, and for any question about a command's definition site, calling interface, loaded module version, or runtime body (including ensemble subcommands like 'string is'). Run it first; reserve grep for full-text source-pattern searches - this repo has several coexisting copies of many modules and grep cannot tell you which copy is actually loaded. Cost: one sub-1s side-effect-free punkshell invocation. Reports resolved name, kind (proc/alias/ensemble), providing package + loaded version, origin file, def file:line, and punk::args synopsis; the only option for runtime-generated procs. For namespace/package-level discovery (listing what a namespace exposes, no command name needed) use the tcl-nslist skill.
---
# tcl-whatis
@ -13,9 +13,13 @@ zipfs) is actually loaded.
## Command
Run from the repo root (`punk91` lives in `bin/`; any punkshell kit works):
Run from the repo root (`punk91` lives in `bin/`, so `bin/punk91` from the
Bash tool; any punkshell kit works). Cost: sub-1s, no side effects.
@ -213,7 +213,7 @@ The project version is fully independent of module versions. A module bump (even
- The project extends Tcl with ANSI terminal capabilities, functional and pattern-matching language features, and a comprehensive module ecosystem.
- This root file is intentionally limited to DOX governance, global ownership boundaries, and the top-level Child DOX Index.
- Source-tree build, testing, linting, and file-resolution workflow lives in `src/AGENTS.md`.
- Runtime Tcl command introspection for agents (resolved name/kind, subcommand-chain resolution e.g `string is`, providing package + loaded version, origin file, def file:line, punk::args synopsis; `-doc` = full plain-text argdoc of all forms): `punk91 src script scriptlib/developer/whatis.tcl ?-body? ?-doc? <command> ?subcommand?...` - full usage and caveats in `.agents/skills/tcl-whatis/SKILL.md`. Its discovery counterpart for namespace/package contents (child namespaces with loadable-package markers, commands classified by kind, punk::args-documented commands, `-synopsis` whole-namespace usage lines - via `punk::ns::get_ns_dicts`, the `n//` machinery): `punk91 src script scriptlib/developer/nslist.tcl ?-synopsis? ?-pathcommands? <nsglob>...` - see`.agents/skills/tcl-nslist/SKILL.md`.
- Runtime Tcl introspection DIRECTIVE for agents: to locate or characterize a Tcl command (definition site, calling interface, loaded module version, runtime body - including subcommand-chain resolution e.g `string is`), run `punk91 src script lib:developer/whatis ?-body? ?-doc? <command> ?subcommand?...` FIRST; to discover what a namespace/package exposes (before writing a new helper, or when starting work in a namespace), run `punk91 src script lib:developer/nslist ?-synopsis? ?-pathcommands? <nsglob>...` FIRST. Reserve grep for full-text/source-pattern searches: this repo has several coexisting copies of many modules, and grep alone cannot tell you which copy is actually loaded. Both are single sub-1s side-effect-free invocations from the repo root (`punk91` lives in `bin/`; `lib:developer/<name>` = `scriptlib/developer/<name>.tcl`). Full usage and caveats: `.agents/skills/tcl-whatis/SKILL.md` and`.agents/skills/tcl-nslist/SKILL.md`.
- Tcl module authoring conventions live in `src/modules/AGENTS.md` and closer module child docs.
- If AGENTS.md conflicts with CLAUDE.md, AGENTS.md wins.
- Technical project goals live in root `GOALS.md` (summary index: ID, status, title, scope, detail pointer per goal) with the canonical Goal/Acceptance contract prose in `goals/G-<id>-<slug>.md` detail files - read the detail file of every goal whose scope intersects paths being edited. Goals are user-owned: agents add or edit goal contract elements (in either tier) only at the user's request, proposal-first (show the proposed wording, get explicit approval before writing - see the `GOALS.md` maintenance rules); never on their own initiative. Suggesting candidate goals when work surfaces something goal-worthy is welcome and encouraged - as a flagged proposal, not a file edit. Non-contract detail-file updates from user-directed work need only be reported in the completion summary. Agents auto-flip a goal to `achieved <date>` when its detail-file acceptance criterion is met as part of the DOX closeout pass - the flip includes archiving the entry to `GOALS-archive.md` and the detail file to `goals/archive/` - and must flag `proposed`→`active` transitions in their completion report for user confirmation. See `GOALS.md` for the full workflow, including how to author a new goal when asked.
