Agent skill

lint-skill

Validate skill documents against PMC skill design principles. Checks format ownership, composite skill structure, and internal consistency. CHECKS: 1. FORMAT OWNERSHIP - kb skill owns all format templates (kb/references/) 2. COMPOSITE STRUCTURE - Steps must have associated skills, stage announcements 3. INTERNAL CONSISTENCY - No gaps, broken references, or missing sections Use when: - Creating new skills - Reviewing existing skills - Periodic skill maintenance - User says "lint skills", "check skills", "validate skills"

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/lint-skill-jayprimer-pmc-marketplace

SKILL.md

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:

    yaml
    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:

    markdown
    ## Step N: STEP_NAME

**Skill:** `/pmc:skill-name`

    Or for multiple skills:

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

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

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

Check Type Description
Broken skill references ERROR /pmc:nonexistent referenced
Broken file references ERROR Links to non-existent files
Missing Prerequisites section WARNING Should reference /pmc:kb
Undefined placeholders ERROR {placeholder} or TBD in content
Inconsistent naming WARNING Skill name in frontmatter vs filename
Missing "Use when" section WARNING Frontmatter should have triggers
Empty sections WARNING Headers with no content

Validation Procedure

Step 1: Identify Skills to Check

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

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

Type Characteristics Example
Atomic Single responsibility, no skill delegation kb, reflect, complete
Composite Orchestrates other skills, has steps dev, workflow
Validation Checks/verifies artifacts lint-kb, plan-validation, ticket-status
Reference Manages templates/formats kb (format ownership)

Step 3: Run Checks Per Type

For All Skills

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

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

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

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

    bash
    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:
    markdown
    **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

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

markdown
---
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 ===

Didn't find tool you were looking for?

Be as detailed as possible for better results