Skip to content

skills.md

Latest commit

 

History

History
300 lines (223 loc) · 27.7 KB

skills.md

File metadata and controls

300 lines (223 loc) · 27.7 KB
Raw

vstack — skills

Maintained by: designer role
Last updated: 2026-05-14
VS Code docs: agent skills

what are skills?

Skills are the HOW of vstack. Each skill is a reusable procedure that agents (the WHO) apply to a task. A skill defines steps, methodology, and expected outputs — it is agnostic to which role invokes it.

In VS Code, skills are Agent Skills — an open standard. Each skill is a directory with a SKILL.md file. Copilot loads a skill automatically when the task matches its description, or you invoke it manually with /skill-name in chat.

Conceptual model:

  • WHO = agent role (product, architect, designer, engineer, tester, release)
  • HOW = skill (verify, adr, design, explore, …)
  • WHAT = input task + artifact files on disk

Canonical names are the source of truth. Historical or compatibility aliases should remain exceptional and temporary. See docs/architecture/adr/002-artifact-naming-and-compatibility-policy.md.

why skills (vs custom instructions)

Unlike custom instructions that primarily define coding preferences and guardrails, skills package specialized, reusable workflows with optional scripts, examples, and references.

Boundary rule:

  • Policies belong in instructions.
  • Procedures belong in skills.

See instructions.md and 013-instructions-vs-skills-boundary.md.

Key benefits:

  • Specialize Copilot for domain-specific tasks without repeating context.
  • Reduce repetition by defining a capability once and reusing it automatically.
  • Compose capabilities by combining multiple skills into one larger workflow.
  • Keep context efficient through progressive disclosure (metadata first, then instructions, then resources on demand).

current skills

List skills in alphabetical order by skill name in every catalog or role skill list.

