Skill Reviewer

Skill Reviewer

Review, validate, generalize, and publish existing Claude Code skills following best practices for public distribution. (To scaffold a brand-new skill, use the companion skill-builder skill.)

---

Core Principle: Generalization for Public Users

CRITICAL: Skills in ~/.claude/skills/ may be shared publicly. Never include:

| ❌ Never Include | ✅ Use Instead | |------------------|----------------| | Hardcoded project names | Environment variables | | Specific UUIDs/IDs | process.env.VAR_NAME | | Personal API endpoints | Configurable URLs | | Company-specific logic | Generic patterns | | Internal team references | Generic examples |

Example: Linear Skill Refactoring

Before (project-specific):

export const INITIATIVES = {
  SKILLSMITH: '5e1cebfe-f4bb-42c1-988d-af792fc4253b'
}
export async function linkAllSkillsmithProjects() { ... }

After (generalized):

export const DEFAULT_INITIATIVE_ID = process.env.LINEAR_DEFAULT_INITIATIVE_ID || ''
export async function linkProjectsToInitiative(initiativeId: string, filter?) { ... }

---

Behavioral Classification (ADR-025)

Every skill must declare its behavioral type. This determines how the skill interacts with users.

1. Autonomous Execution

Directive: EXECUTE, DON'T ASK

Skills that follow a prescribed workflow automatically. No permission-seeking.

| Use For | Examples | |---------|----------| | Enforcement/compliance | governance, docker-enforce | | Automated fixes | lint-fix, format | | CI/CD integrations | deploy, release |

2. Guided Decision

Directive: ASK, THEN EXECUTE

Skills that ask structured questions upfront, then execute based on decisions.

| Use For | Examples | |---------|----------| | Planning/architecture | wave-planner, mcp-decision-helper | | Configuration wizards | init, setup | | Template generators | skill-builder |

3. Interactive Exploration

Directive: ASK THROUGHOUT

Skills with ongoing dialogue. The conversation IS the value.

| Use For | Examples | |---------|----------| | Research/exploration | researcher | | Browser automation | dev-browser | | Debugging sessions | debugger |

4. Configurable Enforcement

Directive: USER-CONFIGURED

Skills that adapt behavior based on project/user configuration.

| Use For | Examples | |---------|----------| | Security tools with severity levels | varlock, security-auditor | | Linting with configurable strictness | eslint-wrapper | | Environment-dependent workflows | ci-doctor |

Classification Decision Tree

Does the skill need user input to work?
│
├─ NO → Autonomous Execution
│
└─ YES → Is input needed throughout, or just upfront?
         │
         ├─ UPFRONT → Guided Decision
         │
         └─ THROUGHOUT → Interactive Exploration

Exception: If behavior depends on config → Configurable Enforcement

---

Skill Creation Checklist

1. Structure Validation

skill-name/
├── SKILL.md              # Required: Core instructions
├── README.md             # Required: Human-readable docs and install instructions
├── CHANGELOG.md          # Required: Version history in Keep a Changelog format
├── references/           # Optional: Detailed docs
├── scripts/              # Optional: Utility scripts
├── hooks/                # Optional: Pre/post command hooks
└── examples/             # Optional: Working examples

README.md must include: problem statement, install command (the Claude Code plugin marketplace flow — claude plugin marketplace add / then claude plugin install @; skillsmith install / is an alternative), usage examples, contents table, requirements.

CHANGELOG.md must include: ## [X.Y.Z] - YYYY-MM-DD entry for every version with Added/Changed/Fixed sections.

2. SKILL.md Requirements

Frontmatter (required):

---
name: Skill Name
description: This skill should be used when the user asks to "phrase 1", "phrase 2", "phrase 3". Be specific with trigger phrases.
version: 1.0.0
---

Behavioral Classification (required in body):

Every skill MUST include a Behavioral Classification section immediately after the title.

## Behavioral Classification

**Type**: [Autonomous Execution | Guided Decision | Interactive Exploration | Configurable Enforcement]

