Skip to main content
skill CX Codex

sop-maintenance — Claude Code skill: what it does, how to install

sop-maintenance is a Claude Code skill for maintaining, versioning, and deprecating SOPs. It keeps operational procedures current after changes to code or infrastructure.

Apache-2.0 159 installs ★ 201 updated 2026-09-08

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add TheBushidoCollective/han --skill sop-maintenance -a claude-code
Open on GitHub

What sop-maintenance does

This skill guides coding assistants through the entire SOP lifecycle. It provides conventions for treating operational docs like code: storing them in git, formatting changelogs, tracking semantic versions, and organizing directories into active, deprecated, and template categories.

The skill relies on Read, Write, Edit, Bash, Grep, and Glob tools. When an SOP becomes obsolete, the agent flags it as DEPRECATED with a clear migration guide instead of silently deleting historical knowledge. Custom procedures also take precedence over built-in ones when paths conflict.

What it helps with

  • Update runbooks and procedures following tooling or framework migrations
  • Mark outdated SOPs as deprecated with explicit migration instructions
  • Incorporate post-incident fixes and checklist verifications into existing docs
  • Structure SOP folders into active collections, archives, and templates

Example prompts for the agent

  • Update deployment/deploy-web-app.sop.md to reflect our migration from Mocha to Vitest
  • Deprecate deploy-docker-swarm.sop.md and point readers to the new Kubernetes SOP
  • Review code-review.sop.md against the maintenance checklist and bump the version

How to install sop-maintenance

1Skills CLI (Vercel)

npx skills add TheBushidoCollective/han --skill sop-maintenance -a claude-code

2Manually: put the files in place

~/.claude/skills/sop-maintenance/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/sop-maintenance/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about sop-maintenance

How to install sop-maintenance in Claude Code?

Run npx skills add TheBushidoCollective/han --skill sop-maintenance -a claude-code. The skill file will be placed in ~/.claude/skills/sop-maintenance/SKILL.md.

What does sop-maintenance do?

It guides the agent on updating, versioning, and retiring Standard Operating Procedures while keeping changelogs and directory indexes organized.

Which agent tools does this skill require?

It uses the Read, Write, Edit, Bash, Grep, and Glob tools to inspect, verify, and modify SOP markdown files.

Source text

SKILL.md · Apache-2.0
---
name: sop-maintenance
description: Use when updating, versioning, deprecating, or maintaining existing Standard Operating Procedures. Covers keeping SOPs accurate, relevant, and synchronized with implementation changes.
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
  - Glob
---

# SOP Maintenance

SOPs require ongoing maintenance to remain accurate and useful. This skill covers strategies for keeping SOPs current, managing versions, and ensuring SOPs evolve with your systems.

## Key Concepts

### SOP Lifecycle

1. **Creation**: Initial SOP development
2. **Active Use**: SOP is being executed regularly
3. **Update**: Modifications to reflect changes
4. **Deprecation**: SOP is outdated but referenced
5. **Archive/Removal**: SOP is no longer needed

### Why SOPs Become Outdated

- **Technology Changes**: Tools, frameworks, or languages updated
- **Process Evolution**: Workflows improve or change
- **Environment Changes**: Infrastructure or deployment changes
- **Discovery**: Better approaches found through experience
- **External Dependencies**: Third-party services change APIs

## Best Practices

### Version Control for SOPs

Treat SOPs as code:

```bash
# Store SOPs in git repository
my-sops/
├── .git/
├── deployment/
│   ├── deploy-web-app.sop.md
│   └── rollback-deployment.sop.md
├── development/
│   ├── code-review.sop.md
│   └── feature-implementation.sop.md
└── README.md
```

**Commit Messages:**

```bash
git commit -m "feat(deployment): add health check step to deploy-web-app.sop"
git commit -m "fix(code-review): correct security checklist items"
git commit -m "docs(development): update feature-implementation with new test framework"
```

### SOP Versioning

Include version information in SOP metadata:

```markdown
# Deploy Application to Production

**Version**: 2.1.0
**Last Updated**: 2025-12-05
**Author**: DevOps Team
**Status**: Active

## Changelog

### v2.1.0 (2025-12-05)
- Added automated rollback triggers
- Updated health check thresholds

### v2.0.0 (2025-11-15)
- Migrated to Kubernetes from Docker Swarm
- Added canary deployment steps

### v1.0.0 (2025-09-01)
- Initial deployment SOP
```

### Keeping SOPs Current

**Regular Review Schedule:**

```markdown
## SOP Maintenance Schedule

- **Monthly**: Review frequently-used SOPs (deployment, incident response)
- **Quarterly**: Review all active SOPs for accuracy
- **After Major Changes**: Update SOPs when systems change
- **Post-Incident**: Update SOPs based on lessons learned
```

**Maintenance Checklist:**

```markdown
## SOP Review Checklist

- [ ] Prerequisites are still accurate
- [ ] Tools/versions are current
- [ ] Steps reflect actual process
- [ ] Parameters are still relevant
- [ ] Success criteria are measurable
- [ ] Error handling covers common issues
- [ ] Related SOPs are still valid
- [ ] Examples use current syntax
```

### Deprecating SOPs

When an SOP is outdated:

```markdown
# ⚠️ DEPRECATED: Deploy Using Docker Swarm

**Status**: DEPRECATED as of 2025-11-15
**Replaced By**: deploy-kubernetes.sop.md
**Reason**: Migrated infrastructure from Docker Swarm to Kubernetes

## Migration Guide

If you need to migrate from this SOP:
1. Review new Kubernetes deployment SOP
2. Understand key differences in deployment process
3. Update CI/CD pipelines to use new SOP
4. Archive Docker Swarm configurations

## Original SOP (for reference only)

[Keep original content for historical reference]
```

### Managing SOP Collections

**Directory Organization:**

```bash
sops/
├── active/              # Currently used SOPs
│   ├── deployment/
│   ├── development/
│   └── operations/
├── deprecated/          # Outdated but may be referenced
│   └── legacy-deployments/
└── templates/           # SOP templates for creating new SOPs
    ├── analysis.template.sop.md
    ├── implementation.template.sop.md
    └── deployment.template.sop.md
```

**Index File:**

```markdown
# SOP Index

## Active SOPs

### Deployment
- [deploy-web-app.sop.md](active/deployment/deploy-web-app.sop.md) - v2.1.0 - Deploy web application to production
- [rollback-deployment.sop.md](active/deployment/rollback-deployment.sop.md) - v1.5.0 - Rollback failed deployment

### Development
- [code-review.sop.md](active/development/code-review.sop.md) - v3.0.0 - Review code changes
- [tdd-implementation.sop.md](active/development/tdd-implementation.sop.md) - v2.2.0 - Implement features with TDD

## Deprecated SOPs

- [deploy-docker-swarm.sop.md](deprecated/deploy-docker-swarm.sop.md) - DEPRECATED - Use deploy-web-app.sop.md instead
```

## Examples

### Example 1: Updating SOP for Tool Change

**Before (using old test framework):**

```markdown
# Run Test Suite

## Steps

1. Run tests with Mocha

   ```bash
   npm run test
   ```

1. Check coverage with Istanbul

   ```bash
   npm run coverage
   ```

```

**After (updated for Vitest):**

```markdown
# Run Test Suite

**Version**: 2.0.0
**Last Updated**: 2025-12-05
**Changes**: Migrated from Mocha to Vitest

## Steps

1. Run tests with Vitest

   ```bash
   npm run test
   ```

1. Check coverage (built into Vitest)

   ```bash
   npm run test:coverage
   ```

## Migration Notes

If migrating from v1.x (Mocha):

- Vitest uses same syntax for most assertions
- Coverage is built-in (no separate Istanbul step)
- Tests run significantly faster

```

### Example 2: Adding Environment Variable Support

**Updated SOP with env var support:**

