본문으로 건너뛰기
TakoAPI
스킬로 돌아가기

copilot-collections

canonical 제작

Copilot
—아직 평가 없음
내 평가

요약

Instructions, prompts, and configurations to help you make the most of GitHub Copilot.

설명

<!--
  ~ Copyright 2026 Canonical Ltd.
  ~ See LICENSE file for licensing details.
-->

# **Canonical Copilot Collections**

**Centralized context management for GitHub Copilot across the Canonical ecosystem.**

This 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.

## **What are Collections?**

A **Collection** is a logical group of markdown files (instructions, prompts, agents, and skills) defined in `collections.yaml.`

Instead of copying specific instructions into 50 different repositories manually, the consuming repository defines a configuration file listing the collections it needs.

**Available Collections (Examples):**

* core: Core assets common to all repositories.
* common-python: Standard Python coding style.  
* common-documentation: Documentation standards with review skill.
* charm-python: Includes common-python + Juju Ops Framework specifics.  
* copilot-toolkit: Meta-tools for generating and managing Copilot assets (agents, skills, prompts, instructions).
* pfe-charms: Platform Engineering specific collection.

## **Usage: Adding to a Repository**

To add Copilot collections to your repository, follow these three steps.

**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.

### **1. Create the Configuration**

Create a file named `.copilot-collections.yaml` in the `.github` folder of your repository (recommended) or in the repository root.

```yaml
copilot:
  # The version of the toolkit to use (matches a Release Tag in this repo)
  version: "v1.0.0"

  # The collections you want to install
  collections:
    - charm-python
    - pfe-charms
```

**Location Preference:** The workflow and sync script will search for the config file in this order:
1. `.github/.copilot-collections.yaml` (recommended)
2. `.copilot-collections.yaml` (root, for backwards compatibility)

You can also specify a custom location - see below for details.

### **2. Run the Initial Sync (Local)**

You can sync the instructions immediately to your local machine to verify them.

```bash
curl -sL https://raw.githubusercontent.com/canonical/copilot-collections/main/scripts/local_sync.sh | bash
```

To specify a custom config file location:
```bash
# Via command-line argument
curl -sL https://raw.githubusercontent.com/canonical/copilot-collections/main/scripts/local_sync.sh | bash -s -- custom/path/.copilot-collections.yaml

# Via environment variable
COPILOT_CONFIG_FILE="custom/path/.copilot-collections.yaml" curl -sL https://raw.githubusercontent.com/canonical/copilot-collections/main/scripts/local_sync.sh | bash
```

**Note:** This will generate files in .github/instructions/, .github/prompts/, and .github/skills/. Do not edit these files manually; they will be overwritten.

### **Install Skills Directly with skills CLI**

For discoverable core skills in this repository, you can install directly with `skills`:

```bash
# List discoverable skills
npx skills add canonical/copilot-collections --list

# Install one skill globally (use skill name, not path)
npx skills add canonical/copilot-collections --skill generate-agent -g
```

**Note:** Group-scoped skill discoverability is handled separately.

### **3. Configure Auto-Updates (CI)**

To ensure your repo stays up to date when the Toolkit releases new versions, add this workflow.

**File:** `.github/workflows/copilot-collections-update.yml`

```yaml
name: Auto-Update Copilot Instructions
on:
  schedule:
    - cron: '0 9 * * 1' # Run every Monday at 09:00 UTC
  workflow_dispatch:
  
permissions:
  contents: write
  pull-requests: write

jobs:
  check-update:
    # Always pin to @main to get the latest logic, but the content version is controlled by your .yaml file
    uses: canonical/copilot-collections/.github/workflows/auto_update_collections.yaml@main
    secrets: inherit
    # Optionally specify a custom config file location and/or branch name:
    # with:
    #   config_file: "custom/path/.copilot-collections.yaml"
    #   branch_name: "work/bot/update-copilot-collections"
```

## **Inspiration & Credits**

