---
name: usethis-skills-modify
description: Modify agent skills (SKILL.md files)
compatibility: usethis, agent skills, markdown
license: MIT
metadata:
  version: "1.1"
---

# Modifying Agent Skills

## Procedure

When modifying any `SKILL.md` file in `.agents/skills/`:

1. Make the necessary content changes to the skill.
2. Increment the version number in the YAML frontmatter `metadata.version` field.
3. Verify the YAML frontmatter is valid (all required fields present, version is quoted).

## Incrementing the version

Every time a `SKILL.md` file is modified, its `metadata.version` must be incremented. This applies to any change, including:

- Adding, removing, or rewording instructions
- Updating procedures or steps
- Fixing typos or formatting
- Changing metadata fields other than `version`

The version follows a `MAJOR.MINOR` format (e.g. `"1.0"`, `"1.1"`, `"2.0"`).

- **Minor version bump** (e.g. `"1.1"` → `"1.2"`): Use for most changes, including adding new guidance or instructions on top of existing ones, rewording, fixing typos, expanding examples, or making minor corrections. If the fundamental approach of the skill remains the same, it's a minor bump.
- **Major version bump** (e.g. `"1.2"` → `"2.0"`): Use only when the fundamental approach or strategy of the skill is being replaced, reversed, or overhauled. A major bump means the previous version's guidance was flawed or is being abandoned in favour of a substantially different approach.

When in doubt, use a minor version bump. Adding extra guidance to a skill is not a fundamental change — it's a refinement.

### Why version incrementing matters

Incrementing the version on every change helps ensure that merge conflicts are detected when two people modify the same skill concurrently. Without versioning, two independent changes to a skill could be silently merged at the git level even though the combined result may be inconsistent or contradictory. The version bump forces a conflict, prompting a human review.

## Content quality guidelines

When modifying skill content, maintain these principles:

- **Describe procedures, not state.** Skills should explain how to approach situations, not describe the current state of the codebase. State descriptions become outdated; procedures remain valid. See the `usethis-skills-create` skill for detailed guidance.
- **Keep content general.** Write instructions that remain valid as the codebase evolves. Avoid embedding specific file paths, class names, or constants unless strictly necessary.
- **Be concise.** Only include information the agent doesn't already know. If a paragraph doesn't justify its token cost, remove it.
- **Avoid time-sensitive information.** Don't include current version numbers, file counts, or lists that grow over time.
- **Use consistent terminology.** Don't introduce synonyms for concepts that already have established terms in the skill.

## YAML frontmatter format

All `SKILL.md` files must include the following YAML frontmatter fields:

```yaml
---
name: <skill-name>
description: <brief description>
compatibility: <comma-separated technologies>
license: MIT
metadata:
  version: "<MAJOR.MINOR>"
---
```