```markdown
# Configure SOP Paths

## Overview

Configure custom SOP paths using environment variable or configuration file.
This allows teams to maintain organization-specific SOPs alongside built-in ones.

## Parameters

- **SOP Paths**: {sop_paths} - Colon-separated directory paths

## Methods

### Method 1: Environment Variable (Recommended)

Set `AGENT_SOP_PATHS` environment variable:

```bash
# In ~/.zshrc or ~/.bashrc
export AGENT_SOP_PATHS="~/my-team-sops:~/project-sops"

# Or inline for single use
AGENT_SOP_PATHS="~/my-sops" strands-agents-sops mcp
```

### Method 2: Command Line Argument

Pass paths directly to MCP server:

```bash
strands-agents-sops mcp --sop-paths ~/my-sops:~/team-sops
```

### Method 3: Configuration File

Add to Claude Code settings:

```json
{
  "mcpServers": {
    "agent-sops": {
      "command": "strands-agents-sops",
      "args": ["mcp"],
      "env": {
        "AGENT_SOP_PATHS": "~/my-sops:~/team-sops"
      }
    }
  }
}
```

## Precedence

1. Command line `--sop-paths` (highest priority)
2. `AGENT_SOP_PATHS` environment variable
3. Default paths (built-in SOPs only)

Custom SOPs override built-in SOPs with matching names.

```

### Example 3: Post-Incident SOP Update

**Adding error handling based on production incident:**

```markdown
# Deploy Application to Production

**Version**: 2.2.0
**Last Updated**: 2025-12-05
**Changes**: Added database connection pool check after incident #1234

## Changelog

### v2.2.0 (2025-12-05)
- Added database connection pool verification step
- Updated error handling for connection failures
- Added monitoring alert validation

*Reason: Production incident #1234 caused by connection pool exhaustion*

## Steps

1. Pre-deployment verification
   - Verify staging deployment healthy
   - Check database migrations ready
   - **NEW**: Verify database connection pool configuration
     ```bash
     # Check pool settings
     kubectl get configmap db-config -o yaml | grep -A5 pool

     # Validate pool size matches expected load
     # MUST be ≥ (expected_connections * 1.5)
     ```

2. Deploy application
   [... existing steps ...]

3. Post-deployment verification
   - Run smoke tests
   - Monitor error rates
   - **NEW**: Verify database connection pool metrics
     ```bash
     # Check active connections
     # MUST be < 80% of pool size
     curl https://monitoring.example.com/metrics/db-pool
     ```

## Error Handling

### NEW: Error: Database Connection Pool Exhausted

**Symptoms**: Application unable to acquire database connections, requests timing out

**Cause**: Pool size insufficient for load, connection leaks, or slow queries

**Resolution**:

1. Immediate: Scale up connection pool size

   ```bash
   kubectl patch configmap db-config --patch '{"data":{"pool_size":"100"}}'
   kubectl rollout restart deployment app
   ```

1. Monitor connection usage for 5 minutes
1. If issue persists, execute rollback
1. Post-incident: Review slow query logs and optimize

```

## Common Patterns

### Template for SOP Update

```markdown
# {SOP Title}

**Version**: {new_version}
**Last Updated**: {date}
**Changes**: {summary of changes}

## Changelog

### v{new_version} ({date})
- {change 1}
- {change 2}
- {change 3}

*Reason: {why these changes were made}*

### v{previous_version} ({date})
[Previous changes]

## [Rest of SOP content]
```

### Template for Deprecation Notice

```markdown
# ⚠️ DEPRECATED: {Old SOP Title}

**Status**: DEPRECATED as of {date}
**Replaced By**: {new-sop-file.sop.md}
**Reason**: {why deprecated}
**Support End Date**: {when will this be removed}

## Migration Guide

To migrate from this SOP to {new SOP}:

1. **Key Differences**:
   - {difference 1}
   - {difference 2}

2. **Migration Steps**:
   - {step 1}
   - {step 2}

3. **Breaking Changes**:
   - {breaking change 1}
   - {breaking change 2}

## References

- New SOP: [{new-sop-title}]({new-sop-file.sop.md})
- Migration Guide: [link]
- Announcement: [link to announcement]

---

## Original SOP (for historical reference)

[Keep original content below this line]
```

