setup-alastairlundy-skills

Stars0

Forks0

UpdatedAugust 1, 2026 at 12:55

Configures a host repository to use the alastairlundy AI-agent skill family by writing four agent-consumable docs (issue-tracker, triage-labels, domain/GLOSSARY, decision-ledger-audit) and adding the `## Agent skills` block to AGENTS.md or CLAUDE.md. Use when setting up a new repo for AI agents, switching the repo's issue tracker, or re-running after a config change.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

alastairlundy

alastairlundy/skills

View GitHub Repository View Creator Repositories

Download

File Explorer

11 files

SKILL.md

readonly

More from this repository

same repository

ask-questions

alastairlundy/skills

Assists agents with when to ask questions via tools vs prose. Use when a request is ambiguous, has multiple valid interpretations, or needs a discrete choice before proceeding. Do not use when user input is not required, or a request has clear discrete options with concise descriptions.

2026-08-010

code-implementation-grilling

alastairlundy/skills

Relentless Socratic interviewing on technical implementation choices — language, framework, dependencies, project structure — once a spec/PRD exists. Use when implementation is the question. When non-code/tech decisions, use `grilling`. When terminology, use `domain-grilling`.

2026-08-010

domain-grilling

alastairlundy/skills

Relentless Socratic interviewing focused on Domain-Driven Design (DDD) alignment — bounded contexts, ubiquitous language, glossary, terminology. Use when the user has a vague idea and conceptual/terminology alignment is the goal. When non-DDD decisions, use `grilling`. When code/tech with a spec, use `code-implementation-grilling`.

2026-08-010

grilling

alastairlundy/skills

Relentless Socratic interviewing to extract clear decisions from vague ideas. Use when the user wants to think through an ambiguous decision that is neither code/tech nor domain modeling or terminology alignment — business strategy, product direction, design choices, process, organizational decisions, and similar non-implementation decisions. Do not use for code/technical implementation choices — use `code-implementation-grilling` instead. Do not use for domain modeling or terminology alignment — use `domain-grilling` instead.

2026-08-010

implement-tickets

alastairlundy/skills

Coordinate implementation of a normalized ticket set — builds the dependency DAG, groups same-file tickets, dispatches each group to a sub-agent with a fresh context, runs a judge LLM against acceptance criteria, and commits one commit per ticket. Use when a batch of tickets should be implemented in parallel/sequential order with per-ticket commits and an end-of-run report. Do not use for a single ticket (implement it directly), tickets not yet generated (use spec-to-tickets first), or non-ticket work.

2026-08-010

spec-to-tickets

alastairlundy/skills

Create implementation tickets with dependency graphs and Independent/Collaborative classification. Use when a user wants to break down a spec or tasks into tickets, or wants to create implementation tickets. Don't use when - spec is incomplete or vague (use grilling first, or domain-grilling if the resolution needs DDD alignment), a different granularity is needed (epics, tasks), direct implementation is the goal, or the user explicitly wants to send tickets to an issue tracker without dependency graphs or classification.

2026-08-010

name	setup-alastairlundy-skills
description	Configures a host repository to use the alastairlundy AI-agent skill family by writing four agent-consumable docs (issue-tracker, triage-labels, domain/GLOSSARY, decision-ledger-audit) and adding the `## Agent skills` block to AGENTS.md or CLAUDE.md. Use when setting up a new repo for AI agents, switching the repo's issue tracker, or re-running after a config change.
license	MIT

Setup Alastairlundy Skills

Scaffolds the per-repo configuration that the alastairlundy AI-agent skill family assumes. Produces four docs/agents/*.md files plus an in-place ## Agent skills block in the host repo's AGENTS.md (or CLAUDE.md).

The skill is a fork of setup-matt-pocock-skills, adapted to this repo's requirements — extended with multi-host support and a decision-ledger-audit section.

When to Use

When the user wants to set up a new host repository to use the alastairlundy AI-agent skill family.
When the user wants to switch the host repository's issue tracker (e.g., GitHub → Gitea, GitLab → Local Markdown, or any host → Other non git workflow).
When the user wants to re-run setup after a config change (new triage labels, new domain layout, new decision-ledger convention, or a new host).
When the user must pick between issue-tracker variants, Git Host sub-options, domain layout (single- vs multi-context), or label-mapping overrides, invoke the ask-questions skill to surface the choice before proceeding.

When Not to Use

When the user is mid-task and does not want to be interrupted — this skill writes files to the host repo and is best run as a discrete work item.

Output Mode

Default behaviour is file-writing: the skill writes four docs/agents/*.md files and updates the ## Agent skills block in the host repo's AGENTS.md (or CLAUDE.md if AGENTS.md does not exist).
The Confirm step (Step 6) is the per-file opt-out: the user can decline any individual file before it is written.
No top-level dry-run flag, no preview mode. The Confirm step is the only safety net.
The skill does not overwrite user edits to sections of AGENTS.md / CLAUDE.md that are outside the ## Agent skills block.

Workflow

Step 1: Explore

Run git status and git log --oneline -10 in the host repo to confirm a clean working tree and to inspect recent commit style. Probe the host repo's starting state — read whatever exists; do not assume:

git remote -v and .git/config — is this a GitHub, GitLab, Gitea, Codeberg, or other-host repo? Which one?
AGENTS.md and CLAUDE.md at the repo root — does either exist? Is there already an ## Agent skills section in either?
GLOSSARY.md and GLOSSARY-MAP.md at the repo root.
docs/adr/ and any src/*/docs/adr/ directories.
docs/agents/ — does this skill's prior output already exist?
.scratch/ — sign that a local-markdown issue tracker convention is already in use.