**Directive**: [EXECUTE, DON'T ASK | ASK, THEN EXECUTE | ASK THROUGHOUT | USER-CONFIGURED]

[Brief description of how the skill interacts with users]

Body requirements:

• Use imperative form ("Configure the server", not "You should configure")
• Keep under 2,000 words (move details to references/)
• Reference all bundled resources
• No project-specific details

3. Generalization Checklist

Before publishing or committing any skill:

• [ ] Behavioral classification declared: Type and directive documented
• [ ] No hardcoded IDs: UUIDs, project IDs, initiative IDs → environment variables
• [ ] No specific names: Project names, company names → generic examples
• [ ] No personal URLs: API endpoints, webhooks → configurable via env vars
• [ ] No internal references: Team names, internal docs → generic documentation
• [ ] Environment variables documented: All required env vars listed
• [ ] Generic examples: Examples use placeholder values like ``

3.1 Documentation Generalization (MANDATORY)

CRITICAL: ALL documentation files (README.md, references/, examples/, lessons-learned.md) MUST be fully generalized. This is non-negotiable for public skills.

What to Generalize in Documentation

| ❌ Project-Specific | ✅ Generic Replacement | |--------------------|------------------------| | "Skillsmith" | "[Project Name]" or "your project" | | "SMI-1234" (Linear issues) | "[ISSUE-ID]" or "[Tracking Issue]" | | "Apache-2.0 to Elastic License 2.0" | "[Old License] to [New License]" | | "ADR-013", "ADR-017" | "ADR-XXX", "ADR-YYY" | | Specific file paths from a project | Generic paths like "docs/adr/*.md" | | Company names (Smith Horn Group, etc.) | "[Your Company]" or omit entirely | | Real dates tied to a project | "[Date]" or "[Month Year]" |

Case Studies and Examples

When including case studies or lessons learned:

# ❌ BAD - Project-specific case study
## Case Study: Skillsmith License Migration (January 2026)
After migrating Skillsmith from Apache-2.0 to Elastic License 2.0...
Created Linear issue SMI-1369...

# ✅ GOOD - Generalized case study
## Case Study: License Migration (Generic Example)
After migrating a project from an open-source license (e.g., Apache-2.0, MIT)
to a source-available license (e.g., Elastic License 2.0, BSL)...
Created tracking issue [ISSUE-ID]...

Templates Must Use Placeholders

All templates in a skill must use generic placeholders:

# ❌ BAD - Specific project in template
> **Linear Issue:** SMI-XXXX (to be created)
> See [ADR-013](../adr/013-open-core-licensing.md)

# ✅ GOOD - Generic placeholders
> **Tracking Issue:** [ISSUE-ID] (to be created)
> See [ADR-XXX](../adr/XXX.md)

Automatic Generalization Check

Before publishing ANY skill, run:

# Search for common project-specific patterns
grep -ri "skillsmith\|smi-[0-9]\|smith.horn" skill-name/
grep -ri "lin_api_\|api_key.*=" skill-name/  # Exposed secrets

If ANY matches are found, the skill is NOT ready for publishing.

4. Varlock for Secrets Management

CRITICAL: All skills handling secrets MUST use Varlock to prevent exposure.

Required Files

skill-name/
├── .env.schema      # Variable definitions with @sensitive annotations (commit)
├── .env.example     # Template with placeholders (commit)
└── .env             # Actual secrets (NEVER commit)

.env.schema Format

# @type=string(startsWith=lin_api_) @required @sensitive
LINEAR_API_KEY=

# @type=string @optional
LINEAR_DEFAULT_INITIATIVE_ID=

Safe Commands (Always Use)

varlock load                           # Validate (masked output)
varlock run -- npx tsx scripts/my.ts   # Run with secrets injected

Unsafe Commands (NEVER Use)

echo $API_KEY        # ❌ Exposes to Claude's context
cat .env             # ❌ Exposes all secrets
tool config show     # ❌ Many tools print secrets!

Document in SKILL.md

## Environment Variables

| Variable | Required | Sensitive | Description |
|----------|----------|-----------|-------------|
| `LINEAR_API_KEY` | Yes | 🔐 Yes | Your Linear API key |
| `LINEAR_DEFAULT_INITIATIVE_ID` | No | No | Default initiative for linking |

---

Skill Update Workflow

When modifying an existing skill:

Step 1: Audit for Project-Specific Content

# Search for hardcoded values
grep -r "SKILLSMITH\|MyProject\|specific-id" skill-name/
grep -r "[0-9a-f]{8}-[0-9a-f]{4}" skill-name/  # UUIDs

Step 2: Extract to Environment Variables

// Before
const PROJECT_ID = '5e1cebfe-f4bb-42c1-988d-af792fc4253b'

// After
const PROJECT_ID = process.env.MY_SKILL_PROJECT_ID || ''
if (!PROJECT_ID) {
  throw new Error('MY_SKILL_PROJECT_ID environment variable required')
}

Step 3: Rename Project-Specific Functions

// Before
export async function updateSkillsmithProject() { ... }

// After
export async function updateProject(projectId: string) { ... }

Step 4: Update Documentation

• Replace specific examples with generic placeholders
• Document all environment variables
• Add configuration section to SKILL.md

Step 5: Validate

Run the validation script:

npx tsx scripts/validate-skill.ts skill-name/

Step 5.5: Bump version and update CHANGELOG

Every meaningful change to a skill requires a version bump and a CHANGELOG entry. Use semver rules:

| Change type | Bump | Example | |-------------|------|---------| | Bug fix, copy correction, typo | PATCH | 1.0.0 → 1.0.1 | | New section, new workflow step, new trigger phrase | MINOR | 1.0.1 → 1.1.0 | | Renamed triggers, removed steps, behavioural change | MAJOR | 1.1.0 → 2.0.0 |

# 1. Update frontmatter
sed -i '' 's/^version: .*/version: "X.Y.Z"/' SKILL.md

# 2. Add CHANGELOG entry
# ## [X.Y.Z] - YYYY-MM-DD
# ### Added / Changed / Fixed
# - Description of change

Before starting any update, record the current version so the diff is clear:

grep "^version:" SKILL.md   # Note this before editing

Step 6: Publish — README, CHANGELOG, GitHub release, and tag (MANDATORY)

Every new skill and every version bump must complete all four steps before the work is considered done:

# 1. Confirm README.md exists and covers: problem, install, usage, contents, requirements
ls README.md || echo "MISSING README.md — create it before publishing"

# 2. Confirm CHANGELOG.md has an entry for this version
grep "## \[$(grep '^version:' SKILL.md | awk '{print $2}')\]" CHANGELOG.md \
  || echo "MISSING CHANGELOG entry for this version"

# 3. Commit everything
git add .
git commit -m "feat:  v"

# 4. Push to GitHub
git push

# 5. Create GitHub release with tag
VERSION=$(grep '^version:' SKILL.md | awk '{print $2}' | tr -d '"')
gh release create "v${VERSION}" \
  --title "v${VERSION}" \
  --notes "$(grep -A 50 "## \[${VERSION}\]" CHANGELOG.md | tail -n +2 | sed '/^## \[/q' | head -n -1)"

Required README.md sections:

• What problem does this skill solve?
• Install command — Claude Code plugin marketplace flow (claude plugin marketplace add / then claude plugin install @); skillsmith install / is an alternative
• Usage examples (copy-pasteable)
• Contents table (files and what they do)
• Requirements

Required CHANGELOG.md format:

## [X.Y.Z] - YYYY-MM-DD

### Added
- New features

### Changed
- Breaking or behavioural changes

### Fixed
- Bug fixes

---

Versioning & Release

Skill Pack Release: Version Drift Audit

Before releasing a skill pack (e.g. product-builder-starter), verify bundled versions match their sources. Skills in a pack can silently fall behind — e.g. linear was bundled at 2.0.0 while the source had reached 2.2.3 (a 14-release gap).

# List all bundled skill versions
for skill_md in skills/*/SKILL.md; do
  skill=$(basename $(dirname "$skill_md"))
  version=$(grep "^version:" "$skill_md" | head -1)
  echo "$skill: $version"
done

# Cross-reference against installed sources
for skill_md in ~/.claude/skills/*/SKILL.md; do
  skill=$(basename $(dirname "$skill_md"))
  version=$(grep "^version:" "$skill_md" | head -1)
  echo "[source] $skill: $version"
done

If a bundled version is behind: update the SKILL.md, add the missing CHANGELOG entries, and bump the version in the pack before tagging the release.

Frontmatter Completeness Check

Run before tagging any release. Missing version: is a silent failure — the registry cannot index the skill, skill_diff has no baseline, and release notes are incomplete.

# Check all SKILL.md files for required fields
for skill_md in skills/*/SKILL.md; do
  skill=$(basename $(dirname "$skill_md"))
  for field in name version description; do
    grep -q "^${field}:" "$skill_md" || echo "MISSING $field in $skill/SKILL.md"
  done
done

Monorepo Tag Convention

For skill packs with multiple skills, use the /v tag format:

git tag governance/v1.4.0
git tag linear/v2.2.3
git tag varlock/v1.0.0
git push --tags

This enables per-skill version history in the same repository without tag collisions.

---

Bulk Find & Replace Operations

When renaming a term across a skill pack (e.g. a dependency renames like claude-flow → ruflo):

Step 1: Always grep case-insensitively first

# Capture ALL capitalisation variants before writing sed patterns
grep -ri "old-term" skills/

Common variants to watch for — all require separate sed expressions:

| Variant | Appears in | |---------|-----------| | old-term | Body text, code blocks | | Old-Term | Section headings (### Old-Term MCP) | | OldTerm | CamelCase references | | OLD_TERM | Env var names |

Step 2: Use sed for strings containing angle brackets

The Edit tool HTML-encodes ` as < and >, writing the entity as literal text. Always use sed` for replacements involving placeholder strings:

# ❌ Edit tool — writes <project>-dev-1 as literal text
# ✅ Use sed instead:
sed -i '' 's/old-container/-dev-1/g' path/to/file.md

Step 3: Verify with a post-rename grep

grep -ri "old-term" skills/   # Should return empty

---

Common Mistakes

Mistake 1: Hardcoded Project References

❌ Bad:

const result = await createSkillsmithProject({...})
await linkToSkillsmithInitiative(projectId)

✅ Good:

const result = await createProject(teamId, {..., initiative: initiativeId})
await linkProjectToInitiative(projectId, initiativeId)

Mistake 2: Missing Environment Variable Validation

❌ Bad:

const apiKey = process.env.API_KEY  // Silently undefined

✅ Good:

const apiKey = process.env.API_KEY
if (!apiKey) {
  throw new Error('API_KEY environment variable is required')
}

Mistake 3: Project-Specific Examples

❌ Bad:

## Example
Link the Skillsmith Phase 5 project to the initiative.

✅ Good:

## Example
Link a project to an initiative:
\`\`\`bash
npx tsx lib/initiative.ts link  [project-filter]
\`\`\`

---

Lessons Learned from Linear Skill

The Linear skill update revealed common patterns to avoid:

1. Hardcoded Initiative IDs

• Problem: INITIATIVES.SKILLSMITH = '5e1cebfe-...'
• Solution: DEFAULT_INITIATIVE_ID = process.env.LINEAR_DEFAULT_INITIATIVE_ID

2. Project-Specific Function Names

• Problem: linkAllSkillsmithProjects(), verifyAllSkillsmithProjects()
• Solution: linkProjectsToInitiative(id, filter), verifyProjectsForInitiative(id, filter)

3. Missing Configuration Docu

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wrsmith108
• Source: wrsmith108/skill-builder-claude-skill
• License: MIT

Install and usage instructions live in the source repository linked above.