---
name: team-skills
description: Use when listing, adding, or onboarding team skills from the directives repo to the agent's skills directory; --all installs every default and external skill at once.
disable-model-invocation: true
---

# team-skills

## Overview

Browse available skills from the team AI directives and install
selected ones to the current agent's skills directory. Use `--all` to
install every `default` and `external` skill in one pass. Skills are
installed under their **original names** (no prefix) so they stay in sync
with the manifest.

## When to Use

- When the user asks to browse, list, or install team skills.
- When the input names a specific skill to install.
- When extending the agent's capabilities with team-shared skills.
- When `team-setup` delegates `/team-skills --all` after initial configuration.

```text
$ARGUMENTS
```

## Core Process

### Setup

Read the file `.adlc/init-options.json` directly. Do NOT use glob, find,
or any file-search tool to locate it — search tools may silently skip
dotfile-prefixed path segments. Read the file at the exact relative path
`.adlc/init-options.json` from the current working directory.

If that read fails (file not found), walk up parent directories by reading
`../.adlc/init-options.json`, then `../../.adlc/init-options.json`,
and so on — up to 4 levels. Stop at the first successful read.

From the JSON, extract the `team_ai_directives` field:

```json
{
  "team_ai_directives": "/path/to/team-ai-directives"
}
```

If `team_ai_directives` is not set, STOP:

```
Team AI directives not configured.
Run: /team-setup
```

Helper scripts (relative to skill directory):

- `$(dirname "$0")/team-helpers.sh --json`
- `$(Split-Path $PSCommandPath -Parent)/team-helpers.ps1 -Json`

### Step 1: Read Skills Manifest

Read `{REPO_ROOT}/.skills.json` (where `{REPO_ROOT}` denotes the project
root — the directory where `.adlc/` lives) and `{TEAM_AI_DIRECTIVES}/.skills.json`
(team directives manifest). Merge both, with project-root entries taking
precedence. Parse the manifest sections (schema v2.0.0):

| Section | Description | Installed by `--all`? |
|---------|-------------|-----------------------|
| `default` | Local skills (in `skills/{name}/`) auto-installed during setup | Yes |
| `external` | Remote skills fetched by URL, installed on demand | Yes |
| `blocked` | Rejected — must never be installed | Never |

### Step 2: Show Available Skills

Present skills grouped by section. For each skill show:

- Name (the key, e.g. `github-actions` for local, `react-best-practices` for external)
- Description
- Whether it's already installed (check agent skills directory)

Format:

```
Team Skills from {TEAM_AI_DIRECTIVES}

Default (local, installed by --all):
  [installed] dbt-template - DBT project templates and best practices
  [available] github-actions - GitHub Actions CI/CD pipeline patterns
  [available] helm-charts - Helm chart patterns for Kubernetes
  [available] crossplane - Crossplane Composition and XRD patterns
  [available] external-secrets - External Secrets Operator patterns
  [available] gke-workload-identity - GKE Workload Identity patterns

External (remote, installed by --all):
  [available] react-best-practices - React performance optimization
  [available] web-design-guidelines - Web interface best practices
```

### Step 3: Install Selected Skills

Determine the install target from the arguments:

- **`--all`**: Install every `default` skill **and** every `external` skill,
  skipping anything in `blocked` and anything already installed.
- **A skill name**: Install that one skill directly.
- **No input**: Ask the user which skills to install.

Determine the agent's skills directory:
1. Read `.adlc/integration.json` to get the current agent
2. Use `{agent_folder}/skills/` as the destination

Install under the **original name** (no prefix), frontmatter `name` unchanged:

For **local skills** (`default` list — names map to `skills/{name}/`):

1. Locate `{TEAM_AI_DIRECTIVES}/skills/{name}/SKILL.md`
2. Copy `SKILL.md` to `{skills_dir}/{name}/SKILL.md`

For **external skills** (`external` map — entries have a `url`):

1. Download `SKILL.md` from the entry's `url` field
2. Save to `{skills_dir}/{name}/SKILL.md`

Never install any skill listed in `blocked`. Skip skills already present at the
destination (report them as `[installed]`).

### Step 4: Confirm

```
Installed: github-actions
Location: .opencode/skills/github-actions/SKILL.md
Source: default (local:./skills/github-actions)
```

