# Skills First Workflow

> Use when entering any repository, creating a new repository, or performing repository migration. Automatically enforces prerequisite skill loading and verification before any implementation begins.

- Skill: `mcj-coder/skills-first-workflow` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add mcj-coder/skills-first-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mcj-coder/skills-first-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: mcj-coder (https://skillmd.com/u/mcj-coder)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/mcj-coder/skills-first-workflow

---


# Skills-First-Workflow

## Overview

Enforce that all work follows a skills-first approach: prerequisite skill
libraries must be installed, bootstrapped, and loaded before any implementation
begins. Performs runtime verification and automatically fixes missing prerequisites.

**CRITICAL**: Load this skill FIRST when entering any repository.

## When to Use

**Entering a repository:**

- First action in any repository
- Beginning any task or work session
- Default behaviour for all repository work

**Creating a repository:**

- Initializing a new repository
- Scaffolding a new project
- Setting up repo structure

**Migrating a repository:**

- Adding skills-first workflow to existing repo
- Updating repository to enforce prerequisite loading
- Establishing skills-first practices

## Core Workflow

1. **Announce** the skill and confirm Superpowers availability.
2. **Verify prerequisites** (runs automatically with AutoFix):
   - Superpowers installed and bootstrapped
   - `superpowers:using-superpowers` loaded
   - AGENTS.md exists and references skills-first-workflow
   - Task-relevant process skills loaded
3. **Initialize or migrate** repository if needed:
   - Greenfield: Create AGENTS.md and README.md
   - Brownfield: Create AGENTS.md on feature branch
4. **Enforce process skills before implementation**:
   - Use `process-skill-router` to select the correct skill based on context
   - Process skills have precondition guards - check these before proceeding
   - Brainstorming (for unclear requirements/new features)
   - Planning (for multi-step tasks)
   - TDD (for code changes)
   - Verification (always before claiming complete)
5. **Block implementation** until all verifications pass.

## Runtime Verification

### Prerequisites Checked

**AutoFix mechanism**: When verification fails, AutoFix reads prerequisite
repository URLs from AGENTS.md, fetches installation instructions from source
repositories, and executes per the agent's default installation mechanism. If
AutoFix cannot complete automatically, it halts and provides manual instructions.

1. **Superpowers available** → AutoFix: Install and bootstrap if not
2. **using-superpowers loaded** → AutoFix: Load if not
3. **AGENTS.md exists** → AutoFix: Create/update if not
4. **Task skills loaded** → AutoFix: Load required skills if not

**Verification must pass before any implementation work begins.**

See `references/AUTOFIX.md` for detailed AutoFix procedures and examples.

## Repository Initialization

### Greenfield

When creating a new repository:

1. Create AGENTS.md with skills-first directives
2. Create README.md with Work Items section
3. Verify initialization complete
4. Commit as part of repository setup

See `references/AGENTS-TEMPLATE.md` for AGENTS.md content.

### Brownfield

When migrating existing repository:

1. Create feature branch: `feat/add-skills-first-workflow`
2. Create AGENTS.md with skills-first directives
3. Update README.md if needed (add Work Items section)
4. Commit with evidence
5. Create PR if required

See `references/AGENTS-TEMPLATE.md` for AGENTS.md content.

## Strict Enforcement Rules

### Before Implementation

**All verifications must pass:**

- Superpowers available
- `using-superpowers` loaded
- AGENTS.md exists and current
- Task-relevant skills loaded

**Only then can implementation begin.**

### Process Skills Required

**Use `process-skill-router` when uncertain which skill applies.** The router evaluates
context and recommends the correct skill based on priority order.

**Precondition guards:** Process skills have precondition checks that must pass before
proceeding. If a precondition fails, the skill will redirect to the correct alternative.
For example, `requirements-gathering` checks that no ticket exists before proceeding.

**For no ticket exists (new work):**

- Load and apply `requirements-gathering` first to create a ticket

**For unclear requirements or new features:**

- Load and apply `superpowers:brainstorming` first

**For multi-step tasks:**

- Load and apply `superpowers:writing-plans` first

**For code changes:**

- Load and apply `superpowers:test-driven-development` first
- Write failing tests before implementation

**For all tasks:**

- Load and apply `superpowers:verification-before-completion`
- Verify before claiming complete

### No Exceptions

**User requests to skip:**

- Explain cannot skip skills-first workflow
- Offer to streamline if skills already loaded
- Proceed with verification anyway

**Simple changes (typos, formatting):**

- Still verify skills loaded (fast if already met)
- Enforcement applies to all changes

**Emergency hotfix:**

- Skills-first still applies
- Minimal skill set acceptable (TDD + verification)
- Cannot skip verification entirely

## Composition

**This skill does NOT create rigid dependencies:**

- Other skills do not declare this as prerequisite
- Loaded first by convention (via AGENTS.md reference)
- Skills remain composable and independent

**Verification responsibilities:**

- Verifies `using-superpowers` loaded
- Verifies AGENTS.md references skills-first-workflow
- Other skills loaded based on task requirements

## Evidence Requirements

**Greenfield:**

- [ ] AGENTS.md created with skills-first directives and prerequisite repo URLs
- [ ] README.md created with Work Items section
- [ ] Both files committed as part of initialization

**Brownfield:**

- [ ] Feature branch created
- [ ] AGENTS.md created/updated with skills-first directives and prerequisite repo URLs
- [ ] Changes committed with evidence
- [ ] PR created if required

**Every Task:**

- [ ] Verification passed: Superpowers available
- [ ] Verification passed: using-superpowers loaded
- [ ] Verification passed: AGENTS.md exists and current
- [ ] Verification passed: Task-relevant skills loaded
- [ ] Process skills applied before implementation

## Quick Reference

| Scenario            | Action                              | Result                            |
| ------------------- | ----------------------------------- | --------------------------------- |
| New repo            | Load skill → AutoFix creates files  | AGENTS.md + README.md initialized |
| Existing repo       | Load skill → AutoFix on branch      | AGENTS.md created via PR          |
| Missing Superpowers | AutoFix installs                    | Superpowers bootstrapped          |
| Missing skills      | AutoFix loads                       | Required skills loaded            |
| Skip request        | Explain + proceed with verification | Enforcement maintained            |

## Red Flags - STOP

- "Just skip the skills and implement quickly."
- "We don't need AGENTS.md for this repo."
- "I'll load skills after I start coding."
- "Tests can come later, implement first."
- "Verification is optional for small changes."

## Success Criteria

**Prerequisites met:**

- Superpowers installed and bootstrapped
- `using-superpowers` loaded
- AGENTS.md exists and references skills-first-workflow

**Process followed:**

- Process skills loaded before implementation
- TDD applied for code changes
- Verification applied before claiming complete

**No shortcuts:**

- Implementation did not begin before skills loaded
- Tests written before implementation code
- Verification completed before claiming done

**AutoFix worked:**

- Missing prerequisites automatically installed
- Missing AGENTS.md automatically created
- No manual intervention required for standard cases

## References

- `references/AGENTS-TEMPLATE.md` - Template for creating AGENTS.md
- `references/AUTOFIX.md` - Detailed AutoFix behaviour for each verification check
- `process-skill-router` - Route to correct process skill based on context
- `requirements-gathering` - Example of precondition guard pattern

## Prerequisite Validation Script

Use this script to verify all prerequisites are met:

```bash
#!/bin/bash
# validate-skills-first.sh

ERRORS=0
WARNINGS=0

echo "=== Skills-First Workflow Validation ==="
echo ""

# Check 1: Superpowers installed
echo "1. Checking Superpowers installation..."
if [ -d "$HOME/.claude/plugins/cache/superpowers-marketplace" ]; then
  echo "   ✓ Superpowers plugin directory exists"
else
  echo "   ✗ Superpowers not installed"
  echo "   Fix: Run 'npm install -g @anthropic/superpowers' or install via Claude settings"
  ((ERRORS++))
fi

# Check 2: AGENTS.md exists
echo ""
echo "2. Checking AGENTS.md..."
if [ -f "AGENTS.md" ]; then
  echo "   ✓ AGENTS.md exists"

  # Check for skills-first reference
  if grep -q "skills-first-workflow" AGENTS.md; then
    echo "   ✓ References skills-first-workflow"
  else
    echo "   ⚠ Does not reference skills-first-workflow"
    ((WARNINGS++))
  fi

  # Check for prerequisite URLs
  if grep -q "github.com" AGENTS.md; then
    echo "   ✓ Contains prerequisite repository URLs"
  else
    echo "   ⚠ No prerequisite repository URLs found"
    ((WARNINGS++))
  fi
else
  echo "   ✗ AGENTS.md not found"
  echo "   Fix: Create AGENTS.md from template"
  ((ERRORS++))
fi

# Check 3: README.md exists
echo ""
echo "3. Checking README.md..."
if [ -f "README.md" ]; then
  echo "   ✓ README.md exists"
else
  echo "   ✗ README.md not found"
  ((ERRORS++))
fi

# Check 4: Git repository
echo ""
echo "4. Checking git repository..."
if git rev-parse --git-dir > /dev/null 2>&1; then
  echo "   ✓ Git repository initialized"

  # Check for remote
  if git remote get-url origin > /dev/null 2>&1; then
    echo "   ✓ Remote 'origin' configured"
  else
    echo "   ⚠ No remote configured"
    ((WARNINGS++))
  fi
else
  echo "   ✗ Not a git repository"
  ((ERRORS++))
fi

# Summary
echo ""
echo "=== Summary ==="
echo "Errors: $ERRORS"
echo "Warnings: $WARNINGS"

if [ $ERRORS -eq 0 ]; then
  echo ""
  echo "✓ All prerequisites met - ready for skills-first workflow"
  exit 0
else
  echo ""
  echo "✗ $ERRORS prerequisite(s) not met"
  echo "Run AutoFix or manually resolve before proceeding"
  exit 1
fi
```

## Sample Verification Commands

### Check Superpowers Status

```bash
# Check if Superpowers CLI is available
superpowers --version

# Check plugin installation location
ls -la ~/.claude/plugins/cache/superpowers-marketplace/

# Verify using-superpowers skill exists
ls ~/.claude/plugins/cache/superpowers-marketplace/superpowers/*/skills/using-superpowers/
```

### Check Repository Prerequisites

```bash
# Verify AGENTS.md content
cat AGENTS.md | head -50

# Check for required sections
grep -E "^#|skills-first" AGENTS.md

# Verify README.md exists and has content
wc -l README.md
```

### Validate Skill Loading

```bash
# In Claude Code, verify skills loaded
# These commands show skill status in conversation

# Check if using-superpowers is active
# (Look for skill announcement in conversation)

# Verify process skills available
# (Use /skills command in Claude Code)
```

## AutoFix Command Examples

When validation fails, AutoFix performs these actions:

### Missing AGENTS.md

```bash
# AutoFix creates AGENTS.md from template
cat > AGENTS.md << 'EOF'
# AGENTS.md - Skills-First Workflow

## Required Reading

Before ANY work in this repository, load: `development-skills:skills-first-workflow`

## Prerequisites

- Superpowers: https://github.com/anthropics/superpowers
- Development Skills: https://github.com/org/development-skills

## Process Skills

1. **requirements-gathering** - Before creating tickets
2. **brainstorming** - For unclear requirements
3. **writing-plans** - For multi-step tasks
4. **test-driven-development** - For code changes
5. **verification-before-completion** - Before claiming done
EOF

git add AGENTS.md
git commit -m "docs: add AGENTS.md for skills-first workflow"
```

### Missing Superpowers

```bash
# AutoFix installs Superpowers
# (Actual command depends on environment)

# For Claude Code:
# Settings > Extensions > Install Superpowers

# For CLI:
npm install -g @anthropic/superpowers
superpowers bootstrap
```

## Evidence Checklist

Before proceeding with any task, verify:

- [ ] `validate-skills-first.sh` exits with code 0
- [ ] Superpowers plugin directory exists
- [ ] AGENTS.md contains skills-first-workflow reference
- [ ] README.md exists
- [ ] Git repository initialized with remote

```bash
# One-liner verification
./validate-skills-first.sh && echo "Ready to proceed"
```