setup-matt-pocock-skills - Engineering Skills Repository Configuration

Skill Overview

setup-matt-pocock-skills is a one-time repository initialization skill. Run it once before using other engineering skills to configure three things in the repository: the issue tracker, the triage label vocabulary, and the domain documentation layout.

Applicable Scenarios

1. First-time integration of the Matt Pocock engineering skills package: After installing skills such as to-tickets, triage, or to-spec, you need to configure them with the location of the repository’s issues, the label names, and where documentation belongs; otherwise, the subsequent skills will have no starting point.
2. Starting a new repository or project: The repository does not yet have docs/agents/ or CONTEXT.md, and you want to establish the working conventions needed by AI agents in files once and for all, rather than explaining them again in every conversation.
3. Managing context separately in a multi-package monorepo: When signals such as pnpm-workspace.yaml or packages/* are present, the skill proposes a multi-context layout—a root CONTEXT-MAP.md pointing to each package’s CONTEXT.md—instead of forcing the entire documentation set into a single context.

Core Functions

1. Configure the issue tracker: First explore the repository’s current state (git remote -v, .git/config), then recommend a tracker type based on the findings—GitHub using the gh CLI, GitLab using the glab CLI, local Markdown files under .scratch/<feature>/ for repositories without remotes or solo projects, or custom workflows such as Jira and Linear. The final decision is written to docs/agents/issue-tracker.md.
2. Configure the triage label vocabulary: This is performed only when the triage skill is installed. By default, it uses five standardized roles—needs-triage, needs-info, ready-for-agent, ready-for-human, and wontfix—with label strings matching the role names. If your tracker already uses different names (for example, bug:triage for needs-triage), you can map the roles to existing labels to avoid creating duplicates.
3. Configure the domain documentation layout and write agent conventions: The default is a single-context layout (one root-level CONTEXT.md plus docs/adr/). Only when monorepo signals are detected does it offer multi-context options. Once decided, it writes an ## Agent skills section to CLAUDE.md or AGENTS.md, with one summary line and a file reference for each configuration area.

The entire process is prompt-driven rather than a deterministic script: the skill first explores the repository, presents its findings, confirms each section with you, and only then writes the files. During the confirmation stage, it provides a draft for you to modify. If an ## Agent skills section already exists in the selected file, it updates that section in place without appending a duplicate block or overwriting changes to other sections.

Frequently Asked Questions

How many times does this skill need to run, and when should it be run?

Normally, run it once per repository before using any other engineering skill for the first time. If you only want to fine-tune the content afterward, edit docs/agents/*.md directly; you do not need to run the skill again. Run it again only if you plan to change the issue tracker or want to reconfigure everything from scratch.

Will it automatically create AGENTS.md? Will an existing CLAUDE.md be overwritten?

Neither. There are explicit file-selection rules: if CLAUDE.md exists, edit it; otherwise, edit AGENTS.md. If neither exists, it first asks which one you want to create and does not decide for you. The skill will never create AGENTS.md when CLAUDE.md already exists, and vice versa. When writing, it updates only the ## Agent skills section, leaving surrounding sections unchanged.

Can it be used without GitHub? What if there is no remote repository?

Yes. GitHub is merely the default recommendation. The skill also supports GitLab (using the glab CLI), local Markdown files (with issues stored under .scratch/<feature>/, suitable for solo projects or repositories without remotes), and other trackers such as Jira and Linear. When selecting “Other,” simply describe your workflow in a paragraph, and the skill will record it as free text. Also note that this skill sets disable-model-invocation: true, so it can only be triggered manually; the AI will not invoke it automatically.