## Anti-Patterns

**Avoid These Maintenance Mistakes:**

1. **No Version Tracking**
   - ❌ Updating SOPs without tracking changes
   - ✅ Use version numbers and changelog

2. **Ignoring Deprecated SOPs**
   - ❌ Leaving outdated SOPs without deprecation notice
   - ✅ Clearly mark deprecated SOPs and provide alternatives

3. **Breaking Changes Without Notice**
   - ❌ Silently changing SOP behavior
   - ✅ Version bump and migration guide for breaking changes

4. **No Review Schedule**
   - ❌ Only updating SOPs when they break
   - ✅ Regular review schedule for all SOPs

5. **Poor Change Communication**
   - ❌ Updating SOPs without notifying users
   - ✅ Announce significant SOP changes to team

## Maintenance Workflow

### Regular Maintenance

```markdown
## Monthly SOP Maintenance

1. Review high-frequency SOPs
   - Check execution logs for failures
   - Review any reported issues
   - Update based on user feedback

2. Validate SOP accuracy
   - Run through critical SOPs manually
   - Verify tools/versions are current
   - Test examples still work

3. Update documentation
   - Fix any inaccuracies found
   - Add clarifications where needed
   - Update related SOPs

4. Commit and communicate changes
   - Commit updates with descriptive messages
   - Announce changes in team channel
   - Update SOP index
```

### Post-Change Maintenance

```markdown
## After System Changes

When infrastructure, tools, or processes change:

1. Identify affected SOPs

   ```bash
   # Search for SOPs mentioning changed component
   grep -r "docker" sops/*.sop.md
   ```

1. Update each affected SOP
   - Update version number
   - Add changelog entry
   - Modify affected steps
   - Update examples

1. Test updated SOPs
   - Run through new workflow
   - Verify all steps work
   - Check success criteria still valid

1. Review dependencies
   - Check related SOPs need updates
   - Update SOP index
   - Notify team of changes

```

## Related Skills

- **sop-authoring**: Create new SOPs with quality
- **sop-structure**: Organize SOPs effectively
- **sop-rfc2119**: Use precise requirement keywords

© TheBushidoCollective · Apache-2.0 · TheBushidoCollective/han

Similar skills

All skills for Writing and docs →

From the same set36

The whole set →
bdd-patterns bdd-patterns helps agents write BDD specifications with Given–When–Then, feature files, and acceptance criteria. Use it when behavior must guide implementation. CX Codex +1 211installs bdd-scenarios This skill helps turn requirements into BDD scenarios, acceptance criteria, and edge cases. Use it to clarify expected behavior before implementation. CX Codex +1 180installs playwright-bdd-gherkin-syntax playwright-bdd-gherkin-syntax guides agents in drafting Gherkin feature files, outlines, data tables, and tags for Playwright BDD. CX Codex +1 180installs storybook-component-documentation Generates Storybook component documentation via autodocs, MDX pages and JSDoc comments. Useful when creating or updating UI library docs. CX Codex +1 166installs cucumber-best-practices cucumber-best-practices teaches coding agents to write declarative Gherkin scenarios and maintain independent Cucumber tests. Clean step definitions without UI selectors. CX Codex +1 154installs android-kotlin-coroutines android-kotlin-coroutines is a Claude Code skill for asynchronous Kotlin patterns in Android apps. It guides coroutines, Flow, StateFlow, and safe concurrency across ViewModels and Jetpack Compose. CX Codex +1 145installs ios-uikit-architecture ios-uikit-architecture — a skill with UIKit architecture patterns: MVVM, MVC, coordinators, dependency injection, and integration of SwiftUI into UIKit apps. Use it when building iOS applications with UIKit. CX Codex +1 145installs android-architecture This skill guides Android architecture with MVVM, clean layers, Hilt, and Room. Use it when shaping app structure or separating UI from business logic. CX Codex +1 141installs

Project sponsors

Companies that keep this analytics open