# molting

Adopt this skill: https://proskills.md/skills/other/mtdmo-molting-skill-molting

Page: https://proskills.md/skills/other/mtdmo-molting-skill-molting
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skill/molting/SKILL.md
size: 2547
upstream: https://github.com/mtdmo/molting/blob/main/skill/molting/SKILL.md

```text
---
name: molting
description: Perform the shell reset required when an agent's primary model, provider, or effective prompt language changes. Use when you need to refactor prompts, persona, tool rules, and workflow assumptions into a coherent canonical spec with traceability and evaluation. Also use for broader shell cleanup when the operating layer has become bloated or contradictory.
---

# Molting

Use this skill when the shell around an agent needs a disciplined rewrite, especially after a primary-model migration.

## Required Inputs

Gather the real operating materials before rewriting anything:

- system and developer prompts
- persona or soul files
- tool definitions and tool-use rules
- formatting and response-style rules
- examples that materially anchor behavior
- memory or workflow docs that change how the agent operates
- provider-specific patches or stale workarounds

If the shell is large or messy, read `references/molting-framework.md` first.

## Required Deliverables

A proper molt should produce:

- a current-shell interpretation
- a classification of rules into hard rules, soft rules, heuristics, and legacy clutter
- a rewritten canonical operating spec
- a traceability map
- a risk review
- an evaluation plan
- an adoption recommendation

## Workflow

1. Gather the current shell exactly as it exists.
2. Interpret what the agent is actually designed to do.
3. Classify instructions by importance.
4. Rewrite a cleaner canonical spec for the new primary model.
5. Map the rewrite back to the source.
6. Review molting risks.
7. Evaluate before adoption.

## Guardrails

- Do not treat molting as retraining.
- Do not use molting to hide broken tools or missing documentation.
- Do not casually mix shells from different primary models without traceability.
- Do not weaken hard rules just because the rewrite reads better.
- Do not translate the shell into a new prompt language without reviewing tool semantics, tone, and escalation behavior.
- Do not silently invent new capabilities.

## Output Standard

Prefer a reviewable artifact, not a freeform rewrite. The final output should make it easy to answer:

- what stayed
- what changed
- what was removed
- what still needs testing

If you need a human-readable structure, use `../../templates/molting-report-template.md`.

## Resources

- Read `references/molting-framework.md` for the full doctrine, workflow, and failure modes.
- Read `references/molting-prompts.md` for staged prompts that support interpret -> classify -> rewrite -> trace -> test.
```

## File: README.md
upstream: https://github.com/mtdmo/molting/blob/main/README.md

```text
<p align="center">
  <img src="assets/molting-logo.png" alt="Molting logo" width="320">
</p>

# Molting

Molting is the controlled rewrite of an agent shell after its primary model changes.

When the default LLM changes, the shell around it rarely transfers cleanly. Prompts, persona, tool habits, formatting rules, and provider-specific patches were tuned around the previous model. If you swap the brain and keep the shell untouched, regressions often show up as lower discipline, weaker tool use, flatter persona, or inconsistent response language.

This repo packages a practical way to handle that transition.

## What Molting Is

Molting is instruction-layer refactoring:

- reread the current operating materials
- separate hard rules from soft preferences and stale clutter
- rewrite a cleaner canonical spec for the new primary model
- preserve traceability and test the rewrite before adoption

## What Molting Is Not

- retraining or fine-tuning
- a substitute for fixing broken tools or missing documentation
- permission to mix shells from different primary models without review
- a reason to skip evaluation just because the rewrite sounds cleaner

## When To Use It

- the primary model or provider changed
- an established shell performs worse on a new model family
- response language, verbosity, or tool discipline drifted after migration
- the shell accumulated provider-specific patches, duplicated rules, or contradictions
- you want a portable, inspectable operating spec instead of patch-on-patch prompt edits

## What A Good Molt Produces

- a canonical operating spec for the new primary model
- a traceability map showing what was preserved, merged, clarified, inferred, or removed
- a risk review covering constraint erosion, persona drift, and tool confusion
- a focused evaluation plan before the rewrite is adopted

## Repository Contents

| Path | Purpose |
| --- | --- |
| [docs/framework.md](docs/framework.md) | Human-readable explanation of the molting framework and decision model. |
| [docs/checklist.md](docs/checklist.md) | Step-by-step checklist for running a disciplined molt. |
| [docs/discussion.md](docs/discussion.md) | Open questions and research directions for the framework. |
| [skill/molting/SKILL.md](skill/molting/SKILL.md) | Portable skill entrypoint for agent systems that support packaged skills. |
| [skill/molting/references/molting-framework.md](skill/molting/references/molting-framework.md) | Portable framework reference optimized for in-agent use. |
| [skill/molting/references/molting-prompts.md](skill/molting/references/molting-prompts.md) | Staged prompts for interpret -> classify -> rewrite -> trace -> test. |
| [templates/molting-report-template.md](templates/molting-report-template.md) | Report template for documenting a completed molt. |
| [examples/coding-agent-primary-model-transition.md](examples/coding-agent-primary-model-transition.md) | Worked example of a coding-agent shell migration. |

## Workflow

1. Inventory the current shell: prompts, persona files, tool policies, formatting rules, examples, and patches.
2. Interpret the shell before rewriting: mission, priorities, hard constraints, tone, tool semantics, and contradictions.
3. Classify material into hard rules, soft rules, heuristics, and legacy clutter.
4. Rewrite a cleaner canonical spec for the new primary model.
5. Trace the rewrite back to source material so nothing important is silently weakened.
6. Evaluate before adoption on the behaviors that actually matter.

## Common Use Cases

- moving a coding agent from one primary model family to another
- translating an existing shell into a new prompt language because the new model behaves better there
- cleaning up a long-lived agent whose prompts accreted through patches and emergency workarounds
- packaging an agent definition so it can survive future model or provider swaps with less drift

## Design Principles

- preserve hard constraints before polishing prose
- treat prompt language changes as shell changes, not cosmetic rewrites
- remove stale model-specific hacks instead of carrying them forward by default
- prefer explicit traceability over elegant but unverifiable simplification
- adopt a molt only after the new shell actually behaves better or more consistently

## Status

This repository is intentionally lightweight and doc-first. The framework is ready to use, the skill is portable, and the surrounding materials are meant to make the concept easy to inspect, apply, and extend in public.

If you want to contribute examples, evaluation rubrics, or sharper migration patterns, start with [CONTRIBUTING.md](CONTRIBUTING.md).

## License

This project is licensed under the [MIT License](LICENSE). Use it, modify it, remix it, and ship it.
```
