skill-contract-generator

name	skill-contract-generator
description	Generates evolution contracts for skills, defining what can be updated, what must remain stable, and how to extract knowledge. Use when creating new skills or formalizing update rules for existing skills. Adds a "Skill Contract" section to SKILL.md that guides skill-updater during project work.

Skill Contract Generator

Overview

This skill adds a structured "Skill Contract" section to any skill's SKILL.md file. The contract declares what parts of the skill are stable (general knowledge) versus mutable (can evolve during projects), and defines rules for updates and knowledge extraction.

When to Use This Skill

Use this skill when:

• Creating a new skill and want to define its evolution rules
• Formalizing update boundaries for an existing skill
• Preparing a skill to be used with skill-updater
• Clarifying what knowledge should be extracted after projects

Workflow

Step 1: Select Target Skill

Identify which skill needs a contract:

• For new skills: Use immediately after creating with skill-creator
• For existing skills: Add contracts retroactively

Ask the user:

• "Which skill do you want to create a contract for?"
• "Where is the skill's SKILL.md file?"

Default assumption: .claude/skills/<skill-name>/SKILL.md

Step 2: Analyze Skill Structure

Read the skill's SKILL.md to understand:

• Skill type: Meta-skill vs. general skill
• Content structure: What sections exist
• Resources: scripts/, references/, assets/ directories
• Complexity: Simple reference vs. complex workflow

This analysis informs contract generation.

Step 3: Define Stable Elements

Identify what should remain constant across projects:

Core Workflow Steps:

• Fundamental process that defines the skill
• Essential decision logic
• Standard operating procedures

Domain Knowledge:

• Best practices that apply universally
• Technical specifications
• API/library patterns that rarely change

Examples:

• For git-workflow: All Git commands are stable
• For project-context-generator: The 4-step workflow is stable
• For skill-analyzer: Matching heuristics are stable

Step 4: Define Mutable Elements

Identify what can evolve during projects:

New References:

• Project-specific patterns discovered
• Examples from real usage
• Edge cases encountered

Improved Explanations:

• Clarified instructions based on confusion
• Better examples
• Refined decision trees

Additional Scripts:

• Helper utilities that prove useful
• Validation tools
• Automation scripts

Examples:

• For git-workflow: Can add project-specific workflows to references/
• For project-logger: Can add new entry types based on project needs
• For skill-analyzer: Can refine matching criteria

Step 5: Define Update Rules

Specify how updates should happen:

Allowed Operations:

• Add files to references/ (always allowed)
• Modify specific sections of SKILL.md (list which ones)
• Add scripts to scripts/ (with constraints)
• Optimize phrasing (without changing meaning)

Prohibited Operations:

• Changing core workflow structure
• Removing established best practices
• Breaking backward compatibility

Review Requirements:

• What changes need human approval
• What can be automated
• When to create a new skill vs. updating existing

Step 6: Define Knowledge Extraction Needs

Specify what to look for when extracting knowledge:

Patterns to Extract:

• Common use cases that emerge
• Frequently asked questions
• Reusable code snippets

Abstraction Triggers:

• When to generalize project-specific patterns
• What threshold indicates general applicability
• How to separate general vs. project-specific

Examples:

• For frontend-design: Extract common component patterns
• For project-logger: Extract common log entry patterns
• For domain skills: Extract reusable business logic

Step 7: Generate Contract Section and File

Create both a concise contract summary in SKILL.md and a detailed contract file in references/.

A. Create references/contract.md (detailed specification):

# Skill Contract: [skill-name]

> Complete specification of what can evolve and what must remain stable.

## Stable (General Knowledge)

