Lint Skill Documents

Lint Skill Documents

Validate skill documents against PMC skill design principles.

Prerequisites

ALWAYS run /​pmc:kb first to understand KB structure and skill organization.

Default Scope

By default, lint-skill checks all skills in the same directory as itself:

.pmc/​marketplace/​plugins/​pmc/​skills/
├── lint-skill/    <- this skill
├── dev/           <- checked
├── kb/            <- checked
├── plan/          <- checked
└── ...            <- all siblings checked

Override scope:

• /​pmc:lint-skill skill-name - Check single skill
• /​pmc:lint-skill path/​to/​skills/ - Check different directory

---

Skill Design Principles

Principle 1: Format Ownership

KB skill owns all format templates.

• All format templates live in kb/​references/​*.md
• Other skills reference formats, never define them
• Directory structure defined in kb/​references/​directory-structure.md

Check:

• Skill defines document formats? → ERROR (move to kb/​references/)
• Skill duplicates format info from kb? → WARNING (reference instead)

Principle 2: Composite Skill Structure

Composite skills (orchestrators) follow strict patterns.

A composite skill:

• Coordinates multiple other skills in sequence
• Each step has explicit skill association
• Declares stage transitions during execution

Required Elements:

1. Frontmatter WORKFLOW - Lists all steps with associated skills:

   WORKFLOW:
   1. STEP_NAME - /​pmc:skill-name (brief description)
   2. STEP_NAME - /​pmc:skill-a + /​pmc:skill-b
   

2. Stage Announcements - Documents how to announce transitions:

   === ENTERING STEP_NAME ===
   [... work ...]
   

3. Step-Skill Mapping - Every step must have at least one skill:

   ## Step N: STEP_NAME
   
   **Skill:** `/​pmc:skill-name`
   

   Or for multiple skills:

   **Skills:**
   - `/​pmc:skill-a` → purpose
   - `/​pmc:skill-b` → purpose
   

4. Skill Reference Table - Summary of all step-skill mappings:

   | Step | Skill | Purpose |
   |------|-------|---------|
   | 1. STEP | `/​pmc:skill` | What it does |
   

Check:

• Step without associated skill? → ERROR (create or assign skill)
• Missing stage announcement pattern? → ERROR
• Missing skill reference table? → WARNING

Principle 3: Internal Consistency

Skills must be internally consistent and complete.

Checks:

---

Validation Procedure

Step 1: Identify Skills to Check

Default: All sibling skills in same directory as lint-skill.

# Default scope (sibling skills)
ls .pmc/​marketplace/​plugins/​pmc/​skills/​*/​SKILL.md

# Single skill
ls .pmc/​marketplace/​plugins/​pmc/​skills/​{skill-name}/​SKILL.md

# Recently modified only
git diff --name-only HEAD~5 -- .pmc/​marketplace/​plugins/​pmc/​skills/

Step 2: Classify Each Skill

Step 3: Run Checks Per Type

For All Skills

## Basic Checks

- [ ] Frontmatter has `name` and `description`
- [ ] Description has `Use when:` triggers
- [ ] Has Prerequisites section referencing /​pmc:kb
- [ ] No TBD/​TODO/​placeholder markers
- [ ] All `/​pmc:skill` references exist
- [ ] All file path references exist
- [ ] Skill name matches directory name

For Composite Skills (Additional)

## Composite Skill Checks

- [ ] WORKFLOW in frontmatter lists all steps
- [ ] Each step has associated skill(s)
- [ ] Stage announcement pattern documented
- [ ] Skill Reference Table exists
- [ ] All referenced skills exist
- [ ] No orphan steps (step without skill)
- [ ] No orphan skills (skill without step)

For Format/​Reference Skills

## Format Ownership Checks

- [ ] Format templates in kb/​references/ only
- [ ] Other skills reference, not duplicate
- [ ] Directory structure in directory-structure.md
- [ ] No format definitions outside kb/​references/

Step 4: Report Issues

# Skill Lint Report

## Summary

| Skill | Type | Errors | Warnings |
|-------|------|--------|----------|
| dev | composite | 0 | 1 |
| plan | atomic | 1 | 0 |

## Issues

### plan (ERRORS: 1)

| Severity | Check | Issue |
|----------|-------|-------|
| ERROR | broken-reference | `/​pmc:nonexistent` not found (line 45) |

### dev (WARNINGS: 1)

| Severity | Check | Issue |
|----------|-------|-------|
| WARNING | empty-section | "## Advanced Usage" has no content |

---

Fixing Common Issues

Missing Skill for Step

If a composite skill step has no associated skill:

1. Option A: Create new skill

   mkdir .pmc/​marketplace/​plugins/​pmc/​skills/​{new-skill}
   # Create SKILL.md with atomic skill template
   

2. Option B: Assign existing skill

   • Find skill that covers this functionality
   • Update step to reference it

3. Option C: Merge into adjacent step

   • If step is trivial, combine with related step

Format Definition Outside kb

If skill defines formats that should be in kb/​references/:

1. Extract format to kb/​references/​{format}-format.md
2. Replace inline definition with reference:

   **Format:** See [kb/​references/​{format}-format.md](../​kb/​references/​{format}-format.md)
   

Broken Skill Reference

If /​pmc:skill doesn't exist:

1. Check for typo in skill name
2. Check if skill was renamed/​removed
3. Create missing skill if needed
4. Update reference to correct skill

---

Skill Templates

Atomic Skill Template

---
name: {skill-name}
description: |
  {One-line summary of what this skill does.}

  {2-3 lines of detail about the skill's purpose.}

  Use when:
  - {trigger condition 1}
  - {trigger condition 2}
---

# {Skill Title}

{Brief description.}

## Prerequisites

**ALWAYS run /​pmc:kb first** to understand KB structure.

## When to Use

**Use when:**
- {condition}

**Skip when:**
- {condition}

---

## Procedure

### Step 1: {Name}

{Instructions}

### Step 2: {Name}

{Instructions}

---

## Checklist

- [ ] {Item 1}
- [ ] {Item 2}

Composite Skill Template

---
name: {skill-name}
description: |
  {One-line summary - orchestrates X workflow.}
  Coordinates skills in sequence: a → b → c.

  WORKFLOW:
  1. STEP_A - /​pmc:skill-a (description)
  2. STEP_B - /​pmc:skill-b + /​pmc:skill-c
  3. STEP_C - /​pmc:skill-d (description)

  Use when:
  - {trigger condition 1}
  - {trigger condition 2}
---

# {Workflow Title}

{Brief description of the workflow.}

## Prerequisites

**ALWAYS run /​pmc:kb first** to understand KB structure.

## State Announcements

**ALWAYS announce stage transitions:**

=== ENTERING STEP_A === [... work ...]

=== ENTERING STEP_B === [... work ...]

## Workflow Overview

{ASCII diagram showing flow}

---

## Step 1: STEP_A

**Skill:** `/​pmc:skill-a`

{What this step does and when to proceed.}

---

## Step 2: STEP_B

**Skills:**
- `/​pmc:skill-b` → {purpose}
- `/​pmc:skill-c` → {purpose}

{Instructions for this step.}

---

## Skill Reference

| Step | Skill | Purpose |
|------|-------|---------|
| 1. STEP_A | `/​pmc:skill-a` | {purpose} |
| 2. STEP_B | `/​pmc:skill-b` | {purpose} |
| 2. STEP_B | `/​pmc:skill-c` | {purpose} |
| 3. STEP_C | `/​pmc:skill-d` | {purpose} |

---

Checklist

Basic Validation

• All skills have frontmatter with name/​description
• All skills have "Use when" triggers
• All skills reference /​pmc:kb in prerequisites
• No TBD/​TODO markers
• All skill references valid
• All file references valid

Composite Skills

• WORKFLOW in frontmatter
• Every step has skill(s)
• Stage announcements documented
• Skill Reference Table exists
• No orphan steps or skills

Format Ownership

• All formats in kb/​references/
• No format duplication across skills
• Other skills reference kb formats

---

Example Report

=== LINT SKILL REPORT ===

Checked: 15 skills
Errors: 2
Warnings: 4

## ERRORS

### plan/​SKILL.md
- LINE 156: Broken reference `/​pmc:nonexistent` - skill does not exist

### workflow/​SKILL.md
- LINE 45: Step "3. EXECUTE" has no associated skill

## WARNINGS

### dev/​SKILL.md
- Missing Skill Reference Table (composite skill should have one)

### test/​SKILL.md
- Empty section "## Advanced Usage"

### reflect/​SKILL.md
- No "Use when" in frontmatter description

### validate/​SKILL.md
- Placeholder found: "{TBD}" at line 89

=== END REPORT ===