Feat user skills

[simongdavies]

This pull request implements the user-generated skills feature in HyperAgent, allowing users to persist learnings from a session as reusable skills (SKILL.md files) that override system skills and survive upgrades. The changes introduce new commands, update documentation, and add core logic for saving, loading, and managing user skills. It also includes comprehensive testing instructions and validation for edge cases.

Key changes:

User Skills Feature Implementation

• Added support for user-generated skills: users can save session learnings as skills via the /save-skill command, which persists a structured SKILL.md under ~/.hyperagent/skills/<name>/ and optionally a companion module. User skills override system skills with the same name and are loaded automatically on startup.

• Introduced the generate_skill tool, which handles validation, user approval, and writing of user skills and companion modules. It ensures no silent overwrites and provides detailed feedback to the user.

• Updated the session configuration to include both system and user skill directories, enabling user skills to be loaded and override system skills on name collision.

Command and REPL Enhancements

• Extended the /skills command set with subcommands for listing, showing, editing, and deleting user skills. Added the /save-skill command for persisting new skills. User skills are marked with a 👤 badge and overrides are flagged in the UI.

• Updated the command help text and documentation to reflect the new user skills functionality and management commands.

Documentation and Testing

• Added a comprehensive TESTING-USER-SKILLS.md guide detailing end-to-end testing, boundary cases, override behavior, and troubleshooting for the user skills feature.

• Updated SKILLS.md with a new section explaining user skills, how to save them, when to use them, and management commands.

Core and Utility Logic

• Refactored skill loading logic to support loading from multiple directories (system and user), and updated the approach resolver to handle the new skill directory structure.

• Added tracking for modules registered during a session, so they can be suggested as companion modules when saving a skill.

• Introduced a cap on tool-call history to limit memory usage and ensure only recent session activity is summarized for skill generation.

These changes collectively enable users to capture, reuse, and manage domain-specific expertise directly within HyperAgent, making workflows more efficient and persistent across sessions.

[Copilot]

Pull request overview

This PR adds user-generated skills to Hyperagent so session learnings can be saved as reusable SKILL.md files under the user library and loaded alongside bundled skills.

Changes:

• Adds user skill persistence, multi-directory skill loading, and /save-skill generation flow.
• Extends slash commands and agent state to track session context for skill authoring.
• Adds documentation and tests for skill loading/writing, session summaries, and markdown rendering.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 18 comments.

Show a summary per file

File	Description
src/agent/index.ts	Wires user skills into session config, adds generate_skill, and tracks tool/session context.
src/agent/skill-writer.ts	Adds validation, rendering, CRUD, and persistence for user skills.
src/agent/skill-loader.ts	Adds source/file metadata and multi-directory loading with override precedence.
src/agent/session-context.ts	Adds session activity summarization for /save-skill.
src/agent/slash-commands.ts	Adds /save-skill and user-skill management subcommands.
src/agent/state.ts	Adds session-learning state fields.
src/agent/commands.ts	Updates help text for skills and save-skill commands.
src/agent/approach-resolver.ts	Allows approach resolution from multiple skill directories.
src/agent/tool-gating.ts	Allows the new generate_skill tool.
src/agent/system-message.ts	Instructs the LLM when to save learned skills.
src/agent/markdown-renderer.ts	Switches to markedTerminal() extension setup.
tests/skill-writer.test.ts	Adds coverage for user skill validation and CRUD.
tests/skill-loader.test.ts	Adds coverage for source metadata and user override loading.
tests/session-context.test.ts	Adds coverage for session context extraction/rendering.
tests/markdown-renderer.test.ts	Adds markdown renderer smoke/regression tests.
tests/intent-matcher.test.ts	Updates skill fixtures for new fields.
tests/approach-resolver.test.ts	Updates skill fixtures for new fields.
docs/TESTING-USER-SKILLS.md	Adds manual testing guide for user skills.
docs/SKILLS.md	Documents saving and managing user skills.

Comments suppressed due to low confidence (2)

src/agent/index.ts:5618

• Saving the skill before validating/registering the companion module can leave a persisted skill that references a module that was denied or failed validation. That partial state makes the new skill broken for future sessions; either register the module first or roll back/update the skill when the companion module step fails.

      if (params.companionModule) {
        const m = params.companionModule;
        const moduleSaveResult = (await registerModuleImpl({
          name: m.name,

docs/TESTING-USER-SKILLS.md:104

• This override test does not actually shadow a bundled skill because code-review is not present in the repository's skills/ directory. Use an existing system skill name (for example one listed in skills/CLAUDE.md) so the test verifies override behavior.

User skills must override system skills with the same name. Drop a user
skill that shadows an existing system one:

```bash
mkdir -p "$HYPERAGENT_USER_SKILLS_DIR/code-review"