Copilot Coding Agent Instructions

Copilot Coding Agent Instructions

Trust these instructions first. Only perform additional exploration if information is incomplete or found to be in error.

Repository Overview

This repository is a Claude Code Marketplace Plugin Collection containing 22+ plugins that extend Claude's capabilities with specialized skills, commands, and agents. The plugins cover Python development, code quality, Git/CI-CD, AI/LLM tools, documentation, and agent orchestration.

Project Type: Plugin marketplace for Claude Code CLI Languages: Markdown (primary for skills/commands/agents), Python 3.11+ (scripts) Package Manager: uv (Astral's extremely fast Python package manager) Python Version: 3.11+ required

Directory Structure

claude_skills/
├── .claude/                  # Claude Code local config (symlinked skills/commands/agents)
│   ├── agents/               # Agent markdown files
│   ├── commands/             # Command markdown files
│   └── skills/               # Skill directories (symlinks to plugins/)
├── .claude-plugin/           # Repository-level marketplace config
│   └── marketplace.json      # Plugin registry manifest
├── plugins/                  # All 22 plugins live here
│   └── {plugin-name}/
│       ├── .claude-plugin/
│       │   └── plugin.json   # Plugin manifest
│       ├── skills/           # Skill directories (SKILL.md + references/)
│       ├── commands/         # Command markdown files (optional)
│       ├── agents/           # Agent markdown files (optional)
│       └── README.md
├── sessions/                 # cc-sessions framework (task management)
├── scripts/                  # Utility scripts
├── marketplace.json          # Local marketplace config (in .claude-plugin/)
├── pyproject.toml            # Python project config (linting, type checking)
├── .pre-commit-config.yaml   # Pre-commit/prek hooks config
└── CLAUDE.md                 # AI-facing project instructions

Build and Development Commands

Environment Setup (Required First)

Always run these commands before any other operations:

# Install Python dependencies and create virtual environment
uv sync

# This creates .venv/ and installs all dependencies from pyproject.toml
# Must complete successfully before running any uv run commands

Testing Plugins Locally

To test plugins during development:

# Option 1: Load specific plugins for this session
claude --plugin-dir ./plugins/python3-development --plugin-dir ./plugins/holistic-linting

# Option 2: Add local marketplace for persistent enable/disable
/plugin marketplace add ./.claude-plugin/marketplace.json

# Install plugins you need (--scope local keeps it gitignored)
/plugin install python3-development@jamie-bitflight-skills --scope local

# Disable when not needed
/plugin disable python3-development@jamie-bitflight-skills

# Re-enable when needed
/plugin enable python3-development@jamie-bitflight-skills

Linting and Formatting

Always run linting before committing changes:

# Run ruff linter with auto-fix on specific files
uv run ruff check --fix path/to/file.py

# Run ruff formatter
uv run ruff format path/to/file.py

# Run ty type checking
uv run ty check path/to/file.py

# Run pre-commit hooks on specific files (preferred method)
uv run prek run --files path/to/file.py

# Run all pre-commit hooks on all files (slow, use sparingly)
uv run prek run --all-files

Important Notes:

• The repository uses prek (Rust-based pre-commit replacement), not pre-commit
• Some hooks may fail on first run due to network requirements (shellcheck-py)
• Run individual hooks when full pre-commit fails: uv run prek run ruff --files <file>

Pre-commit Hook List

The following hooks run on commit:

Plugin Structure

Each plugin must contain:

plugins/{plugin-name}/
├── .claude-plugin/
│   └── plugin.json           # Required: plugin manifest
├── skills/
│   └── {skill-name}/
│       ├── SKILL.md          # Required: skill definition with YAML frontmatter
│       └── references/       # Optional: reference documentation
├── commands/                 # Optional: slash command definitions (.md files)
├── agents/                   # Optional: agent definitions (.md files)
└── README.md                 # Optional: user-facing documentation

plugin.json Schema

{
  "name": "plugin-name",
  "description": "Description with ACTION->TRIGGER->OUTCOME format",
  "version": "1.0.0",
  "skills": ["./skills/skill-name"],
  "commands": ["./commands"],
  "agents": ["./agents"]
}

SKILL.md Format

Skills require YAML frontmatter:

---
name: skill-name
description: Description with trigger conditions
---

# Skill Title

Content with rules, examples, and references...

Coding Standards

Python Files

• Target Python 3.11+
• Use from __future__ import annotations in all files
• Follow Google docstring convention
• Type hints required for all public functions
• Max line length: 120 characters
• Use native generics (list[str] not List[str])

Markdown Files

• Skills are AI-facing documentation, NOT user documentation
• Use imperative language ("The model MUST...")
• Include XML tags for structured sections
• Cite all sources with URLs and access dates
• Use relative paths with ./ prefix for file references

Commit Messages

Use Conventional Commits format:

type(scope): description

Types: feat, fix, docs, style, refactor, test, chore
Scope: skill name or component

Known Issues and Workarounds

Pre-commit Network Failures

Some hooks require network access and may fail in restricted environments:

# If full pre-commit fails, run individual hooks
uv run prek run ruff ruff-format markdownlint-cli2 --files <changed-files>

Ruff Format Trailing Comma

The project uses skip-magic-trailing-comma = true. Ruff may report files as needing reformatting for trailing comma differences. Run uv run ruff format <file> to fix.

EXE003 Shebang Warning

Scripts using uv run --script shebang pattern trigger EXE003. This is intentionally ignored in pyproject.toml.

Validation Checklist

Before submitting changes:

1. Run uv sync if dependencies changed
2. Run uv run ruff check --fix and uv run ruff format on Python files
3. Run uv run ty check on Python files
4. Verify plugin structure: /plugin validate ./plugins/plugin-name
5. Check markdown links are relative with ./ prefix
6. Ensure SKILL.md has valid YAML frontmatter
7. Use Conventional Commits format for commit messages

File Locations Quick Reference

Critical Reminders

• Skills are AI-facing documentation written for Claude, not humans
• Always use uv run prefix for Python commands
• Test new plugins with claude --plugin-dir ./plugins/plugin-name
• Paths in skills use ./ relative prefix
• CI runs via .github/workflows/code-quality.yml with quality gate pattern
• Environment setup for coding agent defined in .github/workflows/copilot-setup-steps.yml