a-i--skills: Instructions file for GitHub Copilot

Coding Standards Instructions

Markdown-First Approach

Skills are primarily instructional content, not code. The SKILL.md file is the primary artifact.

Python Script Guidelines

When adding Python scripts to a skill's scripts/ directory:

Style

• Follow PEP 8 conventions
• Keep scripts focused and single-purpose
• Make scripts directly executable when appropriate
• Include docstrings for non-trivial functions

Dependencies

• Document dependencies in comments or a requirements.txt
• Keep dependencies minimal
• Don't assume global package installation

Example Structure

#!/usr/bin/env python3
"""
Brief description of what this script does.

Usage:
    python3 script_name.py [arguments]
"""

import sys
import os

def main():
    """Main entry point."""
    # Implementation
    pass

if __name__ == "__main__":
    main()

Testing

• Include simple smoke tests when appropriate
• Document test commands in SKILL.md
• Example: python3 scripts/my_script_test.py

Content Guidelines

Examples in SKILL.md

• Keep examples concise and actionable
• Use ASCII art/content unless the domain requires otherwise
• Show concrete input/output when helpful
• Demonstrate edge cases when relevant

Code Comments

• Don't over-comment obvious code
• Do comment non-obvious decisions or algorithms
• Explain "why" not "what" when code is clear

File Organization

Within a Skill Directory

my-skill/
  SKILL.md              # Required: instructions
  scripts/
    helper.py           # Executable helpers
    requirements.txt    # Python dependencies
  references/
    documentation.md    # Supporting docs
    examples/           # Example files
  assets/
    template.txt        # Templates
    config.json         # Configuration

Naming Conventions

• Directories: lowercase, hyphen-separated
• Python files: lowercase, underscore-separated (snake_case)
• Markdown files: UPPERCASE or Title Case
• Config/data: lowercase with appropriate extension