Skip to content

Create Skills Summary

ContributorsPaul Atkins

Purpose

Produce a skills summary that maps available engineering library skills to a remediation plan's work items. Identifies coverage, gaps, and execution-time skills that engineers will use during implementation.

Prerequisites

  1. Remediation plan — phased work items with skill references
  2. Engineering library — skills directory (e.g. .github/skills/)
  3. Gap analysis (optional) — helps contextualise which gaps skills address

Instructions

Step 1 — Inventory available skills

Read all SKILL.md files in the engineering library. For each skill, capture:

Field Source
Name name: frontmatter
Description description: frontmatter
Phase phase: frontmatter (diagnose / plan / implement / cross-cutting)
Maturity maturity: frontmatter
User-invocable metadata.user-invocable:

Step 2 — Map skills to plan items

For each work item in the remediation plan:

  1. Check if a Skill: reference already exists in the plan.
  2. If not, check whether an available skill covers the work item's activity.
  3. Record the mapping.

Produce a table:

## Skills Used in the Plan

| Plan item | Phase | Skill | How it's used |
|-----------|-------|-------|---------------|
| 1.2 CI/CD pipeline | Phase 1 | `gap-analysis` | Baseline assessment |
| 2.3 Test coverage | Phase 2 | `unit-test` | Test writing guidelines |
| ... | ... | ... | ... |

Step 3 — List available but unused skills

For each skill NOT referenced in the plan, explain why:

## Available Skills Not Used

| Skill | Phase | Why not used |
|-------|-------|-------------|
| `scientist-pattern` | implement | No legacy migration with behaviour parity required |
| `databricks-naming-compliance-review` | cross-cutting | System does not use Databricks |

Step 4 — Identify execution-time skills

Some skills aren't plan items but will be used during execution:

## Execution-Time Skills

| Skill | When used |
|-------|-----------|
| `git-hygiene` | Every coding session |
| `unit-test` | When writing tests for each work item |
| `docs-implementation-tagging` | When updating docs alongside code changes |

Step 5 — Identify skill gaps

For each plan item where no skill exists but one would be valuable:

## Skill Gaps

| Capability needed | Plan items affected | Priority | Notes |
|-------------------|--------------------|---------|----- |
| Azure pipeline setup | 1.2, 1.3 | High | Reference pipeline exists in feature-flagger-ui |
| Database migration | 0.2, 1.1 | High | SQLite → PostgreSQL migration patterns |
| Frontend test scaffolding | 2.5, 2.6 | Medium | Jest/Vitest + React Testing Library |

Step 6 — Produce the summary document

Output as [system]-skills-summary.md with sections:

  1. Skills used in the plan
  2. Available skills not used
  3. Execution-time skills
  4. Skill gaps (with priority)

Output

A single .md file that serves as a reference for engineers executing the plan and for skill library maintainers identifying where to invest in new skills.

Tips

  • Don't force-fit skills. If a skill doesn't naturally apply, list it as "not used" with a reason. Artificially mapping skills adds confusion.
  • Execution-time skills matter. Skills like git-hygiene and unit-test won't appear as plan items but are used constantly during implementation.
  • Skill gaps are actionable. Each gap is a candidate for a new skill. Prioritise gaps that affect multiple plan items or are on the critical path.

Troubleshooting

Error: Skills summary maps skills that don't naturally fit plan items. Cause: Force-fitting skills to show high coverage. Solution: If a skill doesn't naturally apply, list it as "not used" with a reason. Artificially inflated coverage is misleading.

Error: Execution-time skills are missing from the summary. Cause: Only plan-referenced skills were inventoried; cross-cutting skills like git-hygiene were overlooked. Solution: Scan the full skills library for skills with phase cross-cutting or implement — these are commonly used during execution even if not explicitly in the plan.

Error: Skill gap priorities don't align with plan priorities. Cause: Gaps were prioritised independently of the plan's critical path. Solution: Cross-reference gaps against plan phases and dependencies. Gaps blocking Phase 0–1 items are higher priority than those affecting Phase 3.