Skill Description Primary role(s) Output artifact
adr Architecture Decision Record writing. Documents a decision with context, alternatives, and rationale. architect docs/architecture/adr/NNN-*.md
analyse Cross-cutting technical analysis. Investigates impact, tradeoffs, root causes, or feasibility without implementing changes. engineer, architect analysis report
architecture Engineering-lead plan review. Lock in service boundaries, data models, API contracts, test strategy. architect docs/architecture/overview.md
ask Read-only technical Q&A. Clarifies ambiguous questions, gathers repository evidence, and returns concise answers with references and confidence. all roles referenced answer + next-step guidance
aws-cli AWS CLI workflows for IAM, S3, EC2, RDS, ECS, Lambda, CloudWatch, Secrets Manager, and SSM Parameter Store. engineer, tester —
cicd Write GitHub Actions CI/CD workflow configuration. Covers build, test, lint, security scan, container publish, deploy. release GitHub Actions workflow
changedoc Create and maintain per-change planning documents for existing repositories. Defines metadata, AS-IS, TO-BE, impact, acceptance criteria, and test scenarios before implementation. planner, product, architect, designer, engineer, tester, release docs/changes/<slug>_<title>_YYYYMMDD.md
cloudformation Write and review AWS CloudFormation templates. Parameters, conditions, cross-stack references, change sets, drift detection, and security hardening. engineer CFN template .yaml
code-review Pre-landing code review. Finds bugs that pass CI but break in production — race conditions, security issues, performance landmines. engineer inline findings
codeql Set up CodeQL code scanning via GitHub Actions or CLI. Language matrix, query suites, monorepo config, alert triage. tester .github/workflows/codeql.yml
concise Runtime response-style controller. Switches response density (normal, compact, ultra) and reports active mode via status without reinstall. all roles session style state + status output
consult DX triage and focused review. Routes to one path (API DX, CLI/tool DX, or developer workflow DX) and routes non-DX requests to specialized skills. designer focused DX report or routing recommendation
container Write and review Dockerfile, docker-compose, and container config. Covers multi-stage builds, non-root users, layer optimisation. engineer Dockerfile + compose
conventional-commit Prepare and validate Conventional Commit messages from current changes, with type/scope selection and commit-intent checks before commit. engineer, release compliant commit message(s) + commit(s)
copilot-ops Operate and govern GitHub Copilot settings. Policy checks, configuration drift, usage visibility, and safe change rollout. release Copilot governance operations report
debug Systematic root-cause debugging. Follows scientific method: observe → hypothesise → test → conclude → fix → prevent. engineer root cause report + fix
dependabot Create or optimize .github/dependabot.yml. Ecosystem detection, grouping strategies, monorepo patterns, schedule, and PR customization. engineer, tester .github/dependabot.yml
dependency Dependency health audit. Vulnerability scanning, outdated packages, licence compliance, transitive risk, pinning policy, supply chain hygiene. engineer, tester dependency audit report
design Build a complete API or service design from scratch. Produces OpenAPI specs, error conventions, naming standards. designer docs/design/overview.md / openapi.yaml
docs Post-release documentation alignment for README/API docs/migrations and related artifacts (no CHANGELOG ownership). product, architect, designer, engineer, tester, release updated docs artifacts
explore Repository and system discovery. Maps the architecture, identifies tech debt, produces an onboarding summary. engineer codebase map
gdpr GDPR-compliant engineering practices. Privacy by design, data minimization, storage limitation, erasure, encryption, and PR review checklist. engineer, architect, tester checklist / PR findings
gh-issues Create, update, and manage GitHub Issues via gh CLI. Covers bug/feature/task templates, labels, assignees, milestones, and sub-issues. release, product GitHub Issues
gh-release Create or update a GitHub Release using gh CLI with tag validation, draft/publish mode, and release notes file integration. release GitHub Release
guardrails Activate safety guardrails for the session. Requires explicit confirmation before any destructive action. — (mode activation)
helm Write, review, and operate Helm charts and release lifecycles. Covers lint/template validation, upgrades, rollbacks, and dependencies. engineer, tester Helm charts + release config
incident Incident analysis and blameless post-mortem writing. Timeline reconstruction, 5-Whys root cause, contributing factors, action items. tester, engineer docs/postmortems/YYYY-MM-DD-*.md
inspect Read-only verification audit. Runs baseline plus optional extended checks and produces severity-ranked findings, with no code or commit changes. tester read-only audit report
k8s Write, review, and troubleshoot Kubernetes manifests and operations. Covers rollout safety, probes, RBAC, namespace isolation, and diagnostics. engineer, tester Kubernetes manifests
lazy Engineer-focused minimal-change execution. Prefer avoid/delete/reuse/stdlib/native solutions before writing new code while keeping safety guarantees. engineer minimal safe implementation report + changes
migrate Database migration review and authoring. Forwards/backwards compatibility, zero-downtime strategies, rollback plans, data integrity, index safety. engineer, tester reviewed/corrected migration SQL
onboard Generate a contributor onboarding guide. Prerequisites, setup, tests, env vars, architecture overview, good first issues. product CONTRIBUTING.md + README dev section
openapi Write and review OpenAPI 3.1 specifications. Resource naming, HTTP semantics, status codes, error conventions, pagination, security schemes. designer, engineer openapi.yaml
performance Performance profiling and regression detection. Establishes baselines, detects regressions, profiles bottlenecks. engineer, tester perf report
postmortem Blameless post-mortem writing for incidents. Produces a stakeholder-facing post-mortem document linked to the triggering issue and RCA. tester, engineer stakeholder post-mortem
pr Commit, push, and open a pull request from the current branch to main. release commit + PR
rancher Operate Kubernetes workloads and governance through Rancher. Covers project scope, RBAC, Fleet/GitOps basics, and multi-cluster checks. engineer, tester Rancher/Fleet config
rca Root cause analysis for incidents and bugs. Guides a systematic technical investigation and produces an RCA document linked to the triggering issue. engineer, tester technical RCA
refactor Structured refactoring without behavior change. Identify smells, plan incremental steps, execute, verify correctness. engineer refactored code + green tests
release-notes Prepare release artifacts: write release notes, own CHANGELOG updates, produce docs/releases/YYYY-MM-DD.md. release CHANGELOG + release doc
requirements Collaborative requirements gathering. Clarifies what must be built, defines success criteria and NFRs. product docs/product/requirements.md
secret-scan Configure GitHub secret scanning and push protection. Path exclusions, custom patterns, alert triage, and credential remediation. tester, engineer .github/secret_scanning.yml
security OWASP Top 10 + STRIDE security audit. Finds auth bypasses, injection flaws, exposed secrets, broken access control. tester security audit report
simplify Generic simplification skill for all roles. Reduces proposal and execution complexity while preserving required outcomes and safety constraints. all roles simplify report + reduced scope/complexity
space-setup Set up and maintain a GitHub Copilot Space for a repository. Scope curation, refresh cadence, and context quality checks. product Space setup and maintenance checklist
terraform Write, review, and refactor Terraform IaC. Module structure, state management, variable conventions, provider pinning, and security hardening. engineer Terraform config files
terragrunt Write, review, and refactor Terragrunt DRY multi-environment IaC. Root config, dependency blocks, _envcommon, and run-all workflows. engineer terragrunt.hcl files
threat-model Threat modeling with STRIDE-first identification, optional DREAD prioritization, and selective PASTA depth for critical systems. architect, tester, engineer, designer docs/architecture/threat-model.md
verify Verification fix-loop with mode routing (quick/standard/exhaustive). Runs targeted checks, fixes by severity, and re-verifies impacted paths. engineer, tester fixes + verification report
vision CEO/founder-mode plan review. Rethink from first principles, validate ambition, find the 10x solution. product docs/product/vision.md

