# Skill File Authoring Conventions

This document describes the `agdt` frontmatter block used in `.github/agents/agdt.*.agent.md`
and `.github/prompts/agdt.*.prompt.md` files for platform classification. The classification
system enables context-aware conditional skill injection — only skills relevant to the
target repository's platform configuration are injected into Copilot sessions.

## Purpose

Every `agdt.*` skill file can optionally carry an `agdt` YAML frontmatter block that
declares which platform(s) the skill requires. The injection pipeline reads this block
via `parse_classification()` and decides whether to include the skill based on the
target repository's configured `issue_adapter` and `code_hosting` values.

Files **without** an `agdt` block are treated as **universal** — they are always injected
regardless of platform configuration.

## The `agdt` Frontmatter Block

The `agdt` block is placed in the YAML frontmatter (between `---` delimiters) of each
skill file. It supports two top-level fields: `requires` and `always`.

### `requires` Sub-Block

The `requires` block declares platform dependencies along two independent axes:

| Axis | Field | Valid Values | Description |
|------|-------|-------------|-------------|
| Issue adapter | `issue_adapter` | `jira`, `github`, `markdown` | The issue tracking system the skill depends on |
| Code hosting | `code_hosting` | `github`, `azure_devops`, `other` | The code hosting platform the skill depends on |

When both axes are present, `should_inject()` performs an **AND-match** — the skill is
only injected when **both** the configured `issue_adapter` and `code_hosting` match.

When only one axis is present, the other axis is unrestricted (matches any value).

### `always` Field

Setting `always: true` marks the file as an **always-inject** skill. These files are
injected into every Copilot session regardless of platform configuration. This is used
for the self-reporting allowlist — skills that let agents file bugs and feature requests
against the agentic-devtools project itself.

When `always: true` is set, any `requires` constraints are ignored at injection time
(though they may still be present for documentation purposes).

## Classification Decision Tree

When adding or modifying an `agdt.*` skill file, follow this decision tree to determine
the correct classification:

1. **Is this a self-reporting/allowlist skill?** (e.g., `create-agdt-*` files)
   → Add `agdt: { always: true }`

2. **Does the skill invoke ONLY Jira-specific commands?** (e.g., `agdt-add-jira-comment`,
   `agdt-get-jira-issue`, `agdt-create-epic`, Jira role management commands)
   → Add `agdt: { requires: { issue_adapter: jira } }`

3. **Does the skill invoke ONLY Azure DevOps-specific commands?** (e.g.,
   `agdt-add-pull-request-comment`, `agdt-get-pull-request-threads`,
   `agdt-approve-pull-request`, pipeline commands)
   → Add `agdt: { requires: { code_hosting: azure_devops } }`

4. **Does the skill invoke ONLY GitHub-specific commands?** (e.g., `agdt-gh-*` commands,
   GitHub Copilot review, GitHub Actions, GitHub PR merge — without equivalent branches
   for other platforms)
   → Add `agdt: { requires: { code_hosting: github } }`

5. **Does the skill require BOTH a specific issue adapter AND code hosting platform?**
   → Add both axes: `agdt: { requires: { issue_adapter: jira, code_hosting: azure_devops } }`

6. **Is the skill platform-neutral?** (invokes no platform-specific commands)
   → Leave **untagged** (no `agdt` block) — the skill is universal.

7. **Does the skill implement intentional multi-provider branching?** (explicitly handles
   multiple platforms via conditional logic, e.g., both Azure DevOps and GitHub paths
   side by side)
   → Leave **untagged** (no `agdt` block) — the skill must be available in all environments.

## What Makes a File Universal

A file is classified as **universal** (no `agdt` block) for one of two reasons:

- **Platform-neutrality** — The file invokes no platform-specific commands and references
  no platform-only concepts. Examples: `git-save-work`, `set`, `test`, `advance-workflow`.

- **Intentional multi-provider branching** — The file explicitly handles every first-class
  provider for the relevant axis via conditional logic. For example,
  `address-pr-review-comments` provides both an Azure DevOps path (`agdt-reply-to-pull-request-thread`,
  `agdt-resolve-thread`) and a GitHub path (`agdt-gh-reply-to-review-comments`,
  `agdt-gh-resolve-review-threads`) side by side, and instructs the agent to choose the
  appropriate commands for the configured platform. Such files must remain available in all
  environments.

**Important**: The `agdt-` command prefix alone is **not** a reliable universality
indicator. Many platform-specific commands use the `agdt-` prefix without any sub-prefix
(e.g., Jira's `agdt-add-jira-comment`, Azure DevOps' `agdt-get-pull-request-threads`).

## Frontmatter Examples

### Jira-Only Skill

```yaml
---
description: "Add Jira Comment: Add a comment to a Jira issue"
agdt:
  requires:
    issue_adapter: jira
---
```

### Azure DevOps-Only Skill

```yaml
---
description: "Add PR Comment: Post a comment on a pull request"
agdt:
  requires:
    code_hosting: azure_devops
---
```

### GitHub-Only Skill

```yaml
---
description: "Address Copilot Review: Automatically address GitHub Copilot PR review comments by URL"
agdt:
  requires:
    code_hosting: github
---
```

### Always-Inject Skill

```yaml
---
description: "Create Bug Issue: Create a bug issue in agentic-devtools"
agdt:
  always: true
---
```

### Universal (Untagged) Skill

```yaml
---
description: "Git Save Work: Stage, commit/amend, and push changes"
---
```

No `agdt` block — the skill is universal and always injected.

### Dual-Axis `requires` Skill

```yaml
---
description: "Example Dual-Axis Skill: Requires both Jira and Azure DevOps"
agdt:
  requires:
    issue_adapter: jira
    code_hosting: azure_devops
---
```

Both axes must match for the skill to be injected.

## Consistency Rules

- **Agent/prompt pairs**: When both an `.agent.md` and `.prompt.md` file exist for the
  same skill name, both **must** carry identical `agdt` blocks (FR-005).
- **YAML validity**: The frontmatter must remain valid YAML parseable by `yaml.safe_load()`.
- **Existing fields preserved**: Adding an `agdt` block must not remove or modify existing
  fields like `description`, `agent`, `handoffs`, or `name`.
- **Placement**: The `agdt` block should be placed after `description:` for readability
  (advisory, not enforced by CI).