### Notes

- Default skills are installed via `--all`, typically invoked by `team-setup`
  after initial configuration or run manually at any time.
- Skills are installed under their original names — no `team-` prefix — so the
  on-disk name matches the manifest key.
- Skills from the `blocked` list are never installed.
- External skills are fetched over HTTPS from the URL in the manifest.

## Common Rationalizations

| Rationalization | Why it's wrong | Do this instead |
|---|---|---|
| "I'll add a `team-` prefix to installed skills" | Diverges the on-disk name from the manifest key, breaking lookups | Install under the original name; frontmatter `name` stays unchanged |
| "Search tools will find `.adlc/init-options.json`" | Glob/find silently skip dotfile-prefixed path segments | Read the exact relative path directly |
| "Blocked skills are just strong recommendations" | `blocked` means explicitly rejected on install | Never install blocked skills |
| "Default skills already auto-installed elsewhere" | Only `--all` (via team-setup or manual) installs them | Run `/team-skills --all` to onboard the default set |
| "I'll skip merging the project-root manifest" | Project entries are meant to override team defaults | Merge both manifests; project-root wins conflicts |

## Red Flags

- Using glob, find, or grep to locate `.adlc/init-options.json` instead of reading the exact path.
- Renaming a skill or adding a `team-` prefix on install — install under the original name so it matches the manifest.
- Installing a skill listed under the `blocked` section.
- Writing skills to any directory other than the agent's configured skills folder.
- Proceeding past an unset `team_ai_directives` field instead of stopping with the config message.
- Fetching an external skill over a non-HTTPS URL.

## Verification

- `.adlc/init-options.json` was read directly (no search tool) and `team_ai_directives` resolved to a path.
- Both `{REPO_ROOT}/.skills.json` and `{TEAM_AI_DIRECTIVES}/.skills.json` were merged; project-root entries won any conflicts.
- Each installed skill lives at `{skills_dir}/{name}/SKILL.md` with its original `name` in frontmatter (no prefix).
- No skill from the `blocked` section was installed.
- `--all` installed every `default` and `external` skill (skipping `blocked` and already-installed).
- A confirmation block was emitted showing the installed name, on-disk location, and source.

## Configuration

- `TEAM_AI_DIRECTIVES` — Path to the team AI directives (overrides `.adlc/init-options.json`).
- `.adlc/init-options.json` — Project-level config file with `team_ai_directives` field.
- Default fallback: `team-ai-directives/` relative to project root.
- `team-helpers.sh` / `team-helpers.ps1` — Shared scripts used for path resolution.

## 12-Factor Alignment

Factor XII (Team Capability) — manages team skill catalog and installation.

#!/usr/bin/env bash
# team-helpers.sh — Shared utilities for team-* skills
# 
# Flags:
#   --json              Output path info as JSON (default: key=value)
#   --scaffold [DIR]    Create a fresh 11-file team AI directives scaffold at DIR
#   --agents-only DIR   Create only AGENTS.md at DIR (for repair use)
#   --inject-agents [DIR]  Inject team-boot directive into project-level AGENTS.md at DIR
#   --name NAME         Team name for scaffold (default: "My Team")
set -euo pipefail

###############################################################################
# 1. PATH RESOLUTION
###############################################################################

