Skip to main content
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 and the backend / frontend rulesets.
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.

​
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 followA specific task run on request
”New files use declare(strict_types=1)""Scaffold a new DDD module under src/”
Passive knowledgeAn 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: 
---
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:
FieldPurpose
nameDisplay label in skill listings. Defaults to the directory name.
descriptionThe trigger. What the skill does and when to use it. Claude reads this to decide whether to invoke the skill.
when_to_useExtra triggering context, appended to the description (shares the same character budget).
allowed-toolsTools Claude may use without a permission prompt while the skill is active.
disable-model-invocationtrue = the skill only runs when a human types /name (good for destructive or deploy-style tasks).
argument-hintAutocomplete hint, e.g. [module-name].
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.

​
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.
# 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

1

One clear job

A skill does one task well. If it branches into several unrelated tasks, split it.
2

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.
3

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.
4

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.
5

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.
6

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).

​
Where skills live

ScopePathUse for
Project.claude/skills/<name>/SKILL.mdTeam skills — commit these to the repo so everyone (and CI agents) get them.
Personal~/.claude/skills/<name>/SKILL.mdYour own experiments, across all projects.
Plugin<plugin>/skills/<name>/SKILL.mdSkills distributed via a plugin, namespaced plugin:name.
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.

​
How to add a skill

1

Create the directory

In the target repo (sevendays_backend or the Angular app):
mkdir -p .claude/skills/scaffold-module
2

Write SKILL.md

Add the frontmatter (at least a strong description) and the step-by-step instructions. Keep it under ~500 lines.
3

Add supporting files

Drop any templates, examples, or scripts into the skill directory and reference them from SKILL.md.
4

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.
5

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.
Skills follow the open Agent Skills 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.

​
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.