ai-skills

name	ai-skills
description	Create, modify, validate, and analyze Windsurf AI assets such as AGENTS.md files, Windsurf skills, templates, and supporting scripts. Use when building or maintaining the repository's Windsurf-specific AI component package. Use when this capability is needed.
metadata	{"author":"alex-voloshin-dev"}

AI Assets

Build and maintain Windsurf-native AI assets for this repository. Treat every asset as live Windsurf prompt surface.

1. Determine Scope

Identify:

• Operation: create | modify | validate | analyze
• Asset type: agents-md | skill | template | checklist | script
• Target path or asset name

If the request is ambiguous, resolve it from repository context before asking the user.

2. Gather Context

Read only the assets needed for the task:

1. The target asset, if it exists
2. Root AGENTS.md
3. Relevant scoped AGENTS.md files
4. Relevant .windsurf/skills/*/SKILL.md files
5. Relevant files under .windsurf/
6. context-engineering skill when the asset affects prompt layering, memory, RAG, or orchestration

3. Build a Dependency Map

Map outgoing and incoming references.

Check for:

• References to AGENTS.md
• References to .windsurf/skills/<name>/
• References to shared templates, checklists, or support resources under .windsurf/skills/ai-skills/
• References to explicit support scripts such as .windsurf/hooks/scripts/*
• Missing files
• Orphaned assets
• Circular references that add confusion

For analyze, stop after presenting the dependency map.

4. Choose the Right Windsurf Primitive

Use the smallest asset that matches the job:

• Repository or directory policy -> AGENTS.md
• Reusable task workflow or knowledge -> .windsurf/skills/<name>/SKILL.md
• Reusable authoring scaffold -> supporting resources under .windsurf/skills/<skill>/templates/
• Validation procedure -> supporting resources under .windsurf/skills/<skill>/checklists/ or companion markdown files
• Repeatable local automation -> explicit support scripts owned by the target package

Do not recreate Claude-specific primitives such as agent files, Claude settings, or Claude hook configs.

5. Authoring Rules

AGENTS.md

• Put hard constraints first
• Keep project facts concrete and current
• Keep global policy in the root file and local conventions in scoped files
• Avoid repeating parent guidance verbatim

SKILL.md

• Include name and a specific description
• Optimize description for correct progressive disclosure
• Keep the workflow executable with minimal ambiguity
• Move bulky references and checklists into companion markdown files

Templates and Checklists

• Prefer short, reusable structures
• Separate policy from examples
• Make completion criteria explicit

Scripts

• Keep scripts visible and optional
• Never hide critical behavior behind implicit automation
• Prefer PowerShell for this repository's local automation

6. Prompt Engineering Review

Review the asset as live Windsurf context:

1. What part of Windsurf behavior does it shape?
2. What failure mode does it prevent or enable?
3. Is the instruction hierarchy clear?
4. Is critical information front-loaded?
5. Is the token cost justified?

Use review-checklist.md for the full validation pass.

7. Validate

Run these checks on every create or modify operation:

• Asset uses Windsurf-native concepts only
• References resolve
• No machine-specific paths unless intentionally local documentation
• No secrets or credentials
• English only
• SKILL.md remains concise enough for progressive disclosure
• AGENTS.md guidance is specific, not generic

If the asset changes the Windsurf package structure, update the package README or mapping docs.

8. Finalize

Report:

• What changed
• Dependency status
• Validation result
• Remaining follow-up items

---

Source: alex-voloshin-dev/ai-skills — distributed by TomeVault.