**Core Elements:**
- [List workflow steps, domain knowledge, or essential patterns]
- [What defines this skill's identity]

**Do not modify:**
- [Specific sections or content that must remain unchanged]

## Mutable (Can Evolve)

**Can be updated during projects:**
- [What can be added/refined in SKILL.md]
- [New files that can be added to references/]
- [Scripts that can be added to scripts/]

**Update guidelines:**
- [How to add new content]
- [What format to use]
- [When to update vs. create new skill]

## Update Rules

**Allowed without review:**
- Add new examples to existing sections
- Add reference files documenting project patterns
- Fix typos or clarify confusing wording

**Requires review:**
- Modify core workflow steps
- Change established best practices
- Add new sections to SKILL.md

**Prohibited:**
- Remove existing best practices
- Change fundamental skill purpose
- Break compatibility with existing usage

## Knowledge Extraction

**What to extract after projects:**
- [Patterns that emerged multiple times]
- [Common questions or confusion points]
- [Reusable code or templates]

**When to extract:**
- [Trigger: e.g., "After 3 projects using this skill"]
- [Indicator: e.g., "When same pattern appears in 2+ projects"]

**How to extract:**
- Add generalizable patterns to references/
- Update examples in SKILL.md with real cases
- Create new skills for project-specific domains

B. Add concise summary to SKILL.md (progressive disclosure):

## Skill Contract

**Stable:** [One-line summary of what cannot change]
**Mutable:** [One-line summary of what can evolve]
**Update rules:** [One-line summary or "See references/contract.md"]

> Full contract specification in `references/contract.md`

Example:

## Skill Contract

**Stable:** Core workflow steps, domain knowledge, essential patterns
**Mutable:** References, examples, clarifications, project-specific workflows
**Update rules:** See `references/contract.md` for detailed rules

> Full contract specification in `references/contract.md`

Step 8: Insert Contract and Create File

Execute both operations:

A. Create references/contract.md:

1. Create references/ directory if it doesn't exist
2. Write detailed contract to references/contract.md
3. Use the full template from Step 7A

B. Insert contract summary into SKILL.md:

Placement:

• After the main content
• Before the "Resources" section (if any)
• As the second-to-last section

Insertion process:

1. Read current SKILL.md
2. Find insertion point (before Resources or at end)
3. Insert concise "## Skill Contract" section
4. Write updated SKILL.md

Result: Skill now has both:

• Concise contract in SKILL.md (respects context window)
• Detailed contract in references/contract.md (for deep dives)

Step 9: Confirm and Document

Present the contract to the user:

• Show the generated contract
• Explain the stable/mutable boundaries
• Confirm update rules make sense

Ask:

• "Does this contract accurately reflect the skill's evolution rules?"
• "Are there additional constraints or freedoms needed?"

Update if necessary, then confirm completion.

Contract Templates by Skill Type

Template: Reference/Guidelines Skills

For skills like git-workflow that provide reference information:

Stable:

• Core reference content (commands, APIs, patterns)
• Organizational structure

Mutable:

• Additional examples
• Project-specific workflows in references/
• Clarifications and tips

Template: Workflow Skills

For skills like project-context-generator with step-by-step processes:

Stable:

• Workflow steps and their order
• Core questions to ask
• Template structure

Mutable:

• Example questions
• Template sections (can add, not remove)
• Additional guidance for edge cases

Template: Meta-Skills

For skills like skill-analyzer that operate on other skills:

Stable:

• Core algorithm or heuristics
• Input/output format
• Integration points

Mutable:

• Heuristic weights or criteria
• Edge case handling
• Additional validation rules

Best Practices

Be Specific About Boundaries

Good:

Can add new examples to "Best Practices" section
Can add files to references/ documenting project patterns
Cannot modify the 4-step workflow structure

Avoid vague:

Can update as needed
Don't change important parts

Consider Skill Maturity

New skills: More permissive contracts (still learning what works) Mature skills: Stricter contracts (proven patterns to preserve)

Balance Flexibility and Stability

• Too rigid: Skill can't improve
• Too flexible: Skill loses coherence
• Right balance: Core identity preserved, details evolve

Resources

references/contract_template.md

Template for the Skill Contract section with:

• Standard structure
• Examples for different skill types
• Placeholder text for customization

See this file for the complete contract template that can be customized for any skill.