| name | tech-reference-add |
| description | Capture project-specific, opinionated insights about a technology into skill reference files. Skills load these files at invocation time if they exist. Use when the user says "save this insight", "add this to the [tech] reference", "remember this [tech] pattern", "capture this convention", or "log this for [tech]". Do NOT use to generate generic best practices from public documentation.
|
| metadata | {"version":"3.0.0","triggers":["save this insight","add this to the [tech] reference","remember this [tech] pattern","capture this convention","log this for [tech]"]} |
Tech Reference Add
Append a project-specific insight about a technology into skill reference files. Skills scan for {tech}-{skill}.md files in their references/ directories at invocation time and load them if present — same file structure and naming convention as always. What changes is only the source of content: session observations, not generated best practices.
Guardrails
Scope
- Do NOT write outside
skills/ or extended/ directories.
- Do NOT include sensitive information — no credentials, tokens, keys, or connection strings. Use placeholder names only (e.g.
$API_KEY).
Public Knowledge Check
After extracting the insight, evaluate whether it's general public knowledge available in official documentation. If it is, do NOT reject — instead warn the user:
"This may already be covered by my training data without needing a reference file. Want to save it anyway?"
Wait for the answer. If yes, continue. If no, stop.
Before Writing
Show the formatted insight and target file list. Get explicit confirmation before writing.
On Duplication
Before appending, scan the target file for semantically equivalent rules. If found, show both and ask: replace / merge / keep both / skip.
Step 1: Extract the Insight
Parse from the user's message:
- Tech — e.g.
Django, Go. Ask if ambiguous.
- Insight — the rule, pattern, or convention. If too vague to write a precise rule, ask for clarification.
- Code snippet — if the insight references specific syntax and no example was provided, ask whether one would help. Omit if purely conceptual.
Ask clarifying questions before proceeding if any of the above is unclear.
Step 2: Public Knowledge Check
Evaluate whether the insight is general public knowledge. If yes:
"This may already be covered by my training data without needing a reference file. Want to save it anyway?"
If no, continue directly to Step 3.
Step 3: Discover Reference-Enabled Skills
Scan skills/ and extended/ for directories containing a references/ or reference/ folder. For each, read its SKILL.md description to understand the workflow it supports.
Step 4: Infer Relevant Skills
For each reference-enabled skill, reason semantically: "Does this insight affect the workflow this skill performs?"
Reasoning examples:
- Naming convention →
tlc-spec-driven (coding-principles style refs), code-review; performance-review not applicable
- Query optimization →
code-review (performance audit mode); likely tlc-spec-driven (coding-principles)
- Test fixture pattern →
tests, tests-code-review; not tlc-spec-driven
- Security input handling →
security-best-practices, code-review; not tests
Do not hardcode skill relationships — infer from each skill's SKILL.md description. When an insight is cross-cutting, include all skills where it would surface. If a skill's relevance is uncertain, include it in the proposal marked with (?) and let the user decide.
Step 5: Propose and Confirm
Present:
| Skill | Target File | Action | Rationale |
|---|
| code-review | skills/code-review/references/django-code-review.md | Append | Affects review correctness |
| tlc-spec-driven | extended/tlc-spec-driven/references/coding-guidelines/django-coding-guidelines.md | Create + append | Style convention |
| code-review | skills/code-review/references/django-performance-review.md | Append (?) | May surface during performance audit — confirm |
Ask: "Confirm saving to these files? Remove any you don't want or adjust the list."
Do not write until the user confirms.
Step 6: Write
For each confirmed target file:
If the file does not exist, create it with this header:
# {Tech} — {skill-name} insights
Project-specific patterns and conventions.
---
Append the insight as the next numbered item:
{N}. {Rule} — {brief why, if non-obvious}
If a code snippet applies, add it immediately after the rule line:
// Good
{minimal example — signature + key line(s) only}
// Bad
{minimal example — signature + problematic line(s) only}
Use // Good / // Bad markers only when contrast aids understanding. Omit the code block if the rule is purely conceptual.
Step 7: Report
## tech-reference-add: insight saved
Tech: {tech}
Insight: {rule}
Written to
- skills/code-review/references/django-code-review.md (appended, item 3)
- extended/tlc-spec-driven/references/coding-guidelines/django-coding-guidelines.md (created)
Skipped
- code-review (performance): removed by user
