Skill Promotion Workflow

Manages atomic promotion of skills from staging directory to production with validation, SLA enforcement, and optional auto-deployment.

Overview

The skill promotion workflow automates the process of moving generated skills from the staging directory to production, ensuring:

• Atomic Operations: Skills are moved atomically to prevent partial promotions
• Pre-Promotion Validation: Content integrity, schema compliance, and test execution
• SLA Enforcement: Skills older than 48 hours in staging trigger alerts
• Git Integration: Optional automatic commit with promotion metadata
• Auto-Deployment: Optional integration with deployment pipeline (Task 1.1)

Architecture

.claude/skills/
├── staging/              # Skills pending promotion (temporary)
│   ├── auth-v2/
│   │   ├── SKILL.md
│   │   ├── execute.sh
│   │   └── test.sh
│   └── logging-v3/
│       └── ...
└── [production]/         # Production skills (after promotion)
    ├── authentication/
    ├── logging/
    └── ...

Usage

CLI Script

# List all staged skills
./scripts/promote-staged-skills.sh --list

# Check for stale skills (>48h)
./scripts/promote-staged-skills.sh --check-stale

# Promote a specific skill (with confirmation prompt)
./scripts/promote-staged-skills.sh .claude/skills/staging/auth-v2

# Auto-promote if validation passes (no prompt)
./scripts/promote-staged-skills.sh .claude/skills/staging/auth-v2 --auto

# Promote with git commit and deployment
./scripts/promote-staged-skills.sh .claude/skills/staging/auth-v2 --auto --git-commit --deploy

# Force promotion (skip validation - admin only)
./scripts/promote-staged-skills.sh .claude/skills/staging/auth-v2 --force --auto

TypeScript API

import { SkillPromotionService } from './src/services/skill-promotion';
import { DatabaseService } from './src/lib/database-service';

const dbService = new DatabaseService({ type: 'sqlite', path: './data/cfn.db' });
const promotionService = new SkillPromotionService(dbService);

// Promote a skill
const result = await promotionService.promoteSkill(
  '.claude/skills/staging/auth-v2',
  {
    autoDeploy: true,
    gitCommit: true,
    notify: true,
    promotedBy: 'admin@example.com'
  }
);

if (result.success) {
  console.log(`Skill promoted: ${result.skillName}`);
  console.log(`Production path: ${result.productionPath}`);
  console.log(`Deployment ID: ${result.deploymentId}`);
} else {
  console.error(`Promotion failed: ${result.error}`);
}

// List staged skills
const stagedSkills = await promotionService.listStagedSkills();
console.log(`${stagedSkills.length} skills in staging`);

// Check for stale skills (>48h)
const staleSkills = await promotionService.checkStaleness();
if (staleSkills.length > 0) {
  console.log(`WARNING: ${staleSkills.length} stale skills detected`);
  for (const skill of staleSkills) {
    console.log(`  - ${skill.name} (${skill.ageHours}h, ${skill.slaBreachHours}h over SLA)`);
  }
}

Validation Checks

The promotion validator performs the following checks:

1. Content Integrity

• SKILL.md exists and is readable
• execute.sh exists and is executable
• Optional: test.sh, README.md (warnings if missing)

2. Schema Compliance

• Frontmatter is valid YAML
• Required fields: name, description, version
• Version follows semantic versioning (X.Y.Z)
• Optional fields: author, tags, dependencies

3. Test Execution

• If test.sh exists, it must be executable
• Tests run with 30-second timeout
• Test failures generate warnings (non-fatal, allow --force)

4. Conflict Detection

• Check if production skill already exists
• Compare versions (staging vs production)
• Warn if overwriting (require --overwrite flag)

SLA Enforcement

Skills in staging for >48 hours trigger SLA breach alerts:

Manual Checking

./scripts/promote-staged-skills.sh --check-stale

Automated Checking (Cron Job)

# Run daily at 9am to check for stale skills
0 9 * * * cd /path/to/project && ./scripts/promote-staged-skills.sh --check-stale

Background Job (TypeScript)

import { PromotionSLAEnforcer } from './src/jobs/promotion-sla-enforcer';