changedoc ownership model

Use changedoc for existing-repository change requests (feature, bug, refactor, and similar work).

  • Primary owner: product initializes the changedoc and owns scope/acceptance intent.
  • Contributors: architect, designer, engineer, and tester enrich AS-IS, TO-BE, impact, and test scenarios.
  • Orchestration: planner coordinates updates and stage transitions.
  • Artifact path: docs/changes/<slug>_<title>_YYYYMMDD.md.

file locations

Path Purpose
src/vstack/_templates/skills/<name>/config.yaml Source of truth — skill frontmatter fields
src/vstack/_templates/skills/<name>/template.md Source of truth — skill instructions body
src/vstack/_templates/skills/_partials/*.md Shared partials injected via {{TOKEN}}
.github/skills/<name>/SKILL.md Generated output — what VS Code loads
.vstack/vstack.json Generated install manifest and artifact index for all installed artifact types

Never edit .github/skills/ directly. Regenerate after every change:

vstack install

template.md structure

Skill templates use the same split model as agents:

  • config.yaml contains skill metadata/frontmatter fields.
  • template.md contains only skill instructions body.

The generator reads config.yaml and emits recognised fields as frontmatter in generated SKILL.md.

{{SKILL_CONTEXT}}

## Your skill instructions here
name: architecture
version: 1.0.1
description: |
  Engineering-lead plan review. Lock in the execution plan — service boundaries,
  data models, API contracts, error handling, test strategy, ...
argument-hint: '[plan or system to review]'

The {{SKILL_CONTEXT}} token is replaced with the shared _partials/skill-context.md at generation time.

authoring-only guidance vs runtime guidance

Authoring guidance belongs in this document (or README), not in every runtime skill body. Keep generated SKILL.md files focused on execution steps.

Put in docs (author-facing):

  • writing standards for skill templates
  • minimum skill contract/checklists for authors
  • rationale and design principles for maintainers

Put in runtime skills (model-facing):

  • actionable procedure for the current task
  • concrete commands and expected output structure
  • explicit escalation and failure behavior

frontmatter fields

Field Type Required Notes
name string yes Lowercase kebab-case. Must match the directory name. Max 64 chars. Also the /slash-command name in chat.
description string yes What the skill does and when to use it. Copilot uses this for auto-loading decisions. Max 1024 chars (vstack limit).
license string no Optional license name or reference to bundled license file.
compatibility string no Optional environment requirements. Max 500 chars.
metadata mapping (raw YAML) no Optional arbitrary key/value metadata.
argument-hint string no Shown after /skill-name in the chat input. E.g. [plan or system to review].
user-invocable bool no true (default) = appears in the / slash command menu. Set false for background-only skills.
disable-model-invocation bool no true = Copilot will never auto-load this skill; only accessible via /skill-name.

version is maintained in config.yaml for vstack install/update tracking and is not emitted into generated SKILL.md frontmatter.

Template revision format is YYYYMMDDNNN (for example 20260502001):

  1. YYYYMMDD is the template file modified date used for the update.
  2. NNN is a zero-padded sequence for multiple updates on the same day.
  3. The value is treated as an opaque, monotonically increasing revision token (not semantic versioning).

allowed-tools is supported by vstack and emitted as plain frontmatter text when provided in config.yaml.

name must satisfy the Agent Skills naming rules enforced by vstack: lowercase kebab-case, no leading/trailing hyphen, max 64 characters.

how user-invocable and disable-model-invocation interact

user-invocable disable-model-invocation In / menu Auto-loaded
true (default) false (default) ✅ ✅ General-purpose skills
false false ❌ ✅ Background knowledge skills
true true ✅ ❌ On-demand only
false true ❌ ❌ Disabled

how Copilot loads skills

  1. Discovery — Copilot reads name + description from frontmatter to decide if the skill is relevant.
  2. Instructions loading — The SKILL.md body is loaded into context when the skill is selected (auto or manual).
  3. Resource access — Any extra files in the skill directory (scripts, examples) are only loaded when referenced in the body.

This three-level loading keeps context lean — many skills can be installed without overhead.

minimum skill body contract

Use this as the minimum baseline for every skill body:

  1. What it helps accomplish
  2. When to use it
  3. Step-by-step procedure
  4. Expected input/output examples
  5. References to scripts/resources
  6. Out-of-scope + escalation/failure rules
  7. Common edge cases (strongly recommended)

Recommended additions for production-grade skills:

  1. Assumptions/prerequisites (required tools, environment, permissions).
  2. Completion checklist (definition of done).
  3. Fallback behavior when required context is missing.
  4. Explicit file references to scripts/resources using relative paths from skill root (for example: scripts/run.sh, references/REFERENCE.md).

Recommended skill directory layout:

  • SKILL.md (generated from config.yaml + template.md)
  • scripts/ (executable helpers)
  • references/ (on-demand deep documentation)
  • assets/ (templates, sample data, static resources)

This aligns with progressive disclosure: keep SKILL.md focused (instructions body under about 5000 tokens; target under 500 lines), and move detailed material into references/, scripts/, or assets/.

Token-efficiency guidance:

  • Prefer heading hierarchy and concise transition text over decorative separator lines.
  • Avoid long horizontal ruler lines made from repeated characters (for example _____) in skill bodies.

search and context hygiene

Skill templates should avoid scanning dependency/generated trees unless explicitly requested. Prefer commands that exclude:

  • .venv/, venv/, env/
  • node_modules/
  • __pycache__/
  • dist/, build/
  • .git/

Example grep pattern:

grep -r -n "pattern" . \
  --exclude-dir=.venv \
  --exclude-dir=venv \
  --exclude-dir=env \
  --exclude-dir=node_modules \
  --exclude-dir=__pycache__ \
  --exclude-dir=dist \
  --exclude-dir=build \
  --exclude-dir=.git

adding a new skill

  1. Create src/vstack/_templates/skills/<name>/config.yaml with name, version, and description.
  2. Create src/vstack/_templates/skills/<name>/template.md with a body that includes {{SKILL_CONTEXT}}.
  3. Add <name> to EXPECTED_CANONICAL_NAMES in src/vstack/cli/constants.py.
  4. Regenerate: vstack install
  5. Verify: python3 -m pytest tests/ -q
  6. Update the skills table above.
  7. Keep all skill lists alphabetically ordered by skill name (for example in docs tables and ## skills you use sections in agent templates).

validation

vstack verify   # check all skill templates
python3 -m pytest tests/ -q  # full test suite