Some prompts and instruction patterns in this collection were inspired by the [Awesome GitHub Copilot](https://github.com/github/awesome-copilot) repository.

We 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.

## **Maintaining**

### **Directory Structure**

* `assets/`: Raw markdown files for core instructions, prompts, and agents.
  * `instructions/`: Custom instruction files.
  * `prompts/`: Prompt files.
  * `agents/`: Agent files.
* `skills/`: Core agent skill directories (each containing `SKILL.md`, plus optional `scripts/`, `references/` and `assets/` subfolders).
* `collections.yaml`: Core definitions.
* `groups/`: Team specific collections.
  * `<team-name>/`: Folder for team assets.
    * `collections.yaml`: Team specific definitions.
    * `skills/`: Team specific agent skill directories, following the same layout as core skills.
* `scripts/`: Logic for syncing files.
* `.github/workflows/`: Reusable workflows.

### **How to add a new Instruction**

1. **Add the file:** Create `assets/instructions/my-topic/my-new-instructions.md` (for core) or `groups/<team>/instructions/...` (for teams).
2. **Update Manifest:** Edit `collections.yaml` (core) or `groups/<team>/collections.yaml`.
   * Add it to an existing collection items list.
   * OR create a new collection key if it represents a new logical group.
3. **Release:**
   * Open PR.
   * Merge changes to main.
   * After **Test Toolkit** passes, **Release Toolkit** automatically tags the
     tested commit and publishes a GitHub Release with autogenerated release notes.
   * *Consumer repos will pick this up automatically on their next scheduled run.*

### **Automatic Releases**

Every successful **Test Toolkit** push run on `main` triggers the dedicated
`.github/workflows/release.yaml` workflow. Pull request runs and failed checks
do not publish releases. All changes to `main`, including documentation changes,
are eligible.

The publisher increments the minor version of the latest stable release and
resets the patch version: `v0.22.0` becomes `v0.23.0`, then `v0.24.0`.
It uses GitHub's generated release notes (the same facility as the release UI),
starting from the previous release tag, and marks the new release as **Latest**.
The existing latest release must have a `vMAJOR.MINOR.PATCH` tag.

Publishing runs are serialized, with up to 100 pending runs queued. Rerunning
checks for an already released commit does not create another release. If checks
finish out of order, a commit already included in a newer release is skipped
rather than rolling subscribers back. The release always targets the tested
commit, not a potentially newer `main`.

The workflow uses the built-in `GITHUB_TOKEN` with `contents: write`; no personal
token is required. Failed release lookup or publishing, divergent history, and
an existing next-version tag fail the workflow instead of silently succeeding.
After resolving a publishing failure, rerun **Release Toolkit** from the Actions
tab. Subscriber schedules and update workflows do not need to change.

### **How to add a new Agent Skill**

1. **Create the directory:** Create `skills/<skill-name>/` (for core) or `groups/<team>/skills/<skill-name>/` (for teams).
2. **Add SKILL.md:** Create the skill definition file with required YAML frontmatter:
   ```markdown
   ---
   name: skill-name
   description: What the skill does
   ---
   # Skill content here
   ```
3. **Update Manifest:** Edit `collections.yaml` and add to a collection's items:
   ```yaml
   - src: skills/<skill-name>
     dest: .github/skills/<skill-name>/
   ```
   **Important:** Skills are directories, so `dest` must end with `/`.
4. **Validate:** Run `./scripts/validate_collections.sh .`
5. **Release:** Follow the same release process as instructions.

#### **Skill Directory Layout (optional subfolders)**

A skill is a directory whose only required file is `SKILL.md`. Because skills are
synced as whole directories, any supporting files you place alongside `SKILL.md`
are copied automatically — you do **not** register them individually in the manifest.

Two optional subfolders are used by convention across existing skills:

* `scripts/`: Executable helpers the skill invokes (e.g. Python utilities).
  Referenced from `SKILL.md` by relative path (e.g. `python3 scripts/helper.py`).
  Examples: `generate-agent-skills/scripts/`, `generate-path-instructions/scripts/`.
* `references/`: Auxiliary Markdown the agent loads on demand (checklists,
  templates, deep-dive docs) to keep `SKILL.md` lean.
  Examples: `generate-agent/references/`, `generate-repo-instructions/references/`.

Both are optional; add them only when the skill needs helper code or extra
reference material. Note: files under `skills/**` are exempt from the license
header check (see `.licenserc.yaml`).

### **Group Collections**

Teams can manage their own collections in `groups/<team-name>/`.

**Naming Convention:**
Collection names are global. To avoid collisions, **prefix your collection names with your group name**.
*   ✅ `pfe-charms`
*   ❌ `charms` (Too generic)

**Path Resolution:**
*   **Relative Paths**: `src: instructions/guide.md` -> Resolves to `groups/<team>/instructions/guide.md`.
*   **Root Paths**: `src: /assets/common/logo.png` -> Resolves to `assets/common/logo.png` (Repository Root).

### **Linting Markdown Files**

The repository includes a Markdown linter to ensure consistent formatting across all instruction, prompt, agent, and skill files.

**Run the linter:**

```bash
# Lint all files
make lint-md

# Lint specific directory
make lint-md SOURCEDIR=assets/agents
make lint-md SOURCEDIR=assets/instructions
```

**Requirements:** The linter uses `uv` and `pymarkdownlnt`. The Makefile automatically sets up a virtual environment and installs dependencies on first run.

**Configuration:** Linting rules are defined in `.pymarkdown.json` at the repository root.

설치

https://github.com/canonical/copilot-collections에서 스킬을 설치해줘

이 스킬은 ClawHub 레지스트리에 게시되지 않았습니다. 프롬프트를 코딩 에이전트(Claude Code, Cursor, Codex)에 붙여넣으면 소스 저장소에서 바로 스킬을 설치합니다.

저장소 열기

링크