Re-Specialize
Incrementally updates auto-generated content in CLAUDE.md and agent files
without touching user customizations. Uses protected zone markers to identify
what can be safely regenerated.
When to use
- When project dependencies have changed (new framework, updated versions)
- When architecture has evolved (new patterns, restructured folders)
- When agents need refreshed context about the project
- Periodically to keep CLAUDE.md in sync with the actual codebase
Process
Step 1 -- Read current state
Read CLAUDE.md and all agent files in .claude/agents/:
- Identify existing zone markers (
<!-- guild:auto-start:ID --> / <!-- guild:auto-end:ID -->)
- Note which zones exist and their current content
- Identify any user customizations outside of zones
Step 2 -- Explore the project
Same exploration as guild-specialize:
- Scan dependency files for current stack and versions
- Analyze project structure and architecture patterns
- Detect code conventions from linter/formatter configs
- Check environment variable examples
Step 3 -- Check zone markers
If CLAUDE.md has zone markers, proceed to regeneration.
If CLAUDE.md does NOT have zone markers (legacy project):
- Offer to inject markers around the auto-generated sections
- Show the user where markers would be placed
- Require explicit confirmation before modifying
- If user declines, abort gracefully
Step 4 -- Regenerate zone content
Invoke the Tech Lead agent using Task tool with model: "opus" (reasoning tier):
- Generate fresh content for each zone based on the project scan
- Compare new content with existing zone content
- Present a diff for each zone to the user
- Only replace zones where content has actually changed
Zones to regenerate:
| Zone ID |
Content |
structure |
Project folder structure with descriptions |
architecture |
Architecture patterns and design decisions |
conventions |
Code conventions from linter/formatter |
env-vars |
Environment variables from .env.example |
Step 5 -- Update agent context
Invoke the Tech Lead agent using Task tool with model: "sonnet" (execution tier):
- For each agent in
.claude/agents/*.md, update the agent-context zone
- If no
agent-context zone exists, append one at the bottom
- Preserve everything outside the zone (role definition, process, rules)
Step 6 -- Confirm changes
Present a summary:
Re-specialization complete for [project-name]
Zones updated:
- structure: [changed/unchanged]
- architecture: [changed/unchanged]
- conventions: [changed/unchanged]
- env-vars: [changed/unchanged]
Agents updated: [count] of [total]
Review the changes above. Confirm to commit.
Step 7 -- Commit
Commit all changes as an atomic commit:
git add CLAUDE.md .claude/agents/*.md
git commit -m "chore: re-specialize via guild-re-specialize"
Important Notes
- NEVER modify content outside of zone markers
- NEVER read real
.env files -- only .env.example
- If a zone's content hasn't changed, skip it (no-op)
- Present diffs before applying changes
- User confirmation is required before committing
1---2name: re-specialize3description: "Incremental re-specialization — re-scans the project and updates only auto-generated zones in CLAUDE.md and agents"4user-invocable: true5workflow:6 version: 17 steps:8 - id: read-current9 role: system10 intent: "Read current CLAUDE.md and agent files to identify existing zones."11 produces: [current-claude-md, current-agents]12 - id: explore-project13 role: system14 intent: "Scan project for current stack, dependencies, architecture, conventions."15 produces: [detected-stack, detected-architecture, detected-conventions]16 gate: true17 - id: check-zones18 role: system19 intent: "Check if CLAUDE.md has guild zone markers. If not, offer to inject them."20 requires: [current-claude-md]21 produces: [zone-status]22 gate: true23 - id: regenerate-zones24 role: tech-lead25 intent: "Generate new content for each auto zone based on fresh project scan. Present diff to user."26 requires: [current-claude-md, detected-stack, detected-architecture, detected-conventions, zone-status]27 produces: [updated-claude-md, zone-diffs]28 model-tier: reasoning29 - id: update-agents30 role: tech-lead31 intent: "Update agent-context zones in agent files with fresh project context."32 requires: [detected-stack, detected-architecture, detected-conventions]33 produces: [updated-agents]34 model-tier: execution35 - id: confirm36 role: system37 intent: "Present summary of changes and get user confirmation."38 requires: [zone-diffs, updated-agents]39 produces: [confirmation]40 gate: true41 - id: commit42 role: system43 intent: "Commit re-specialized files."44 requires: [updated-claude-md, updated-agents, confirmation]45 produces: [re-specialize-commit]46metadata:47 source: https://skillmd.com/skills/guild-agents/re-specialize48---4950# Re-Specialize5152Incrementally updates auto-generated content in CLAUDE.md and agent files53without touching user customizations. Uses protected zone markers to identify54what can be safely regenerated.5556## When to use5758- When project dependencies have changed (new framework, updated versions)59- When architecture has evolved (new patterns, restructured folders)60- When agents need refreshed context about the project61- Periodically to keep CLAUDE.md in sync with the actual codebase6263## Process6465### Step 1 -- Read current state6667Read CLAUDE.md and all agent files in `.claude/agents/`:6869- Identify existing zone markers (`<!-- guild:auto-start:ID -->` / `<!-- guild:auto-end:ID -->`)70- Note which zones exist and their current content71- Identify any user customizations outside of zones7273### Step 2 -- Explore the project7475Same exploration as guild-specialize:7677- Scan dependency files for current stack and versions78- Analyze project structure and architecture patterns79- Detect code conventions from linter/formatter configs80- Check environment variable examples8182### Step 3 -- Check zone markers8384If CLAUDE.md has zone markers, proceed to regeneration.8586If CLAUDE.md does NOT have zone markers (legacy project):8788- Offer to inject markers around the auto-generated sections89- Show the user where markers would be placed90- Require explicit confirmation before modifying91- If user declines, abort gracefully9293### Step 4 -- Regenerate zone content9495Invoke the Tech Lead agent using Task tool with `model: "opus"` (reasoning tier):9697- Generate fresh content for each zone based on the project scan98- Compare new content with existing zone content99- Present a diff for each zone to the user100- Only replace zones where content has actually changed101102Zones to regenerate:103104| Zone ID | Content |105|----------------|--------------------------------------------|106| `structure` | Project folder structure with descriptions |107| `architecture` | Architecture patterns and design decisions |108| `conventions` | Code conventions from linter/formatter |109| `env-vars` | Environment variables from .env.example |110111### Step 5 -- Update agent context112113Invoke the Tech Lead agent using Task tool with `model: "sonnet"` (execution tier):114115- For each agent in `.claude/agents/*.md`, update the `agent-context` zone116- If no `agent-context` zone exists, append one at the bottom117- Preserve everything outside the zone (role definition, process, rules)118119### Step 6 -- Confirm changes120121Present a summary:122123```text124Re-specialization complete for [project-name]125126Zones updated:127- structure: [changed/unchanged]128- architecture: [changed/unchanged]129- conventions: [changed/unchanged]130- env-vars: [changed/unchanged]131132Agents updated: [count] of [total]133134Review the changes above. Confirm to commit.135```136137### Step 7 -- Commit138139Commit all changes as an atomic commit:140141```bash142git add CLAUDE.md .claude/agents/*.md143git commit -m "chore: re-specialize via guild-re-specialize"144```145146## Important Notes147148- NEVER modify content outside of zone markers149- NEVER read real `.env` files -- only `.env.example`150- If a zone's content hasn't changed, skip it (no-op)151- Present diffs before applying changes152- User confirmation is required before committing