Skip to content

Agent skills: emphasize generalization and self-containment in lessons and skill updates#1810

Merged
nathanjmcdougall merged 2 commits into
mainfrom
copilot/generalize-lessons-emphasis
Apr 4, 2026
Merged

Agent skills: emphasize generalization and self-containment in lessons and skill updates#1810
nathanjmcdougall merged 2 commits into
mainfrom
copilot/generalize-lessons-emphasis

Conversation

Copilot AI commented Apr 4, 2026

Copy link
Copy Markdown
Contributor

Lessons and skill updates were being written with stiff, highly-specific content (exact function names, file paths, memory references) that narrows applicability and breaks self-containment. This tightens both skills to enforce abstraction.

usethis-lesson-create (v1.0 → v1.1)

  • New "Self-containment and abstraction" section with three rules: never reference memories, never name specific code objects unless they are the subject, and state principles at the right abstraction level

  • Comparison table showing "too specific" vs generalised rewrites:

    Too specific Better
    Always call clear_functools_caches() after @functools.cache Whenever a caching decorator is added, ensure the cache is cleared in tests
    validate_or_raise accepts err=, not error_cls Validation helpers have specific argument conventions — check the signature before use
  • Updated lesson template placeholder for "Generalised principle" to explicitly prohibit specific names and memory references

  • Strengthened procedure step 3 with the same guidance

usethis-skills-modify (v1.5 → v1.6)

  • New step 2 in the procedure: "Generalise the instruction" before writing skill content — if the incoming instruction names a specific function/file/class, lift it to a transferable principle first
  • New "Generalising incoming instructions" section with a comparison table and the key test: "would this guidance still be relevant if the named entity were refactored away?"
  • New "Never reference memories" content quality guideline — skill content must be fully self-contained

- usethis-lesson-create v1.0 → v1.1: add "Self-containment and
  abstraction" section; strengthen "Generalise the principle" step;
  update lesson template; add abstraction examples table
- usethis-skills-modify v1.5 → v1.6: add "Generalise the instruction"
  procedure step; add "Generalising incoming instructions" section with
  examples table; add "Never reference memories" content guideline

Resolves #1820

Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/a66b4b24-94c2-491f-ac7c-dd02c6b3ca53

Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
Copilot AI changed the title [WIP] Update agent skills to emphasize generalization of lessons Agent skills: emphasize generalization and self-containment in lessons and skill updates Apr 4, 2026
Copilot AI requested a review from nathanjmcdougall April 4, 2026 05:27
@nathanjmcdougall nathanjmcdougall marked this pull request as ready for review April 4, 2026 06:04
@nathanjmcdougall nathanjmcdougall merged commit 476bfd1 into main Apr 4, 2026
1 check passed
@nathanjmcdougall nathanjmcdougall deleted the copilot/generalize-lessons-emphasis branch April 4, 2026 06:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Agent: put more emphasis on the need to generalize lessons

2 participants