> ## Documentation Index
> Fetch the complete documentation index at: https://docs.internal.sevencanyon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude skills

> How to author, add, and maintain Claude skills for the 7days codebase

A **skill** is a reusable, self-contained instruction packet that teaches Claude (Claude
Code and any Claude-based agent) how to do a specific task the 7days way — scaffold a
Symfony module, generate a migration across the four databases, write a Foundry factory,
open a PR to our conventions. This page is the standard for writing them so they stay
consistent with the [AI manifesto](/development/ai/manifesto) and the
[backend](/development/ai/backend-rules) / [frontend](/development/ai/frontend-rules)
rulesets.

<Info>
  Skills use **progressive disclosure**: only the skill's `name` + `description` sit in
  context at all times, the `SKILL.md` body loads when the skill is triggered, and bundled
  files (templates, scripts, references) load only when Claude reaches for them. So a skill
  can carry a lot of detail while costing almost nothing until it's used.
</Info>

## When to write a skill

A skill is the right tool for a **repeatable, multi-step task with a known procedure**.
Prefer the rulesets for always-on conventions, and a skill for on-demand workflows.

| Use a **ruleset** (`/development/ai/…`)        | Use a **skill**                                     |
| ---------------------------------------------- | --------------------------------------------------- |
| Always-on conventions every change must follow | A specific task run on request                      |
| "New files use `declare(strict_types=1)`"      | "Scaffold a new DDD module under `src/`"            |
| Passive knowledge                              | An active procedure with steps, commands, templates |

If you find yourself pasting the same multi-step prompt more than twice, turn it into a
skill.

## Anatomy of a skill

A skill is a directory containing a `SKILL.md` file, plus any supporting files it
references:

```
scaffold-module/
├── SKILL.md              # required: frontmatter + instructions
├── templates/
│   └── services.yaml     # loaded only when the skill needs it
└── scripts/
    └── check.sh
```

`SKILL.md` is Markdown with a YAML frontmatter header:

```markdown theme={null}
---
name: Scaffold module
description: >-
  Scaffold a new DDD module under src/ with its own config, following the
  IGaming reference layout. Use when adding a bigger backend feature that
  should own its Domain / Application / Infrastructure layers.
allowed-tools: Read, Write, Edit, Bash
---

# Scaffold a backend module

1. Create `src/<Module>/` with `Domain/`, `Application/`, `Infrastructure/`.
2. Add `config/services.yaml` and `config/packages.yaml` from `templates/`.
3. Wire the module config into the app config via `imports`.
4. Keep cross-module access behind a facade (see BE-MOD-02, BE-MOD-03).
...
```

### Frontmatter fields

All fields are optional, but a good `description` is what makes a skill discoverable.
Common ones:

| Field                      | Purpose                                                                                                             |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `name`                     | Display label in skill listings. Defaults to the directory name.                                                    |
| `description`              | **The trigger.** What the skill does and *when* to use it. Claude reads this to decide whether to invoke the skill. |
| `when_to_use`              | Extra triggering context, appended to the description (shares the same character budget).                           |
| `allowed-tools`            | Tools Claude may use without a permission prompt while the skill is active.                                         |
| `disable-model-invocation` | `true` = the skill only runs when a human types `/name` (good for destructive or deploy-style tasks).               |
| `argument-hint`            | Autocomplete hint, e.g. `[module-name]`.                                                                            |

<Note>
  The **slash command comes from the directory name**, not the `name` field — e.g.
  `.claude/skills/scaffold-module/SKILL.md` is invoked as `/scaffold-module`. Use a clear,
  kebab-case directory name.
</Note>

## Writing a good description

The `description` is the single most important line — it's the only part of the skill
always in context, and it's how Claude decides when to reach for the skill.

* Write it in the **third person**: "Scaffolds a…", "Generates a…".
* State **what it does *and* when to use it**, with the keywords a request would contain
  ("migration", "module", "factory", "endpoint").