const enforcer = new PromotionSLAEnforcer(dbService, {
  autoPromote: true,  // Auto-promote stale skills
  notifyStale: true,  // Send notifications
});

await enforcer.enforceSLA();

Configuration

Environment variables:

# SLA threshold (hours)
CFN_PROMOTION_SLA_THRESHOLD=48

# Auto-promote stale skills
CFN_PROMOTION_AUTO_PROMOTE=true

# Enable git commits
CFN_PROMOTION_GIT_COMMIT=true

# Enable auto-deployment
CFN_PROMOTION_AUTO_DEPLOY=true

Monitoring

Database Queries

-- Skills currently in staging
SELECT name, created_at,
       ROUND((julianday('now') - julianday(created_at)) * 24, 1) as age_hours
FROM staged_skills
WHERE promoted = 0
ORDER BY created_at ASC;

-- Promotion success rate (last 30 days)
SELECT
  COUNT(*) as total_promotions,
  SUM(CASE WHEN success = 1 THEN 1 ELSE 0 END) as successful,
  ROUND(100.0 * SUM(success) / COUNT(*), 2) as success_rate
FROM skill_promotions
WHERE promoted_at > datetime('now', '-30 days');

-- SLA breaches (skills >48h in staging)
SELECT COUNT(*) as sla_breaches
FROM staged_skills
WHERE promoted = 0
  AND created_at < datetime('now', '-48 hours');

Dashboard Metrics

• Staged Skills Count: Number of skills awaiting promotion
• Average Time in Staging: Mean age of staged skills
• SLA Breach Count: Skills >48h in staging
• Promotion Success Rate: Successful promotions / total attempts
• Auto-Deploy Success Rate: Successful deployments / total promotions

Integration Points

Task 1.1: Skill Deployment Pipeline

After promotion, skills can be automatically deployed:

const result = await promotionService.promoteSkill(stagingPath, {
  autoDeploy: true  // Triggers SkillDeploymentPipeline
});

Task 0.5: Utilities

• file-operations.ts: Atomic moves, file locking
• logging.ts: Structured logging
• errors.ts: Error handling

Phase 4: Skill Generation

Generated skills are placed in staging directory:

// Skill generator outputs to staging
const stagingPath = await skillGenerator.generate({
  output: '.claude/skills/staging/new-skill'
});

// Later: promote to production
await promotionService.promoteSkill(stagingPath);

Error Handling

Promotion Failures

• Validation errors: Fix skill and retry
• Conflicts: Use --overwrite or resolve manually
• Test failures: Use --force (admin only) or fix tests

Rollback

If promotion fails mid-operation:

1. Staging skill remains in staging (atomic move failed)
2. Production skill is unchanged (or restored from backup)
3. Database records rollback
4. Git commits are not created

Manual Rollback

# If promotion succeeded but deployment failed
rm -rf .claude/skills/production-skill
mv .claude/skills/staging/backup-skill .claude/skills/staging/production-skill

Troubleshooting

"Validation failed: Missing required file: execute.sh"

Solution: Add execute.sh to staged skill

"execute.sh is not executable"

Solution: Run chmod +x execute.sh

"Tests failed (non-fatal)"

Solution: Fix tests or use --force to skip

"Skill already exists in production"

Solution: Use --overwrite flag or choose different name

"Git commit failed"

Solution: Ensure git repo is initialized and configured

Best Practices

1. Always validate before promotion (don't use --force unless necessary)
2. Run tests in staging before promotion
3. Monitor SLA breaches (check stale skills daily)
4. Use git commits for audit trail
5. Enable auto-deployment for production readiness
6. Backup production skills before overwriting
7. Test promotions in dev environment first

Future Enhancements

• Webhook notifications (Slack, email)
• Multi-stage promotion (staging → qa → production)
• Approval workflows (require manual approval for production)
• Promotion rollback automation
• Integration with CI/CD pipelines
• Promotion scheduling (promote at specific times)
• Batch promotion (promote multiple skills at once)

Related Documentation

• Task 1.1: .claude/skills/cfn-deployment/SKILL.md
• Task 0.5: docs/IMPLEMENTATION_UTILITIES.md
• Phase 4: docs/SKILL_GENERATION.md (future)
• Operational Guide: docs/SKILL_PROMOTION_WORKFLOW.md