{"id":36937728,"url":"https://github.com/canonical/copilot-collections","last_synced_at":"2026-02-06T22:03:32.540Z","repository":{"id":326273487,"uuid":"1104185839","full_name":"canonical/copilot-collections","owner":"canonical","description":"Instructions, prompts, and configurations to help you make the most of GitHub Copilot.","archived":false,"fork":false,"pushed_at":"2026-01-12T21:21:17.000Z","size":110,"stargazers_count":6,"open_issues_count":4,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-13T01:47:28.046Z","etag":null,"topics":["platform-engineering"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/canonical.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-25T21:53:02.000Z","updated_at":"2026-01-05T20:37:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/canonical/copilot-collections","commit_stats":null,"previous_names":["canonical/copilot-collections"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/canonical/copilot-collections","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canonical%2Fcopilot-collections","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canonical%2Fcopilot-collections/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canonical%2Fcopilot-collections/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canonical%2Fcopilot-collections/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/canonical","download_url":"https://codeload.github.com/canonical/copilot-collections/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canonical%2Fcopilot-collections/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28380803,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T10:00:56.084Z","status":"ssl_error","status_checked_at":"2026-01-13T09:45:11.986Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["platform-engineering"],"created_at":"2026-01-13T10:10:05.291Z","updated_at":"2026-02-06T22:03:32.533Z","avatar_url":"https://github.com/canonical.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\n  ~ Copyright 2026 Canonical Ltd.\n  ~ See LICENSE file for licensing details.\n--\u003e\n\n# **Canonical Copilot Collections**\n\n**Centralized context management for GitHub Copilot across the Canonical ecosystem.**\n\nThis repository acts as a \"Toolkit\" to distribute standardized Copilot Custom Instructions, Prompts, Agents and Skills. It allows individual repositories to \"subscribe\" to specific sets of assets (e.g., Python standards, Juju/Ops Framework patterns) and keep them synchronized automatically.\n\n## **What are Collections?**\n\nA **Collection** is a logical group of markdown files (instructions, prompts, agents, and skills) defined in `collections.yaml.`\n\nInstead of copying specific instructions into 50 different repositories manually, the consuming repository defines a configuration file listing the collections it needs.\n\n**Available Collections (Examples):**\n\n* common-python: Standard Python coding style.  \n* common-documentation: Documentation standards with review skill.\n* charm-python: Includes common-python + Juju Ops Framework specifics.  \n* pfe-charms: Platform Engineering specific collection.\n\n## **Usage: Adding to a Repository**\n\nTo add Copilot collections to your repository, follow these three steps.\n\n**Note:** These steps assume that if the `yq` tool is already installed, it was installed via snap not via apt. The install scripts rely on behavior from the snap version of `yq`. The apt offering of `yq` doesn't have the behavior the scripts expect, and will fail. If `yq` is not installed, the script will automatically install it via snap.\n\n### **1. Create the Configuration**\n\nCreate a file named `.copilot-collections.yaml` in the `.github` folder of your repository (recommended) or in the repository root.\n\n```yaml\ncopilot:\n  # The version of the toolkit to use (matches a Release Tag in this repo)\n  version: \"v1.0.0\"\n\n  # The collections you want to install\n  collections:\n    - charm-python\n    - pfe-charms\n```\n\n**Location Preference:** The workflow and sync script will search for the config file in this order:\n1. `.github/.copilot-collections.yaml` (recommended)\n2. `.copilot-collections.yaml` (root, for backwards compatibility)\n\nYou can also specify a custom location - see below for details.\n\n### **2. Run the Initial Sync (Local)**\n\nYou can sync the instructions immediately to your local machine to verify them.\n\n```bash\ncurl -sL https://raw.githubusercontent.com/canonical/copilot-collections/main/scripts/local_sync.sh | bash\n```\n\nTo specify a custom config file location:\n```bash\n# Via command-line argument\ncurl -sL https://raw.githubusercontent.com/canonical/copilot-collections/main/scripts/local_sync.sh | bash -s -- custom/path/.copilot-collections.yaml\n\n# Via environment variable\nCOPILOT_CONFIG_FILE=\"custom/path/.copilot-collections.yaml\" curl -sL https://raw.githubusercontent.com/canonical/copilot-collections/main/scripts/local_sync.sh | bash\n```\n\n**Note:** This will generate files in .github/instructions/, .github/prompts/, and .github/skills/. Do not edit these files manually; they will be overwritten.\n\n### **3. Configure Auto-Updates (CI)**\n\nTo ensure your repo stays up to date when the Toolkit releases new versions, add this workflow.\n\n**File:** `.github/workflows/copilot-collections-update.yml`\n\n```yaml\nname: Auto-Update Copilot Instructions\non:\n  schedule:\n    - cron: '0 9 * * 1' # Run every Monday at 09:00 UTC\n  workflow_dispatch:\n\njobs:\n  check-update:\n    # Always pin to @main to get the latest logic, but the content version is controlled by your .yaml file\n    uses: canonical/copilot-collections/.github/workflows/auto_update_collections.yaml@main\n    secrets: inherit\n    # Optionally specify a custom config file location:\n    # with:\n    #   config_file: \"custom/path/.copilot-collections.yaml\"\n```\n\n## **Inspiration \u0026 Credits**\n\nSome prompts and instruction patterns in this collection were inspired by the [Awesome GitHub Copilot](https://github.com/github/awesome-copilot) repository.\n\nWe highly encourage you to explore it for further inspiration, including advanced chat modes, persona definitions, and framework-specific prompts that you might want to adapt for your specific projects.\n\n## **Maintaining**\n\n### **Directory Structure**\n\n* assets/: Raw markdown files (Core assets).\n  * instructions/: Custom instruction files.\n  * prompts/: Prompt files.\n  * agents/: Agent files.\n  * skills/: Agent skill directories (each containing SKILL.md).\n* collections.yaml: Core definitions.\n* groups/: Team specific collections.\n  * \u003cteam-name\u003e/: Folder for team assets.\n    * collections.yaml: Team specific definitions.\n* scripts/: Logic for syncing files.\n* .github/workflows/: Reusable workflows.\n\n### **How to add a new Instruction**\n\n1. **Add the file:** Create `assets/instructions/my-topic/my-new-instructions.md` (for core) or `groups/\u003cteam\u003e/instructions/...` (for teams).\n2. **Update Manifest:** Edit `collections.yaml` (core) or `groups/\u003cteam\u003e/collections.yaml`.\n   * Add it to an existing collection items list.\n   * OR create a new collection key if it represents a new logical group.\n3. **Release:**\n   * Open PR.\n   * Merge changes to main.\n   * Create a new GitHub Release (e.g., v1.1.0).\n   * *Consumer repos will pick this up automatically on their next scheduled run.*\n\n### **How to add a new Agent Skill**\n\n1. **Create the directory:** Create `assets/skills/\u003cskill-name\u003e/` (for core) or `groups/\u003cteam\u003e/skills/\u003cskill-name\u003e/` (for teams).\n2. **Add SKILL.md:** Create the skill definition file with required YAML frontmatter:\n   ```markdown\n   ---\n   name: skill-name\n   description: What the skill does\n   ---\n   # Skill content here\n   ```\n3. **Update Manifest:** Edit `collections.yaml` and add to a collection's items:\n   ```yaml\n   - src: assets/skills/\u003cskill-name\u003e\n     dest: .github/skills/\u003cskill-name\u003e/\n   ```\n   **Important:** Skills are directories, so `dest` must end with `/`.\n4. **Validate:** Run `./scripts/validate_collections.sh .`\n5. **Release:** Follow the same release process as instructions.\n\n### **Group Collections**\n\nTeams can manage their own collections in `groups/\u003cteam-name\u003e/`.\n\n**Naming Convention:**\nCollection names are global. To avoid collisions, **prefix your collection names with your group name**.\n*   ✅ `pfe-charms`\n*   ❌ `charms` (Too generic)\n\n**Path Resolution:**\n*   **Relative Paths**: `src: instructions/guide.md` -\u003e Resolves to `groups/\u003cteam\u003e/instructions/guide.md`.\n*   **Root Paths**: `src: /assets/common/logo.png` -\u003e Resolves to `assets/common/logo.png` (Repository Root).\n\n### **Linting Markdown Files**\n\nThe repository includes a Markdown linter to ensure consistent formatting across all instruction, prompt, agent, and skill files.\n\n**Run the linter:**\n\n```bash\n# Lint all files\nmake lint-md\n\n# Lint specific directory\nmake lint-md SOURCEDIR=assets/agents\nmake lint-md SOURCEDIR=assets/instructions\n```\n\n**Requirements:** The linter uses `uv` and `pymarkdownlnt`. The Makefile automatically sets up a virtual environment and installs dependencies on first run.\n\n**Configuration:** Linting rules are defined in `.pymarkdown.json` at the repository root.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcanonical%2Fcopilot-collections","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcanonical%2Fcopilot-collections","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcanonical%2Fcopilot-collections/lists"}