feat: add engineering discipline skills inspired by agent-skills by z23cc · Pull Request #17 · z23cc/flow-code

z23cc · 2026-04-07T02:01:55Z

Summary

Port the most valuable, stack-agnostic engineering discipline patterns from the agent-skills reference plugin into flow-code:

5 new skills: API/interface design, deprecation/migration, CI/CD patterns, performance methodology, context engineering
4 reference checklists: testing-patterns, security, performance, code-review in references/
ADR template: Architecture Decision Records template + integration guide
Anti-rationalization audit: Reviewed 13 skills, enhanced 3 that were missing rationalization tables

New Skills

Skill	Lines	Focus
`flow-code-api-design`	183	Contract-first design, Hyrum's Law, idempotency
`flow-code-deprecation`	194	Deprecation decision framework, migration workflows
`flow-code-cicd`	245	Quality gates, shift-left, feature flags, staged rollouts
`flow-code-performance`	240	Measure-Identify-Fix-Verify-Guard methodology
`flow-code-context-eng`	182	5-tier context hierarchy, token budgeting

Design Decisions

All skills are stack-agnostic (Rust, Python, Go, TypeScript examples)
Web-specific patterns (Core Web Vitals, WCAG, browser DevTools) excluded
Skills follow docs/skill-anatomy.md template exactly (6 required sections)
Reference checklists in references/ — skills reference by name, don't embed

Test plan

All skills follow skill-anatomy.md template (6 sections each)
All skills under 500 lines
All skills have ≥5 rationalizations and ≥3 red flags
flowctl validate passes
flowctl guard passes (229 unit tests, known trycmd flake excluded)
Codex adversarial review: SHIP
Manual review of skill content quality

🤖 Generated with Claude Code

Architecture Decision Record template for documenting the 'why' behind architectural decisions, with flow-code integration guidance. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Stack-agnostic skill for managing deprecation workflows — assessment, replacement, migration, and clean removal. Inspired by agent-skills. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Consolidates context optimization methodology — 5-tier hierarchy, CLAUDE.md optimization, and strategic use of existing context tools. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Stack-agnostic reference checklists for testing patterns, security, performance, and code review. Adapted from agent-skills patterns. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Contract-first interface design skill covering REST APIs, CLI tools, libraries, RPC, and event schemas. Includes Hyrum's Law, idempotency, and boundary validation patterns. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Quality gate pipeline design, shift-left principle, feature flags, and staged rollouts. Platform-agnostic with GitHub Actions examples. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Measure-Identify-Fix-Verify-Guard workflow for systematic performance optimization. Stack-agnostic with multi-language profiling examples. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Reviewed 13 skills for Common Rationalizations and Red Flags coverage. 10 skills already met the >=5 rationalizations, >=3 red flags minimum. Added both sections to the 3 skills that were missing them entirely: plan-review (7 rationalizations, 6 red flags), brainstorm (7, 6), and auto-improve (7, 6). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Each checklist now lives inside the skill that references it, matching the established pattern (django, browser skills). This ensures Skill tool path resolution works correctly. - testing-patterns.md, security-checklist.md → skills/flow-code-cicd/references/ - performance-checklist.md → skills/flow-code-performance/references/ - code-review-checklist.md → skills/flow-code-api-design/references/ - adr-template.md stays in root references/ (not skill-specific) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add skills table (name, description, embedding) with vector index for semantic skill matching. SkillRepo provides upsert() and match_skills() using cosine similarity via BGE-small embeddings. Reuses embed_one()/ensure_embedder() from memory module — zero duplication. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