Completion criterion: a clean working tree is reported, and the presence/absence of AGENTS.md, CLAUDE.md, the ## Agent skills block, and the prior docs/agents/*.md outputs is recorded.

Step 2: Present issue tracker (with PR follow-up)

Invoke the ask-questions skill to present three top-level variants:

Git Host — issues live on a Git host's native issue tracker
Local Markdown files — issues live as files under .scratch/<feature>/ in this repo
Other non git workflow — issues live in a non-git system the user describes in prose

Sub-rules for the Git Host pick:

Ask a follow-up to pick the exact host from {GitHub, GitLab, Gitea, Codeberg} or specify a user-defined host. If the user names a Forgejo-based host (self-hosted Codeberg, self-hosted Forgejo, a non-profit Forgejo instance), resolve to the Forgejo seed template — issue-tracker-forgejo.md is the shared file for Codeberg and all Forgejo-based hosts (Codeberg is a Forgejo instance, so the API and seed content are identical).
After any Git Host pick, ask the PR-as-issue-surface follow-up (yes / no, default no). The answer is recorded as a one-line note in the ## Conventions section of docs/agents/issue-tracker.md. Skip this question for Local Markdown and Other non git workflow.

Sub-rules for the Other non git workflow pick:

Ask a follow-up for the user to describe the workflow in prose; the description is inlined verbatim into docs/agents/issue-tracker.md.

Load the matching seed template (load triggers below), fill in the user's answers, and present the proposed docs/agents/issue-tracker.md.

Completion criterion: a docs/agents/issue-tracker.md candidate is presented to the user, with the ## Conventions and ## When a skill says sections populated for the chosen variant, and the PR-as-issue-surface note recorded (Git Host variants only).

Step 3: Present triage labels

Explain the five canonical roles:

needs-triage — maintainer needs to evaluate
needs-info — waiting on reporter
ready-for-agent — fully specified, AFK-ready
ready-for-human — needs human implementation
wontfix — will not be actioned

Invoke the ask-questions skill to ask whether to override any role-to-label-string mapping. Load references/triage-labels.md, apply the user's overrides, and present the proposed docs/agents/triage-labels.md.