* Be specific enough that it *doesn't* fire on unrelated requests.

```yaml theme={null}
# Good — action + trigger + keywords
description: >-
  Generates and reviews Doctrine migrations across all four databases using
  bin/db_diff. Use when a schema/entity change needs a migration.

# Too vague — will misfire or never fire
description: Helps with the database.
```

## What a good skill should have

<Steps>
  <Step title="One clear job">
    A skill does one task well. If it branches into several unrelated tasks, split it.
  </Step>

  <Step title="A concise SKILL.md (< ~500 lines)">
    Keep the body short and imperative — *what to do*, not an essay on why. Move long
    reference material into separate files the skill links to, so they load only when needed.
  </Step>

  <Step title="Explicit references to bundled files">
    Point at templates and scripts from the body ("use `templates/services.yaml`") so Claude
    knows what exists and when to load it.
  </Step>

  <Step title="Alignment with our standards">
    Cite the rules it must honour by ID (e.g. "follow BE-DB-04/BE-DB-05 for migrations") so the
    skill and the rulesets can't drift.
  </Step>

  <Step title="Scripts for anything deterministic">
    If a step is a fixed command or check, bundle a script and have the skill run it, rather
    than describing it in prose. Our diff gates (`bin/phpstan-diff.sh`, `bin/static.sh`) are
    good things to wire in.
  </Step>

  <Step title="A guardrail for risky work">
    For tasks that write migrations, touch auth/payments, or deploy, set
    `disable-model-invocation: true` so a human always initiates them (see the manifesto's
    "must not do unattended" list).
  </Step>
</Steps>

## Where skills live

| Scope        | Path                               | Use for                                                                          |
| ------------ | ---------------------------------- | -------------------------------------------------------------------------------- |
| **Project**  | `.claude/skills/<name>/SKILL.md`   | Team skills — **commit these to the repo** so everyone (and CI agents) get them. |
| **Personal** | `~/.claude/skills/<name>/SKILL.md` | Your own experiments, across all projects.                                       |
| **Plugin**   | `<plugin>/skills/<name>/SKILL.md`  | Skills distributed via a plugin, namespaced `plugin:name`.                       |

<Warning>
  Shared, team-facing skills belong **in the project repo** (`.claude/skills/`), reviewed
  like any other code. Keep one-off personal skills out of the repo.
</Warning>

## How to add a skill

<Steps>
  <Step title="Create the directory">
    In the target repo (`sevendays_backend` or the Angular app):

    ```bash theme={null}
    mkdir -p .claude/skills/scaffold-module
    ```
  </Step>

  <Step title="Write SKILL.md">
    Add the frontmatter (at least a strong `description`) and the step-by-step instructions.
    Keep it under \~500 lines.
  </Step>

  <Step title="Add supporting files">
    Drop any templates, examples, or scripts into the skill directory and reference them from
    `SKILL.md`.
  </Step>

  <Step title="Use it">
    Editing skills under `.claude/skills/` takes effect mid-session — no restart. Type
    `/scaffold-module`, or let Claude auto-invoke it when a request matches the description.
  </Step>

  <Step title="Review and commit">
    Open a PR like any change. A skill is code: it gets reviewed, and it must stay consistent
    with the rulesets it references.
  </Step>
</Steps>

<Note>
  Skills follow the open [Agent Skills](https://agentskills.io) standard, so the same
  `SKILL.md` works for other Claude-based agents and our MCP-connected tooling. To
  test-drive and tune a skill's description, the official `skill-creator` plugin from the
  Claude plugins marketplace can grade it against test cases.
</Note>

## Maintenance

* **Keep skills and rulesets in sync.** When a convention changes, update the skill in the
  same pull request as the standard it depends on.
* **Prune dead skills.** A stale skill that scaffolds the old way is worse than none — Claude
  will follow it confidently.
* **Prefer scripts over prose** for anything the team already automates, so the skill runs
  the same gates CI does.