skill register: scans skills/*/SKILL.md, extracts YAML frontmatter (name + description), embeds via BGE-small, stores in skills table. skill match: semantic search against registered skills, returns ranked results with cosine similarity scores. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add Step 0.6 (skill routing) between clarity check and research. Translates request to English keywords, calls flowctl skill-match, and injects matched skills into task spec Approach sections. Non-blocking: embedder failure or no matches → skip silently. Max 3 skill references per task to avoid spec bloat. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Replace vector_top_k (requires ANN index, fails in embedded libSQL) with vector_distance_cos (exact search, no index needed). Works unconditionally in embedded mode. Performance is <1ms for 30 skills. Also lower default threshold from 0.75 to 0.70 based on testing — "deprecate old module" scores 0.73 against flow-code-deprecation. Tested: all 5 new skills match correctly with relevant queries. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

This PR ports several stack-agnostic “engineering discipline” skills and checklists into the flow-code skills system, and adds a new flowctl skill CLI + DB support to register/match skills via embeddings (used by planning to auto-route relevant guidance).

Changes:

Added 5 new skills (API design, deprecation, CI/CD, performance methodology, context engineering) plus per-skill reference checklists.
Added ADR template + ADR integration guide, and expanded rationalization/red-flag sections in several existing skills.
Implemented skill registry + semantic match in flowctl (DB schema/repo + CLI commands) and documented “skill routing” in the planning steps.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
skills/flow-code-plan/steps.md	Adds Step 0.6 “skill routing” instructions using `flowctl skill match`.
skills/flow-code-plan-review/SKILL.md	Adds rationalizations + red flags for plan review.
skills/flow-code-performance/SKILL.md	New performance methodology skill (Measure→Identify→Fix→Verify→Guard).
skills/flow-code-performance/references/performance-checklist.md	Adds a performance checklist reference for the performance skill.
skills/flow-code-deprecation/SKILL.md	New deprecation/migration skill with decision framework + process phases.
skills/flow-code-context-eng/SKILL.md	New context-engineering skill (hierarchy, token budgeting, pruning).
skills/flow-code-cicd/SKILL.md	New CI/CD patterns skill (quality gates, shift-left, rollouts, monitoring).
skills/flow-code-cicd/references/testing-patterns.md	Adds testing patterns reference used by CI/CD skill.
skills/flow-code-cicd/references/security-checklist.md	Adds security checklist reference used by CI/CD skill.
skills/flow-code-brainstorm/SKILL.md	Adds rationalizations + red flags for brainstorming.
skills/flow-code-auto-improve/SKILL.md	Adds rationalizations + red flags for auto-improve.
skills/flow-code-api-design/SKILL.md	New API/interface design skill with contract-first + evolution guidance.
skills/flow-code-api-design/references/code-review-checklist.md	Adds a structured code review checklist reference used by API design skill.
references/adr-template.md	Adds ADR template for architectural decision records.
docs/adr-guide.md	Adds ADR integration guide (storage, referencing, lifecycle, plan integration).
flowctl/crates/flowctl-db/src/skill.rs	Introduces `SkillRepo` (upsert/list/match) with cosine-distance semantic search.
flowctl/crates/flowctl-db/src/schema.sql	Adds `skills` table for skill registry + embeddings.
flowctl/crates/flowctl-db/src/pool.rs	Attempts to create `skills_emb_idx` vector index with graceful degradation.
flowctl/crates/flowctl-db/src/memory.rs	Exposes embedder helpers (`ensure_embedder`, `embed_one`, `vec_to_literal`) to crate.
flowctl/crates/flowctl-db/src/lib.rs	Exports new skill repo/types from `flowctl-db`.
flowctl/crates/flowctl-cli/src/commands/skill.rs	Adds `flowctl skill register` and `flowctl skill match` commands.
flowctl/crates/flowctl-cli/src/commands/mod.rs	Registers the new `skill` command module.
flowctl/crates/flowctl-cli/src/commands/db_shim.rs	Adds `inner_conn()` accessor for raw libsql connection for async repos.
flowctl/crates/flowctl-cli/src/main.rs	Wires the new `skill` command group into the CLI.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-07T03:20:07Z

skills/flow-code-plan/steps.md

+1. Translate the request to English keywords (if not already English). This costs zero tokens — you're already processing the request.
+2. Run:
+   ```bash
+   $FLOWCTL skill match "<english keywords>" --threshold 0.70 --limit 3 --json
+   ```
+3. If matches found (non-empty JSON array): save them for Step 5 (task spec writing). Each matched skill will be referenced in the task's Approach section.
+4. If empty result, error, or embedder unavailable: skip silently. Skill routing is advisory, never blocking.


The instructions here assume flowctl skill match --json returns a raw JSON array and can include below-threshold results. In the current CLI implementation, JSON output is wrapped (e.g., { success, data: [...] }), and match_skills filters out scores below --threshold, so the example/result-handling logic won’t match actual output. Update the step to parse the correct JSON shape (likely data) and adjust the example accordingly (or change the CLI output contract).

Copilot · 2026-04-07T03:20:07Z

flowctl/crates/flowctl-db/src/skill.rs

+    /// Semantic search: embed the query, find nearest skills via
+    /// `vector_top_k`, convert L2 distance to cosine similarity, and
+    /// filter by threshold.
+    ///
+    /// Returns `Ok(vec![])` (not an error) if the embedder or vector
+    /// index is unavailable -- graceful degradation.


The doc comment for match_skills says it uses vector_top_k and converts “L2 distance to cosine similarity”, but the implementation uses vector_distance_cos (cosine distance) with a full table scan and converts via score = 1.0 - dist. Please update the comment to reflect the actual query strategy and distance metric so callers aren’t misled about index requirements and scoring semantics.

Suggested change

/// Semantic search: embed the query, find nearest skills via

/// `vector_top_k`, convert L2 distance to cosine similarity, and

/// filter by threshold.

///

/// Returns `Ok(vec![])` (not an error) if the embedder or vector

/// index is unavailable -- graceful degradation.

/// Semantic search: embed the query, compute `vector_distance_cos`

/// against stored embeddings via an exact full-table scan, order by

/// ascending cosine distance, convert to a similarity score with

/// `score = 1.0 - distance`, and filter by threshold.

///

/// This query strategy does not use `vector_top_k` and does not

/// require a vector/ANN index.

///

/// Returns `Ok(vec![])` (not an error) if the embedder or vector

/// functions are unavailable -- graceful degradation.

Copilot · 2026-04-07T03:20:08Z

skills/flow-code-cicd/SKILL.md

+**When NOT to use:**
+- One-off manual deployments that won't recur
+- Local-only development with no shared branches
+- For test design details, see `references/testing-patterns.md`
+


PR description says the new reference checklists live in top-level references/, but these skills reference checklists in per-skill references/ directories (e.g. skills/flow-code-cicd/references/...). Please either move the files to match the documented location or update the PR description/docs to avoid confusing future contributors about where shared references belong.

z23cc and others added 13 commits April 7, 2026 09:46

feat: add ADR template and integration guide

d626eb2

Architecture Decision Record template for documenting the 'why' behind architectural decisions, with flow-code integration guidance. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat: add deprecation and migration skill

df68502

Stack-agnostic skill for managing deprecation workflows — assessment, replacement, migration, and clean removal. Inspired by agent-skills. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat: add context engineering skill

6f6c878

Consolidates context optimization methodology — 5-tier hierarchy, CLAUDE.md optimization, and strategic use of existing context tools. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat: add references/ directory with 4 universal checklists

778f42f

Stack-agnostic reference checklists for testing patterns, security, performance, and code review. Adapted from agent-skills patterns. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat: add API and interface design skill

0e43cdb

Contract-first interface design skill covering REST APIs, CLI tools, libraries, RPC, and event schemas. Includes Hyrum's Law, idempotency, and boundary validation patterns. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat: add CI/CD patterns skill

44bda58

Quality gate pipeline design, shift-left principle, feature flags, and staged rollouts. Platform-agnostic with GitHub Actions examples. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

feat: add performance methodology skill

8ad20e3

Measure-Identify-Fix-Verify-Guard workflow for systematic performance optimization. Stack-agnostic with multi-language profiling examples. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

z23cc marked this pull request as ready for review April 7, 2026 03:15

Copilot AI review requested due to automatic review settings April 7, 2026 03:15

z23cc merged commit 4f4bb38 into main Apr 7, 2026
1 of 2 checks passed

z23cc deleted the fn-93-add-engineering-discipline-skills branch April 7, 2026 03:15

Copilot started reviewing on behalf of z23cc April 7, 2026 03:16 View session

Copilot AI reviewed Apr 7, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add engineering discipline skills inspired by agent-skills#17

feat: add engineering discipline skills inspired by agent-skills#17
z23cc merged 13 commits intomainfrom
fn-93-add-engineering-discipline-skills

z23cc commented Apr 7, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 7, 2026

Uh oh!

Copilot AI Apr 7, 2026

Uh oh!

Copilot AI Apr 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

-    /// Semantic search: embed the query, find nearest skills via
-    /// `vector_top_k`, convert L2 distance to cosine similarity, and
-    /// filter by threshold.
-    ///
-    /// Returns `Ok(vec![])` (not an error) if the embedder or vector
-    /// index is unavailable -- graceful degradation.
+    /// Semantic search: embed the query, compute `vector_distance_cos`
+    /// against stored embeddings via an exact full-table scan, order by
+    /// ascending cosine distance, convert to a similarity score with
+    /// `score = 1.0 - distance`, and filter by threshold.
+    ///
+    /// This query strategy does not use `vector_top_k` and does not
+    /// require a vector/ANN index.
+    ///
+    /// Returns `Ok(vec![])` (not an error) if the embedder or vector
+    /// functions are unavailable -- graceful degradation.

Conversation

z23cc commented Apr 7, 2026

Summary

New Skills

Design Decisions

Test plan

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants