References

Skill Audit Rules

Inherits: All rules from rules-universal.md Execution Required: Execute each check table below. Verify directory structure, frontmatter, scripts, and references.

Table of Contents

• Overview
• Skill Directory Validation
• SKILL.md Validation
• Scripts Audit
• References Audit
• Design Principles
• Common Issues

Overview

A skill is any directory containing a SKILL.md file.

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter: name, description (required)
│   └── Markdown body: instructions (required)
├── scripts/      - Executable code (runtime, NO size limit)
├── references/   - Documentation (on-demand, no official limit)
├── assets/       - Output resources (not loaded)
└── [custom]/     - Any other directories

CRITICAL: Audit ALL files in skill directory by their type.

Skill Directory Validation

Full Directory Audit

Audit ALL files in skill directory by type. Report: "Total files: N, Audited: N"

SKILL.md Validation

Frontmatter

Description Quality

Good pattern:

description: This skill should be used when the user asks to "specific phrase", "another phrase", mentions "keyword", or discusses topic-area.

Must include:

• Specific trigger phrases
• Keywords that indicate relevance
• Topic areas covered

Should NOT include:

• Implementation details
• Technical specifications
• Information belonging in body

Body Validation

When body too long, check in order:

1. Contains explanations AI knows? → Delete
2. Lengthy text vs concise examples? → Simplify
3. Repeated information? → Deduplicate
4. Excessive constraints for flexible tasks? → Simplify
5. Still too long? → Split to references/

Scripts Audit

IMPORTANT: Scripts are runtime-executed, NOT loaded into context. NO line count limits.

Script Integrity Verification

CRITICAL: For composite systems, verify script integrity with source code.

Step 1: Identify Script Locations

Step 2: Declaration vs Reality Check

Function Merge Check (Critical):

• If declared script doesn't exist, read other scripts' source code
• Check if declared function is implemented elsewhere
• Result: Not a missing issue if merged (document update needed)

Step 3: Script Type Classification

Step 4: Description Consistency

Step 5: Dependency Verification

Shell Scripts

#!/bin/bash
set -euo pipefail  # Required

# Error handling
trap 'echo "Error on line $LINENO"' ERR

# Main logic

Python Scripts

#!/usr/bin/env python3
"""Script description."""

import sys

def main():
    try:
        # Main logic
        pass
    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

Script Should NOT Check

• File length/line count (NO limit)
• TOC requirement (not needed for code)
• Style preferences (design choice)

References Audit

Purpose: Documentation loaded on-demand

Official guidance: "Keep individual reference files focused. Agents load these on demand, so smaller files mean less use of context." — No official line limit.

Size Evaluation (Content-Based)

No hardcoded limit. Evaluate based on content nature:

Requirements

"When to Read" Pattern

Good:

## Reference Files

Read `references/api-spec.md` when:
- User asks about API endpoints
- Generating API-related code

Read `references/error-codes.md` when:
- Encountering error codes
- User reports specific errors

Bad:

See references/ for more information.

Design Principles

Universality & Portability

AI Executor Awareness

Full details: See methodology-core.md → AI Capability Model Full LLM checks: See rules-universal.md → LLM Prompting Best Practices Multi-phase checks: See type-prompt.md → Conversational/Multi-Phase Prompt Rules

When Hardcoding is Acceptable

Do NOT flag:

• License/copyright notices
• Brand names
• Technical specifications
• Code examples (syntax, not content)
• Regex for technical patterns

DO flag:

• User-facing messages
• Error messages shown to users
• Output templates with fixed language
• UI labels

Common Issues

Should Flag

Should NOT Flag