Create Skill

Use this skill whenever you need to create a new SKILL.md file in the project.

1. Decide which stack repo the skill lives in (do this FIRST)

Before writing anything, decide which stack repo will host the skill. Editing inside a workspace's .agents/skills/ directly is wrong — that directory is regenerated by wsp bootstrap / wsp sync from the source stacks, and your edit will be blown away. The skill must live in a stack repo and reach the workspace via composition.

Apply the transversal-vs-product test

From agent-stack-core/awac.yml#org_scaffold.transversal_vs_product:

1. Could another product in your portfolio use this skill as-is?
2. Does the skill codify a team or technology convention rather than a product-specific one?
3. If two products needed it, would two copies be a mistake?

Any "yes" → transversal. All "no" → product-specific.

Map the answer to a stack repo

Worked example — create_po_translations: The skill is about handling Odoo .po translation files. Test: would another product with an Odoo module need it as-is? Yes. Is it a convention of Odoo more than of a product? Yes. → transversal by ecosystem → <ecosystem-org>/agent-stack/skills/create_po_translations/. Despite the name not mentioning "odoo", the placement is correct because the technology context (.po files = Odoo translations) is unambiguous.

Default when unsure

Conservative default: product-specific. It is cheap to promote a skill from a product stack to transversal later. It is expensive to retract a transversal skill once two products have started depending on its details.

But: if the skill encodes how a technology works (Odoo, Terraform, Cloudflare Workers, MCP), it is almost always transversal — go with the topical or cross-org stack, not the product.

Naming inside the chosen stack

For transversal stacks, no product suffix is needed. For product stacks, prefer adding the product name to the file/folder when the concept is generic enough that a future transversal version could collide:

• aws_resource_safety_<product>.md — explicit, coexists with universal aws_resource_safety.md from core.
• init_project_<product>.md — explicit, coexists with universal init_project.md from core.
• use_orchestrator_api.md — implicit OK when "orchestrator" is already a product-specific entity name.

Skip the product suffix only when the file name already references a product-specific entity and the chance of colliding with a transversal version is zero.

2. File Location

Once Section 1 is settled, all skills MUST be placed at:

<stack-repo>/skills/<skill-name>/SKILL.md
<stack-repo>/skills/<skill-name>/evals/evals.json   ← MANDATORY

Inside any workspace, after wsp bootstrap or wsp sync, the same skill appears at .agents/skills/<skill-name>/SKILL.md (composed from its source stack — DO NOT edit this composed copy).

Use snake_case for the folder name.

3. Correct SKILL.md Format

---
name: skill-name
description: >
  [Hyper-specific trigger description — see Section 3]
---

# Skill Title

Brief one-line summary of what this skill enables.

---

## Step 1 — [First action]

Instructions...

## Step 2 — [Second action]

Instructions...

## Rules / Constraints

- Rule 1
- Rule 2

4. Writing the Description (Most Critical Part)

The description: field is what Claude reads to decide whether to open this skill dynamically. If it is vague, the skill will not trigger reliably.

A good description answers:

• WHEN to use it (explicit trigger conditions)
• WHAT it does (the key output or behavior)
• HOW it differs from doing it without the skill (constraints, rules, gotchas)

❌ Too vague

description: Helps with creating Excel files.

✅ Hyper-specific

description: >
  USE any time the task involves creating, editing, or reading .xlsx, .csv, or
  .tsv files. Defines the full workflow: pandas for analysis, openpyxl for
  formulas/formatting, recalc.py for formula recalculation. CRITICAL: always use
  Excel formulas (=SUM()) instead of hardcoded Python values. Triggers on file
  paths ending in .xlsx even mentioned casually.

5. Mandatory evals/evals.json

Every skill MUST ship with at least 3 evals. Create the file at: .agents/skills/<name>/evals/evals.json

{
  "skill_name": "skill-name",
  "description": "Tests que verifican que la skill produce el comportamiento correcto.",
  "evals": [
    {
      "id": 1,
      "name": "descriptive-name-of-behavior",
      "prompt": "Realistic user prompt that should trigger this skill's key behavior",
      "assertions": [
        {
          "id": "a1",
          "text": "The response does/mentions X (objectively verifiable)",
          "weight": "critical"
        },
        {
          "id": "a2",
          "text": "The response avoids Y (negative check)",
          "weight": "normal"
        }
      ]
    }
  ]
}

Good assertions are:

• Objectively verifiable (yes/no, not "is it good?")
• Testing a specific rule from the SKILL.md
• "weight": "critical" for the most important behaviors

6. Step-by-Step: Creating a New Skill

1. Decide the host stack repo — apply Section 1's transversal-vs-product test. Open the right repo locally; if it isn't cloned, get it via wsp doctor or git clone.
2. Define the name — snake_case, descriptive (e.g., verify_security). Add product suffix if needed (Section 1).
3. Write the description — hyper-specific (Section 4).
4. Structure as a recipe — sequential steps, not a general overview.
5. Create SKILL.md at <stack-repo>/skills/<name>/SKILL.md.
6. Create evals.json immediately after at <stack-repo>/skills/<name>/evals/evals.json.
7. Commit + push to the stack repo. From this point, any workspace running wsp sync (or wsp bootstrap) picks the skill up automatically.
8. Verify the skill appears in VS Code Open Agent Manager after Reload Window in any workspace that consumes that stack.

7. When to create a new skill vs. update an existing one