Team Skills

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.

$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:

{
  "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:

• Read .adlc/integration.json to get the current agent
• 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}/):

• Locate {TEAM_AI_DIRECTIVES}/skills/{name}/SKILL.md
• Copy SKILL.md to {skills_dir}/{name}/SKILL.md

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

• Download SKILL.md from the entry's url field
• 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.