team-api

Team API

Generate or update a Team Topologies Team API document enriched with AI literacy portfolio assessment data. The Team API is a document that describes a team's capabilities, communication preferences, and service offerings — adding AI literacy data makes the team's engineering maturity visible to the rest of the organisation.

This skill works in two modes:

• Update mode: reads an existing Team API document and adds or refreshes the AI literacy section using the latest portfolio assessment data
• Template mode: generates a new Team API document from the template in references/team-api-template.md, populated with portfolio assessment data

Input

The skill needs:

• Portfolio assessment file — the most recent assessments/*-portfolio-assessment.md. If none exists, tell the user to run /portfolio-assess first.
• Existing Team API file (optional) — if the user provides a path to an existing Team API document, update it. If not, generate from the template.
• Team directory (optional) — where to write the output. Defaults to the current directory.

Process

Step 1: Find Portfolio Assessment Data

ls assessments/*-portfolio-assessment.md 2>/dev/null | sort | tail -1

If no file exists, stop and suggest running /portfolio-assess.

Read the most recent portfolio assessment and extract:

• Portfolio median level
• Assessment coverage percentage
• Repo detail table (each repo with level and discipline scores)
• Shared gaps
• Improvement plan (organisation-wide items)
• Next assessment date

Step 2: Check for Existing Team API

Ask the user:

Do you have an existing Team API document to update?

1. Yes — provide the file path
2. No — generate a new one from the template

Step 3a: Update Existing Team API

If the user provides an existing file, read it and look for an ## AI Literacy or ## AI Engineering Maturity section. If found, replace it with fresh data. If not found, append the section before the last section of the document (typically "Further Information" or similar).

The AI Literacy section to insert:

## AI Literacy

**Portfolio median level**: LN — Level Name
**Assessment coverage**: N% of repos fully assessed
**Last portfolio assessment**: YYYY-MM-DD
**Next assessment due**: YYYY-MM-DD

### Repo Levels

| Repo | Level | Confidence | Last Assessed |
| --- | --- | --- | --- |
| repo-name | LN | assessed/estimated | YYYY-MM-DD |

### Discipline Scores (assessed repos only)

| Repo | Context | Constraints | Guardrails |
| --- | --- | --- | --- |
| repo-name | N/5 | N/5 | N/5 |

### Active Shared Gaps

| Gap | Repos Affected | Recommended Action |
| --- | --- | --- |
| gap description | N/M | action |

### Current Improvement Focus

[Organisation-wide improvement items from the portfolio assessment,
presented as the team's current AI engineering priorities]

Preserve all other sections of the existing Team API untouched.

Step 3b: Generate New Team API from Template

If no existing file, read references/team-api-template.md and populate it with:

• Team name (ask the user)
• Team type (ask: stream-aligned, enabling, complicated-subsystem, or platform)
• The AI Literacy section populated from portfolio assessment data
• Placeholder sections for the user to fill in (communication preferences, service offerings, dependencies)

Write to the team directory as team-api.md.

Step 4: Summary

Report what was done:

Team API [created/updated]: path/to/team-api.md

  AI Literacy section: populated from portfolio assessment (YYYY-MM-DD)
  Portfolio median: LN
  Repos covered: N
  Shared gaps: N
  Next assessment: YYYY-MM-DD

What Gets Pulled from Portfolio Assessment

Portfolio field	Team API field
Portfolio median level	AI Literacy header
Assessment coverage	AI Literacy header
Repo detail table	Repo Levels table (simplified)
Discipline scores	Discipline Scores table
Shared gaps	Active Shared Gaps table
Organisation-wide improvements	Current Improvement Focus
Next assessment date	Next assessment due

What This Skill Does NOT Do

• Does not run /portfolio-assess — the data must already exist
• Does not modify the portfolio assessment — it reads, not writes
• Does not fill in non-AI sections of the Team API — those are the team's responsibility
• Does not enforce Team Topologies practices — it provides the document structure, the team decides how to use it