Completion criterion: a docs/agents/triage-labels.md candidate is presented to the user, with the five-row label-mapping table (or the user's overridden mapping) populated.

Step 4: Present domain docs

Invoke the ask-questions skill to ask the user to pick the domain-docs layout:

Single-context — one GLOSSARY.md at the repo root. Most repos are this.
Multi-context — GLOSSARY.md (system-wide) + GLOSSARY-MAP.md at the root, pointing to per-context GLOSSARY.md files (typically a monorepo).

Load references/domain.md and fill in the chosen layout. The consumer rules in docs/agents/domain.md reference GLOSSARY.md (and GLOSSARY-MAP.md for multi-context). Present the proposed docs/agents/domain.md.

Completion criterion: a docs/agents/domain.md candidate is presented to the user, with the consumer rules referencing GLOSSARY.md.

Step 5: Present decision-ledger-audit

Load references/decision-ledger-audit.md and present the proposed docs/agents/decision-ledger-audit.md. The content is the canonical seed documenting the filename#Dxxx citation rule — bare Dxxx references are prohibited.

Completion criterion: a docs/agents/decision-ledger-audit.md candidate is presented to the user.

Step 6: Confirm

Present the four candidates from Steps 2-5 in a single summary table. For each file, the user accepts or declines. Declined files are not written in Step 7. The ## Agent skills block (Step 7) is included in the summary as a fifth item with the same accept/decline treatment — if declined, only the four docs/agents/*.md files are written.

Completion criterion: each of the four candidates (plus the ## Agent skills block) has an explicit accept/decline from the user; the accepted list is recorded.

Step 7: Write

For each accepted file, write it to the host repo:

Write docs/agents/issue-tracker.md (if accepted).
Write docs/agents/triage-labels.md (if accepted).
Write docs/agents/domain.md (if accepted).
Write docs/agents/decision-ledger-audit.md (if accepted).

For the ## Agent skills block (if accepted):

Choose AGENTS.md if it exists, CLAUDE.md if it exists, or ask the user if neither exists. Never create AGENTS.md when CLAUDE.md exists or vice versa.
Update the ## Agent skills block in-place using a parse-the-block approach: find the ## Agent skills heading, find the next ## heading at the same level, replace the content between them. If the block does not exist, append it. Do not overwrite user edits to surrounding sections.
The block has three subsections (Issue tracker, Triage labels, Domain docs) with one-line summaries pointing to the corresponding docs/agents/*.md files:

## Agent skills

### Issue tracker

[one-line summary of where issues are tracked, plus the PR-as-issue-surface note for Git Host variants]. See `docs/agents/issue-tracker.md`.

### Triage labels

[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`.

### Domain docs

[one-line summary of layout — "single-context" or "multi-context"]. See `docs/agents/domain.md`.

Completion criterion: every accepted file is written; the ## Agent skills block is updated; git status shows only the expected changes; surrounding user content in AGENTS.md / CLAUDE.md is preserved.

Step 8: Done

Report the following four components:

(a) Confirmation that the four docs/agents/*.md files were written (or skipped, per Step 6 declines) and the ## Agent skills block was updated.
(b) Skill mapping — a small table mapping each docs/agents/*.md file to the skills that read it (e.g., issue-tracker.md ← triage, domain.md ← domain-grilling, decision-ledger-audit.md ← grilling / dependency-review).
(c) Edit-directly note — "you can edit any of these files directly; the in-place update logic preserves your changes on re-run".
(d) Re-run note — "re-run this skill to switch issue trackers, update triage labels, or change the domain-docs layout".

Completion criterion: the user has a complete summary of what was written, where, and what the file-to-skill mapping is.

Validation

Do not mark the skill as complete until every item below passes.

docs/agents/issue-tracker.md exists and contains the expected ## Conventions and ## When a skill says sections for the chosen variant (Git Host, Local Markdown, or Other non git workflow).
For a Git Host variant, docs/agents/issue-tracker.md records the PR-as-issue-surface note (yes / no) in the ## Conventions section.
docs/agents/triage-labels.md exists and has 5 rows in the label-mapping table (or the user's overridden mapping).
docs/agents/domain.md exists and references GLOSSARY.md in its consumer rules; for multi-context, it also references GLOSSARY-MAP.md.
docs/agents/decision-ledger-audit.md exists and contains the filename#Dxxx citation rule (bare Dxxx references prohibited).
The ## Agent skills block in AGENTS.md (or CLAUDE.md) references all four docs/agents/*.md files and uses the parse-the-block in-place update (no duplicate block).
git status shows only the expected files; no surrounding user content in AGENTS.md / CLAUDE.md was overwritten.

Reference files (load triggers)

Load each references/*.md file only when its load-trigger condition is met. Do not load all of them upfront.

Before presenting an issue-tracker candidate, load the seed for the chosen variant:
- references/issue-tracker-github.md — GitHub (uses gh CLI)
- references/issue-tracker-gitlab.md — GitLab (uses glab CLI)
- references/issue-tracker-gitea.md — Gitea (uses tea CLI or Gitea API)
- references/issue-tracker-forgejo.md — Codeberg AND other Forgejo-based hosts (shared file — both use the Forgejo API; Codeberg is a Forgejo instance). When the user names a Forgejo-based host under "Other Git Host (User specified)", load this file.
- references/issue-tracker-other-git.md — Other Git Host (User specified) for non-Forgejo hosts
- references/issue-tracker-local.md — Local Markdown
- references/issue-tracker-other-nongit.md — Other non git workflow (User specified)
Before presenting a triage-labels candidate (Step 3), load references/triage-labels.md.
Before presenting a domain-docs candidate (Step 4), load references/domain.md.
Before presenting a decision-ledger-audit candidate (Step 5), load references/decision-ledger-audit.md.

Attribution

Adapted from the setup-matt-pocock-skills skill in the mattpocock/skills repository, licensed under MIT by Matt Pocock and Contributors. The issue-tracker, triage-labels, and domain-docs features are extended with multi-host support (Gitea, Codeberg, other Forgejo-based hosts, other Git hosts, and other non-git workflows) and a decision-ledger-audit section, per docs/decisions/DECISIONS-skills-setup-skill-replace.md (D001-D021).