updating-skills
Skill0 starsChanged 9 months agoMITView on GitHub
Systematic workflow for modifying existing Agent Skills. Ensures spec compliance, version bumps, changelog updates, and audit pass after every change. Activates when user asks to "update skill", "modify skill", "evolve skill", "bump version", or mentions changing an existing skill. Do NOT use when creating, auditing, or testing skills.
- Commits and pushes
In this repository17 other files it gives its agents.
- AGENTS.mdAGENTS.md
- auditing-skillsSkill
- creating-skillsSkill
- forge-builderSkill
- forge-claude-teamsSkill
- forge-codex-multiagentSkill
- forge-orchestratorSkill
- forge-researchSkill
- handoff-freshSkill
- handoffSkill
- managing-doc-manifestSkill
- okfSkill
- pickupSkill
- studySkill
- syncing-docsSkill
- testing-skillsSkill
- wrapSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
18 rules. About 0 are common, 17 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈17
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 28
When iterating on a skill across multiple conversations, the creating-skills spec and auditing-skills checklist can fall out of context.
- Distinctive: line 32
Use TaskCreate to track progress:
- Distinctive: line 49
Before any changes, read all skill files:
- Distinctive: line 63
Never propose changes to files you haven't read.
- Distinctive: line 75
When in doubt, use minor.
- Distinctive: line 88
Run evaluations before changes (baseline) and after (regression check).
- Distinctive: line 102
When updating, check all files for consistency:
- Distinctive: line 115
Follow Keep a Changelog format:
- Distinctive: line 141
Run the auditing-skills checklist.
- Distinctive: line 193
Only for skills published to GitHub:
- Very specific: line 212
Read all files: SKILL.md, CHANGELOG.md, EVALUATIONS.md, examples.md, heuristics.md, README.md, LICENSE
- Distinctive: line 213
Run current evaluations (baseline — all pass)
- Distinctive: line 217
Update EVALUATIONS.md (add Python triggering + functional scenario)
- Distinctive: line 218
Update frontmatter version to "4.4.0"
- Distinctive: line 219
Add CHANGELOG.md entry for 4.4.0
- Distinctive: line 237
Update this skill when:
- Distinctive: line 238
On missed consistency issue: Add to cross-file checklist
- Distinctive: line 239
On new pitfall: Add to common pitfalls table
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Updating Skills
Systematic workflow for modifying existing Agent Skills while maintaining spec compliance.
Why This Exists
When iterating on a skill across multiple conversations, the creating-skills spec and auditing-skills checklist can fall out of context. This skill ensures every update follows the same disciplined process.
Workflow
Use TaskCreate to track progress:
- 1. Read current state (all skill files)
- 2. Run current evaluations (baseline)
- 3. Understand requested changes
- 4. Classify version bump (major/minor/patch)
- 5. Make changes following spec
- 6. Update EVALUATIONS.md (if behavior changed)
- 7. Bump version in frontmatter
- 8. Update CHANGELOG.md
- 9. Audit against checklist
- 10. Fix any audit issues
- 11. Present summary to user
- 12. Push if published (user confirms)
Reading Current State
Before any changes, read all skill files:
skill-name/
├── SKILL.md # Always read first
├── CHANGELOG.md # Check current version
├── EVALUATIONS.md # Check existing test scenarios
├── examples.md # If exists
├── heuristics.md # If exists
├── reference.md # If exists
├── README.md # If exists (published skills)
└── LICENSE # If existsNever propose changes to files you haven't read.
Classifying Version Bump
Follow semver:
| Change Type | Bump | Example |
| Breaking change (workflow restructure, removed feature) | Major X.0.0 | 4.0.0 → 5.0.0 |
| New feature, new section, new capability | Minor x.Y.0 | 4.2.0 → 4.3.0 |
| Bug fix, typo, version ref fix, wording tweak | Patch x.y.Z | 4.3.0 → 4.3.1 |
When in doubt, use minor.
Evaluation-First Updates
Decide whether EVALUATIONS.md needs changes:
| Change Type | Update EVALUATIONS.md? | Example |
| New feature / capability | Yes — add scenario | Added Python support → add Python triggering + functional test |
| Changed behavior | Yes — update existing scenario | Modified output format → update expected output |
| Bug fix | Maybe — add edge case if gap exposed | Fix crash on empty input → add empty-input scenario |
| Wording / typo only | No | Fixed typo in description |
Run evaluations before changes (baseline) and after (regression check). Use testing-skills for execution.
Making Changes
Follow creating-skills spec:
- Third person in description — "Processes files" not "I process files"
- Body under 500 lines — use progressive disclosure if larger
- Concrete examples — real input/output, not abstract
- One-level references — SKILL.md → ref.md, never ref.md → detail.md
- No over-engineering — only change what was requested
Cross-File Consistency
When updating, check all files for consistency:
| Check | Where |
| Version string | Frontmatter, CHANGELOG.md, examples.md, README.md |
| Workflow step count | SKILL.md workflow section, any "X steps" references |
| Feature references | If adding/removing a feature, update all mentions |
| Repo/URL references | If changing URLs, check every file |
This is the most common source of audit failures.
Updating CHANGELOG.md
Follow Keep a Changelog format:
## [X.Y.Z] - YYYY-MM-DD
### Added
- New features
### Changed
- Modified behavior
### Fixed
- Bug fixes
### Removed
- Removed featuresRules:
- Newest version at top
- Date in ISO format
- Group changes by type
- Be specific — "Added deep dependency investigation" not "Updated skill"
Auditing
Run the auditing-skills checklist. Key checks:
Frontmatter
name: lowercase, hyphens, matches directorydescription: third person, what + when, max 1024 charslicense: presentmetadata.version: matches CHANGELOG.md latest entry
Content
- Body under 500 lines
- Workflow checklist present
- Concrete example present
- Self-evolution section present
- References one level deep
Evaluations
- EVALUATIONS.md present and up to date
- New/changed behavior has matching scenario
- should-NOT-trigger scenarios still valid
Cross-File (updating-specific)
- Version consistent across all files
- Step counts match across all references
- No stale references to removed features
- No hardcoded values that should be generic
- CHANGELOG.md entry matches actual changes
Quality
- No over-explaining
- No Windows paths
- No first/second person in description
- Consistent terminology
Report format:
## Audit Result
**Grade**: A / B / C
**Version**: X.Y.Z
| Status | Count |
|--------|-------|
| Critical | 0 |
| Warnings | 0 |
| Suggestions | 0 |
{Details if any issues found}Pushing (If Published)
Only for skills published to GitHub:
cd <skill-directory>
git add -A
git commit -m "v{X.Y.Z}: {one-line summary}"
git pushLocal-only skills skip this step.
Example
Input:
Update the screening-github-cloud skill to add Python supportProcess:
- Read all files: SKILL.md, CHANGELOG.md, EVALUATIONS.md, examples.md, heuristics.md, README.md, LICENSE
- Run current evaluations (baseline — all pass)
- Changes needed: Add Python screening patterns
- Version bump: minor (new capability) → 4.4.0
- Make changes in SKILL.md, heuristics.md, examples.md
- Update EVALUATIONS.md (add Python triggering + functional scenario)
- Update frontmatter version to "4.4.0"
- Add CHANGELOG.md entry for 4.4.0
- Audit all files for consistency
- Fix any stale version refs (examples.md commonly has old versions)
- Present diff summary
- Push to GitHub
Common Pitfalls
| Pitfall | Prevention |
| Stale version in examples.md | Search all files for old version string |
| Step count mismatch | Grep for "X steps" across all files |
| Hardcoded values surviving a "make generic" change | Search for the old hardcoded string |
| Forgetting CHANGELOG.md | Always update before audit |
| Amending when should be new version | Each user-requested change set = new version |
Self-Evolution
Update this skill when:
- On missed consistency issue: Add to cross-file checklist
- On new pitfall: Add to common pitfalls table
- On workflow improvement: Refine steps based on real usage
Current version: 2.0.0. See CHANGELOG.md for history.
References
- Creating skills spec (v4.0.0): creating-skills
- Auditing checklist (v2.0.0): auditing-skills
- Testing evaluations: testing-skills
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

