kkxjerry/skill-invocation-trace

Skill Invocation Trace

Overview

Make skill usage observable. Report only what is visible from the current task, loaded skill files, and actual actions taken.

Workflow

1. Identify the target skill or skills involved in the current task.
2. Read the relevant SKILL.md file paths before describing behavior.
3. If the user asks for more detail about limits or mechanics, read references/observable-surface.md.
4. If the user asks for richer documentation of files, references, or bundled resources, read references/resource-inventory.md.
5. Separate observed facts from inference.
6. Explain the execution plan in a compact, user-facing trace.
7. State limits explicitly when the user asks for hidden internal reasoning.

Trace Rules

• Name the skill that triggered or was requested.
• Cite the exact file path of each SKILL.md that was read.
• Mention concrete trigger evidence from the user request or session instructions.
• List only resources actually read or executed during the task.
• Distinguish:
  • Observed: directly seen in the prompt, files, commands, or tool results
  • Inferred: reasonable conclusion based on those observations
• Refuse to invent hidden chain-of-thought, hidden ranking scores, or undisclosed routing logic.
• If no skill actually triggered, say that plainly.
• Mention bundled resources explicitly:
  • SKILL.md: primary instructions
  • references/: documents loaded for clarification
  • scripts/: executable helpers used to generate or validate output
• If a helper script is useful for formatting, run scripts/render_trace.py instead of hand-writing long repetitive traces.

Output Format

Use this structure unless the user asks for a different format:

Skill invocation trace

Target skill
- <skill name or "none">

Why it triggered
- Observed: <user wording or session rule that matches the skill>
- Inferred: <optional short inference>

Files read
- <absolute path to SKILL.md>
- <absolute path to any references/scripts actually read>

Execution plan
- <step 1>
- <step 2>
- <step 3>

Limits
- <what is observable>
- <what is not observable>

Example

If the user says "show me how you are using skill-creator here", read that skill file and answer like this:

Skill invocation trace

Target skill
- skill-creator

Why it triggered
- Observed: the user asked to create a new skill
- Inferred: the request matches the skill-creator description

Files read
- /absolute/path/to/skill-creator/SKILL.md

Execution plan
- Read the skill instructions
- Initialize the new skill from the provided template
- Edit SKILL.md and validate the result

Limits
- Observable: the declared workflow, files read, commands run, and the final plan
- Not observable: hidden chain-of-thought or any undisclosed internal routing signal

Resources

references/

• Read references/observable-surface.md when the user wants a deeper explanation of what can and cannot be exposed about skill invocation.
• Read references/resource-inventory.md when the user wants the trace to enumerate instructions, references, scripts, assets, or other bundled resources in a structured way.

scripts/

• Use scripts/render_trace.py to generate a consistent Markdown trace from command-line arguments.
• Prefer the script when the trace has many files, resources, or execution steps and manual formatting would be error-prone.