resolve_paths() {
  PROJECT_ROOT="${PROJECT_ROOT:-$([[ -d ".adlc" ]] && pwd || git rev-parse --show-toplevel 2>/dev/null || pwd)}"
  BRANCH="${BRANCH:-$(git branch --show-current 2>/dev/null || echo 'unknown')}"
  TEAM_AI_DIRECTIVES=""

  # 1. Check TEAM_AI_DIRECTIVES env var (highest priority)
  if [[ -n "${TEAM_AI_DIRECTIVES:-}" ]]; then
    TEAM_AI_DIRECTIVES="$TEAM_AI_DIRECTIVES"
  fi

  # 2. Check .adlc/init-options.json
  if [[ -z "$TEAM_AI_DIRECTIVES" ]]; then
    INIT_OPTIONS="${PROJECT_ROOT}/.adlc/init-options.json"
    if [[ -f "$INIT_OPTIONS" ]]; then
      TEAM_AI_DIRECTIVES=$(python3 -c "
import json, sys
try:
    with open('$INIT_OPTIONS') as f:
        print(json.load(f).get('team_ai_directives', ''))
except Exception:
    print('')
" 2>/dev/null || true)
    fi
  fi

  # 3. Fallback to default path
  if [[ -z "$TEAM_AI_DIRECTIVES" ]]; then
    TEAM_AI_DIRECTIVES="${PROJECT_ROOT}/team-ai-directives"
  fi

  echo "PROJECT_ROOT=$PROJECT_ROOT"
  echo "TEAM_AI_DIRECTIVES=$TEAM_AI_DIRECTIVES"
  echo "BRANCH=$BRANCH"
}

output_json() {
  printf '{"REPO_ROOT": "%s", "TEAM_AI_DIRECTIVES": "%s", "BRANCH": "%s"}\n' \
    "$PROJECT_ROOT" "$TEAM_AI_DIRECTIVES" "$BRANCH"
}

###############################################################################
# 2. TEAM AI DIRECTIVES STRUCTURE VALIDATION
###############################################################################

validate_team_ai_directives() {
  local dir="$1"
  local missing=0

  for required in \
    "context_modules/constitution.md" \
    "context_modules/rules" \
    "context_modules/personas" \
    "context_modules/examples" \
    "CDR.md" \
    ".skills.json"; do
    if [[ ! -e "${dir}/${required}" ]]; then
      echo "MISSING: ${required}"
      missing=$((missing + 1))
    fi
  done

  return "$missing"
}

###############################################################################
# 3. SCAFFOLD
###############################################################################

scaffold_team_ai_directives() {
  local dest="$1"
  local team_name="${2:-My Team}"
  local today
  today=$(date +%Y-%m-%d)

  if [[ -d "$dest" && -n "$(ls -A "$dest" 2>/dev/null)" ]]; then
    echo "ERROR: Destination '$dest' already exists and is not empty." >&2
    exit 1
  fi

  mkdir -p "${dest}/context_modules/rules"
  mkdir -p "${dest}/context_modules/personas"
  mkdir -p "${dest}/context_modules/examples"
  mkdir -p "${dest}/skills"

  cat > "${dest}/README.md" << README
# ${team_name} Team AI Directives

Team AI directives repository for ${team_name}.

## Getting Started

1. Wire this directives repository into a project:
   \`\`\`
   /team-setup
   \`\`\`
   Choose "Point to existing local path" and select this directory.

2. Add context modules to \`context_modules/\` (rules, personas, examples).

3. Add skills to \`skills/\` and register them in \`.skills.json\`.

4. Update \`CDR.md\` as context modules are approved.

See [ADLC Team Skills](https://github.com/tikalk/adlc-team-skills) for full documentation.
README

  cat > "${dest}/AGENTS.md" << 'AGENTS'
# Agent Instructions

## Structure

- `context_modules/constitution.md` — Team constitution
- `context_modules/rules/` — Team rules and workflows
- `context_modules/personas/` — Team personas
- `context_modules/examples/` — Team examples
- `skills/` — Team skills
- `evals/` — Directive compliance goldensets (pass/fail cases)
- `CDR.md` — Context Directive Records

## Loading Order

1. Load constitution.md first
2. Load relevant rules for the current task
3. Load relevant personas for the current task
4. Load relevant examples for the current task

## Using Skills

Skills are located in the `skills/` directory. Browse available skills using team-skills and install them as needed.

## CDR.md

The CDR.md file tracks approved context contributions. Update it when adding new context modules.
AGENTS

  cat > "${dest}/CDR.md" << CDR
# Context Directive Records

Context Directive Records (CDRs) track decisions about contributing context modules (rules, personas, examples, skills) to team-ai-directives.

## CDR Index

| ID | Target Module | Type | Status | Created | Verified | Age | Descriptor |
|----|---------------|------|--------|---------|----------|-----|------------|

**Stats**: 0 entries | Last Updated: ${today}
CDR

  cat > "${dest}/.skills.json" << 'SKILLSJSON'
{
  "version": "2.0.0",
  "source": "team-ai-directives",
  "description": "Team skills manifest. The `default` list contains skill names that are auto-installed during project setup. The `external` map contains on-demand skills fetched by URL. The `blocked` list contains skills that must never be installed.",
  "default": [],
  "external": {},
  "blocked": [],
  "policy": {
    "auto_install_default": true,
    "enforce_blocked": true,
    "allow_project_override": true
  }
}
SKILLSJSON

  cat > "${dest}/.mcp.json.example" << 'MCPJSON'
{
  "mcpServers": {}
}
MCPJSON

  cat > "${dest}/context_modules/constitution.md" << CONSTITUTION
---
type: Constitution
title: "${team_name} Constitution"
description: "Team-wide principles and governance"
resource: ./context_modules/constitution.md
tags: [constitution]
generated: { by: agent:team-setup, at: ${today}T00:00:00Z }
id: constitution
cdr_ref: null
created: ${today}
verified:
  - { by: agent:team-setup, at: ${today}T00:00:00Z }
status: stable
stale_after: 180d
---

# ${team_name} Constitution

No team-wide principles defined yet. Add principles as they are established.
CONSTITUTION

  cat > "${dest}/context_modules/index.md" << 'INDEXTOP'
---
okf_version: "0.2"
---

# Context Modules

* [Rules](rules/index.md) - Team rules and workflows
* [Personas](personas/index.md) - Team personas
* [Examples](examples/index.md) - Team examples
INDEXTOP

  cat > "${dest}/context_modules/log.md" << 'LOGTOP'
# Context Modules Update Log
LOGTOP

  cat > "${dest}/context_modules/rules/index.md" << 'INDEXRULES'
# Rules

No rules defined yet. Use /team-learn to create rules via CDRs.
INDEXRULES

  cat > "${dest}/context_modules/rules/log.md" << 'LOGRULES'
# Rules Update Log
LOGRULES

  cat > "${dest}/context_modules/personas/index.md" << 'INDEXPERS'
# Personas

No personas defined yet. Use /team-learn to create personas via CDRs.
INDEXPERS

  cat > "${dest}/context_modules/personas/log.md" << 'LOGPERS'
# Personas Update Log
LOGPERS

  cat > "${dest}/context_modules/examples/index.md" << 'INDEXEX'
# Examples

No examples defined yet. Use /team-learn to create examples via CDRs.
INDEXEX

  cat > "${dest}/context_modules/examples/log.md" << 'LOGEX'
# Examples Update Log
LOGEX

  cat > "${dest}/CDR.md" << 'CDRDERIVED'
# Context Directive Records (Derived Index)

> ⚠️ Auto-generated by `/team-repair`. Do not edit manually.
> Source of truth: `context_modules/*/index.md` + module frontmatter.
> Decision lifecycle (Accepted/Rejected) lives in the `adlc` orphan branch `drafts/cdr/`.

## CDR Index

| ID | Path | Type | Description | Generated | Verified | Age | Status |
|----|------|------|-------------|-----------|----------|-----|--------|

**Stats**: 0 entries | Last Updated: PLACEHOLDER
CDRDERIVED

  touch "${dest}/context_modules/rules/.gitkeep"
  touch "${dest}/context_modules/personas/.gitkeep"
  touch "${dest}/context_modules/examples/.gitkeep"
  touch "${dest}/skills/.gitkeep"

  echo "Scaffolded team-ai-directives at ${dest}"
  echo "Team name: ${team_name}"
  echo "Files created: 14"

  validate_team_ai_directives "$dest" || true
}

scaffold_agents_only() {
  local dest="$1"
  mkdir -p "$dest"

  cat > "${dest}/AGENTS.md" << 'AGENTS'
# Agent Instructions

## Structure

- `context_modules/constitution.md` — Team constitution
- `context_modules/rules/` — Team rules and workflows
- `context_modules/personas/` — Team personas
- `context_modules/examples/` — Team examples
- `skills/` — Team skills
- `reports/sessions/` — Published session summaries (from `/team-learn`, on `adlc` branch)
- `CDR.md` — Context Directive Records

## Loading Order

1. Load constitution.md first
2. Load relevant rules for the current task
3. Load relevant personas for the current task
4. Load relevant examples for the current task

## Using Skills

Skills are located in the `skills/` directory. Browse available skills using team-skills and install them as needed.

## CDR.md

The CDR.md file tracks approved context contributions. Update it when adding new context modules.
AGENTS

  echo "Created AGENTS.md at ${dest}"
}

###############################################################################
# 4. INJECT PROJECT-LEVEL AGENTS.md DIRECTIVE
###############################################################################

inject_project_agents() {
  local project_root="${1:-.}"
  local team_directive="${2:-}"

  # Resolve team_ai_directives if not provided
  if [[ -z "$team_directive" ]]; then
    local init_options="${project_root}/.adlc/init-options.json"
    if [[ -f "$init_options" ]]; then
      team_directive=$(python3 -c "
import json, sys
try:
    with open('$init_options') as f:
        print(json.load(f).get('team_ai_directives', ''))
except Exception:
    print('')
" 2>/dev/null || true)
    fi
  fi

  # Fallback to env var
  if [[ -z "$team_directive" ]] && [[ -n "${TEAM_AI_DIRECTIVES:-}" ]]; then
    team_directive="$TEAM_AI_DIRECTIVES"
  fi

  # Fallback to default path
  if [[ -z "$team_directive" ]]; then
    team_directive="${project_root}/team-ai-directives"
  fi

  local agents_file="${project_root}/AGENTS.md"
  local marker_start="<!-- TEAM_AI_DIRECTIVES START -->"
  local marker_end="<!-- TEAM_AI_DIRECTIVES END -->"

  # Build the managed section
  local section
  section=$(cat <<SECTION
${marker_start}
# Team AI Directives

This project is bound by the team AI directives repository at \`${team_directive}\`.

team-boot runs automatically at session start via the event hook (for agents with event support), injecting a lean orientation into the first user message with the team constitution, CDR index, Class Boots catalog, skills registry, and MCP servers.

If the team AI directives context is NOT in your system prompt or first user message (agent without event support), invoke the \`team-boot\` skill before responding to any task or question.

If team AI directives are unconfigured, invoke the \`team-setup\` skill.

Invoke the matching class boot when a task or decision matches a row:

## Class Boots

| Boot | Injects | Invoke When | Capture Via |
|--|--|--|--|
| architect-boot | ADR index (.adlc/memory/adr/) | architecture work; tech-stack/pattern choice | /architect-specify |
| product-boot | PDR index (.adlc/memory/pdr/) | product/feature scope, personas, monetization | /product-specify |
| change-boot | ChDR index (.adlc/memory/chdr.md) | change-history rationale, reverts, issue-linked commits | /change-init |
| team-boot | CDR module bodies (team-ai-directives) | CDR descriptor match; reusable team pattern | /team-learn |
| tech-radar-boot | Tikal Tech Radar context | choosing/evaluating technology | radar context + /architect-specify |

Each class boot emits its class context section and its own searched line (_Searched N records, K matched._).

**Every response MUST include** a Team Context in Use section before the task answer:

## Team Context in Use

| ID | Name | Type | Rel |
|--|--|--|--|
| CDR-YYYY-NNN | <name> | <type> | <relevance> |

Plus: \`_Searched N CDRs, M skills, J matched._\` — **J MUST equal the number of rows in your table; if no CDRs/skills genuinely match, show an empty table with 0 matched (do not copy a hard-coded CDR or inflate the count).**

## Decision Capture

Detect decisions as they emerge; full detection and capture guidance lives in the matching class boot:

- Tech stack / pattern choice → ADR → /architect-specify (pull tech-radar-boot context first for tech selection)
- Feature scope / persona / monetization → PDR → /product-specify
- Reusable team rule / pattern → CDR → /team-learn
- Revert/hotfix rationale / issue-linked commit → ChDR → /change-init

Maintain a running Session Decision Ledger in every response (after the Team Context in Use table):

| Decision | Type | Captured? | Skill |
|----------|------|-----------|-------|
| _none yet_ | — | — | — |

_Unrecorded: N pending._

At session end, prompt to invoke the capture skills for any unrecorded decisions. Only suggest capture when genuinely warranted.
${marker_end}
SECTION
)

  # Create AGENTS.md if it doesn't exist, or update the managed section
  python3 - "$agents_file" "$marker_start" "$marker_end" "$section" <<'PY'
import os, sys

agents_path, start, end, section_content = sys.argv[1:5]

if os.path.exists(agents_path):
    with open(agents_path, "r", encoding="utf-8") as f:
        content = f.read()
else:
    content = ""

# Check if markers already exist
s_idx = content.find(start)
e_idx = content.find(end)

if s_idx != -1 and e_idx != -1 and s_idx < e_idx:
    # Replace existing managed section
    new_content = content[:s_idx] + section_content + content[e_idx + len(end):]
    if new_content.endswith("\n"):
        new_content += "\n"
    elif not new_content.endswith("\n\n"):
        new_content += "\n"
    with open(agents_path, "w", encoding="utf-8") as f:
        f.write(new_content)
    print(f"Updated team AI directives section in {agents_path}")
else:
    # Append managed section
    if content and not content.endswith("\n"):
        content += "\n"
    if content and not content.endswith("\n\n"):
        content += "\n"
    content += section_content + "\n"
    with open(agents_path, "w", encoding="utf-8") as f:
        f.write(content)
    print(f"Injected team AI directives section into {agents_path}")
PY
}

###############################################################################
# MAIN
###############################################################################

main() {
  if [[ "$#" -eq 0 ]]; then
    resolve_paths
    return
  fi

  local has_json=false
  local has_scaffold=false
  local has_agents_only=false
  local has_inject_agents=false
  local scaffold_dest=""
  local agents_only_dest=""
  local inject_dest=""
  local team_name="My Team"
  local parsing_scaffold=false
  local parsing_agents=false
  local parsing_name=false
  local parsing_inject=false

  for arg in "$@"; do
    if [[ "$arg" == "--json" || "$arg" == "-Json" ]]; then
      has_json=true
      continue
    fi
    if [[ "$arg" == "--help" || "$arg" == "-h" ]]; then
      echo "Usage: team-helpers.sh [--json] [--scaffold DIR] [--agents-only DIR] [--inject-agents [DIR]] [--name NAME]"
      exit 0
    fi
    if [[ "$arg" == "--scaffold" ]]; then
      has_scaffold=true
      parsing_scaffold=true
      parsing_agents=false
      parsing_name=false
      parsing_inject=false
      continue
    fi
    if [[ "$arg" == "--agents-only" ]]; then
      has_agents_only=true
      parsing_agents=true
      parsing_scaffold=false
      parsing_name=false
      parsing_inject=false
      continue
    fi
    if [[ "$arg" == "--inject-agents" ]]; then
      has_inject_agents=true
      parsing_inject=true
      parsing_scaffold=false
      parsing_agents=false
      parsing_name=false
      continue
    fi
    if [[ "$arg" == "--name" ]]; then
      parsing_name=true
      parsing_scaffold=false
      parsing_agents=false
      parsing_inject=false
      continue
    fi
    if $parsing_scaffold && [[ -n "$arg" ]]; then
      scaffold_dest="$arg"
      parsing_scaffold=false
      continue
    fi
    if $parsing_agents && [[ -n "$arg" ]]; then
      agents_only_dest="$arg"
      parsing_agents=false
      continue
    fi
    if $parsing_inject && [[ -n "$arg" ]]; then
      inject_dest="$arg"
      parsing_inject=false
      continue
    fi
    if $parsing_name && [[ -n "$arg" ]]; then
      team_name="$arg"
      parsing_name=false
      continue
    fi
  done

  if $has_scaffold; then
    if [[ -z "$scaffold_dest" ]]; then
      echo "ERROR: --scaffold requires a destination directory argument" >&2
      exit 1
    fi
    scaffold_team_ai_directives "$scaffold_dest" "$team_name"
    return
  fi

  if $has_agents_only; then
    if [[ -z "$agents_only_dest" ]]; then
      echo "ERROR: --agents-only requires a destination directory argument" >&2
      exit 1
    fi
    scaffold_agents_only "$agents_only_dest"
    return
  fi

  if $has_inject_agents; then
    local project_root="${inject_dest:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
    inject_project_agents "$project_root"
    return
  fi

  # Default: resolve paths
  resolve_paths > /dev/null
  if $has_json; then
    output_json
  else
    resolve_paths
  fi
}

main "$@"