# Skill Reviewer

> >

- **Type:** Skill
- **Install:** `agentstack add skill-wrsmith108-skill-builder-claude-skill-skill-reviewer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [wrsmith108](https://agentstack.voostack.com/s/wrsmith108)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [wrsmith108](https://github.com/wrsmith108)
- **Source:** https://github.com/wrsmith108/skill-builder-claude-skill/tree/main/skills/skill-reviewer

## Install

```sh
agentstack add skill-wrsmith108-skill-builder-claude-skill-skill-reviewer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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):**
```typescript
export const INITIATIVES = {
  SKILLSMITH: '5e1cebfe-f4bb-42c1-988d-af792fc4253b'
}
export async function linkAllSkillsmithProjects() { ... }
```

**After (generalized):**
```typescript
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):**
```yaml
---
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.

```markdown
## 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:

```markdown
# ❌ 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:

```markdown
# ❌ 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:
```bash
# 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

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

# @type=string @optional
LINEAR_DEFAULT_INITIATIVE_ID=
```

#### Safe Commands (Always Use)

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

#### Unsafe Commands (NEVER Use)

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

#### Document in SKILL.md

```markdown
## 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

```bash
# 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

```typescript
// 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

```typescript
// 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:
```bash
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` |

```bash
# 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:
```bash
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:

```bash
# 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**:
```markdown
## [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).

```bash
# 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.

```bash
# 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:

```bash
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

```bash
# 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:

```bash
# ❌ 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

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

---

## Common Mistakes

### Mistake 1: Hardcoded Project References

❌ **Bad:**
```typescript
const result = await createSkillsmithProject({...})
await linkToSkillsmithInitiative(projectId)
```

✅ **Good:**
```typescript
const result = await createProject(teamId, {..., initiative: initiativeId})
await linkProjectToInitiative(projectId, initiativeId)
```

### Mistake 2: Missing Environment Variable Validation

❌ **Bad:**
```typescript
const apiKey = process.env.API_KEY  // Silently undefined
```

✅ **Good:**
```typescript
const apiKey = process.env.API_KEY
if (!apiKey) {
  throw new Error('API_KEY environment variable is required')
}
```

### Mistake 3: Project-Specific Examples

❌ **Bad:**
```markdown
## Example
Link the Skillsmith Phase 5 project to the initiative.
```

✅ **Good:**
```markdown
## 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](https://github.com/wrsmith108)
- **Source:** [wrsmith108/skill-builder-claude-skill](https://github.com/wrsmith108/skill-builder-claude-skill)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-wrsmith108-skill-builder-claude-skill-skill-reviewer
- Seller: https://agentstack.voostack.com/s/wrsmith108
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.