Skills Lifecycle and Consolidation

Skills Lifecycle and Consolidation#

This document captures:

  1. What is already implemented for skills UX/runtime behavior.

  2. The proposed lifecycle model for updating and consolidating skills to avoid duplication.

  3. Tool exposure policy for the skills MCP wrapper.

Current Implementation (Shipped in This Branch)#

Global Skills Entry in TUI#

Skills management is available from a dedicated Skills button in the mode bar when skills are discoverable. The analysis-only “Manage Skills” button was removed from analysis settings.

Skills Modal Organization#

The modal now groups skills by source:

  • builtin (MassGen bundled skills)

  • project (.agent/skills in current project)

  • user (~/.agent/skills)

  • previous_session (evolving skills discovered from logs)

The modal includes:

  • Source/custom/evolving labeling for each skill.

  • Include evolving skills from previous sessions toggle.

  • Enable All, Disable All, and Enable Custom quick actions.

Runtime Behavior#

  • include_previous_session_skills is stored in TUI analysis state and forwarded at runtime.

  • Analysis mode now supports skill_lifecycle_mode with:

    • create_or_update (default): update best matching existing skill, otherwise create.

    • create_new: always create a new skill directory.

    • consolidate: apply update/create and then merge overlapping project skills.

  • Local skills setup now supports including previous-session evolving skills in merged local skills directories.

  • Skill scanning now returns richer metadata (for example: source_path, is_custom, is_evolving, origin) and deduplicates by skill name.

  • Analysis skill-creation instructions now explicitly request provenance metadata:

    • massgen_origin

    • evolving: true

  • Post-analysis harvesting now applies lifecycle-aware upsert logic (create/update/consolidate) rather than copy-only behavior.

Skills MCP Wrapper Tool#

A skills tool is available in the workspace tools server:

  • skills(action="list") returns grouped skill metadata.

  • skills(action="read", skill_name="...") reads a skill by:

    1. Trying openskills read first.

    2. Falling back to direct SKILL.md reads when needed.

This enables skill usage in local execution contexts where direct CLI invocation may not be reliable.

Remaining Gaps#

Without lifecycle controls, evolving skill creation can cause:

  • Duplicate domain skills (for example, multiple poem-writing variants).

  • Drift and fragmentation across similar skills.

  • Overly large, noisy “all skills” inventories.

Lifecycle Model (Implemented + Tuning)#

Default#

create_or_update is the default behavior in analysis mode.

Behavior:

  1. Discover existing skills first.

  2. Match the new candidate against existing skills using semantic similarity (name + description + content).

  3. If match confidence is high, update the existing skill instead of creating a new one.

  4. If confidence is low, create a new skill.

Other Modes#

  • create_new: Always create a new skill (explicit opt-in).

  • consolidate: Merge overlapping skills and keep canonical versions.

Consolidation Guardrails#

  • Keep canonical skill IDs/directories stable where possible.

  • Record provenance for merged skills (for example merged_from list).

  • Prefer staged writes + explicit approval over silent direct merges.

Analysis UX#

Analysis options now include a dedicated skill lifecycle selector in the popover:

  • Create or Update (recommended)

  • Create New Only

  • Consolidate Similar Skills

Tool Exposure Policy#

Requirement for the skills MCP wrapper tool:

  • Expose it only when CLI-native skill workflows are not active.

  • Do not expose it when backend type is codex.

  • Do not expose it when backend type is claude_code.

  • Treat this as a hard gating rule to avoid overlapping skill systems.

Rationale:

  • Those backends already have native skill patterns.

  • Avoid duplicated/conflicting skill invocation paths.

Implementation note:

  • Backend/tool gating is now enforced in two layers:

    • MCP config excludes skills and sets a disable env flag.

    • Workspace tools server honors the env flag and does not register skills at all.

Candidate Config Surface (Proposed)#

orchestrator:
  coordination:
    use_skills: true

    # Existing:
    load_previous_session_skills: false

    # Proposed:
    skill_lifecycle_mode: "create_or_update"   # create_new | create_or_update | consolidate
    enable_skill_consolidation_in_analysis: false
    skill_write_policy: "final_agent_staging"  # none | final_agent_staging | final_agent_direct
    max_previous_session_skills: 10
    previous_session_skill_sort: "recency"     # recency | relevance

Decision Checklist Before Implementation#

  1. Should create_or_update be the default globally, or only in analysis mode?

  2. Should consolidation ever run automatically, or always require explicit toggle?

  3. Should superseded skills be archived automatically or only suggested?

  4. Should canonical updates require approval in all modes, or only when multiple agents are writing?