# Skill Creator ## Purpose Author a new Agent skill that fits this repository's conventions and ships ready for review. Focus on: - consistent frontmatter and section layout - behavior aligned with `skill-check.config.json` limits - clear Use when, Execution, and Done when sections - no duplication with existing skills --- ## Constraints - Apply `@rules/php/core-standards.mdc` **only once it is established that the skill being created targets PHP code work in a PHP project** — skip it for a stack-agnostic or non-PHP skill; do not load the PHP standards when the new skill does not touch PHP. - Apply `@rules/git/general.mdc` - Output must be in English - Do not modify other skills, rules, or production code - Do not duplicate an existing skill — extend or refactor instead - Never add behavior beyond what the requested skill needs --- ## Use when - A new Agent skill must be added to `skills/` for an AI agent workflow - An existing workflow that lives only in chat history should be promoted to a reusable skill - The user asks to "create a skill", "add a skill", or "scaffold a skill" --- ## Inputs the agent must collect Before generating any file, gather: - **Skill name** — kebab-case, ≤ 64 chars, unique under `skills/` - **Purpose** — one sentence describing what the skill does - **Trigger phrase** — the "Use when …" wording for the description - **Scope** — read-only review, code change, refactor, delivery, or other - **Required rules** — which `rules/**/*.md*` files the skill must apply - **Integrations** — issue tracker, GitHub, MySQL, Telescope, etc. (or none) - **Output expectations** — markdown report, code change, PR comment, etc. If running interactively, confirm the inputs with the user. If running autonomously (e.g. invoked by `resolve-issue` or a scheduled workflow), infer the inputs from the triggering issue / PR description and state the assumptions in the final summary. --- ## Execution ### 1. Discover existing skills - List `skills/` and read any skill whose name overlaps semantically with the request. - If an existing skill already covers the workflow, stop and propose an update to that skill instead of creating a new one. ### 2. Choose the slug and location - Slug must be kebab-case, ≤ 64 chars, and not collide with an existing folder under `skills/`. - Create `skills/<slug>/SKILL.md`. Add subfolders (`templates/`, `references/`) only when the skill genuinely needs them. ### 3. Write the frontmatter Required keys: ```yaml --- name: <slug> description: "Use when <trigger phrase>. <one sentence on scope>." license: MIT metadata: author: "Petr Král (pekral.cz)" --- ``` Rules from `skill-check.config.json`: - `description`: 50–1024 chars; should start with "Use when" - `name`: ≤ 64 chars - Body: ≤ 500 lines and ≤ 5000 tokens ### 4. Compose the body The repo accepts two body layouts. Pick one and stay consistent within the file. **Layout A — Constraints-first (preferred for new skills):** 1. `## Constraints` — applied rules and hard limits (one bullet per item) 2. `## Use when` — concrete triggers 3. `## Required approach` or `## Execution` — numbered steps the agent must follow 4. `## Output` or `## Output Format` — structure of what the skill returns 5. `## Done when` — verifiable completion criteria Examples in the repo: `refactor-entry-point-to-action`, `smartest-project-addition`, `test-driven-development`, `test-like-human`, `security-review`. **Layout B — Title + Purpose (legacy, still acceptable):** 1. `# <Title Case Name>` 2. `## Purpose` — one short paragraph plus a bullet list of focus areas 3. `## Constraints` 4. `## Execution` 5. `## Output` or `## Output Format` 6. `## Principles` — short guiding rules (optional) 7. `## Done when` Examples in the repo: `code-review`, `class-refactoring`, `create-test`, `analyze-problem`. Omit a section only when it does not apply. ### 5. Reference rules and other skills - Reference rule files as `@rules/<area>/<file>.mdc` or `.md` exactly as they exist on disk. - Reference other skills as `@skills/<slug>/SKILL.md`. - Never invent paths. Verify every reference points to a real file before saving. ### 6. Keep behavior minimal - One skill, one workflow. Split into separate skills if the scope grows. - Do not paste rule content into the skill — link to it. - Do not add humanizer, marketing, or third-party links unless the user requests them. --- ## Quality Gates Run before declaring the skill done: - `composer skill-check` — must report `PASS` with no warnings on the new file - If `skill-check` flags an auto-fixable warning, run `npx skill-check check skills/<slug> --fix --no-security-scan` (path-scoped) instead of `composer skill-check-fix`, which rewrites every skill in the tree and can pollute the diff with unrelated formatting changes - `composer build` — full project build (must finish without errors) Do not silence checks; fix the SKILL.md content until the report is clean. --- ## Repository updates After the new SKILL.md passes validation: - Add a `CHANGELOG.md` entry under `[Unreleased]` describing the new skill and referencing the issue (e.g. `(#432)`). - Update `README.md`: - bump the skill count in the "Skills Overview" header and the "Why This Package" bullet - add the new skill to the appropriate table (Issue Resolution, Code Review, Testing, Platform & Data, etc.) Skip the README update only when the skill is intentionally internal and not part of the public catalog — state this explicitly in the PR description. --- ## Output - New file: `skills/<slug>/SKILL.md` - Updated `CHANGELOG.md` and `README.md` - Short summary covering: - chosen slug and scope - rules and skills referenced - skill-check result - follow-up tasks (e.g. tests for code that the skill orchestrates) if any --- ## Principles - Reuse existing skills before adding new ones - Keep each skill narrow and composable - Prefer explicit steps over vague guidance - Verify every `@rules/*` and `@skills/*` reference exists - Let `skill-check` be the source of truth for SKILL.md quality --- ## Done when - `skills/<slug>/SKILL.md` exists with valid frontmatter and required sections - `composer skill-check` passes with no warnings on the new file - `composer build` finishes without errors - `CHANGELOG.md` and `README.md` reflect the new skill (or the omission is justified) - The summary lists the slug, references, and validation result ## Output Humanization - Use [blader/humanizer](https://github.com/blader/humanizer) for all skill outputs to keep the text natural and human-friendly.

Skill Creator

Purpose

Author a new Agent skill that fits this repository's conventions and ships ready for review.

Focus on:

consistent frontmatter and section layout
behavior aligned with skill-check.config.json limits
clear Use when, Execution, and Done when sections
no duplication with existing skills

Constraints

Apply @rules/php/core-standards.mdc only once it is established that the skill being created targets PHP code work in a PHP project — skip it for a stack-agnostic or non-PHP skill; do not load the PHP standards when the new skill does not touch PHP.
Apply @rules/git/general.mdc
Output must be in English
Do not modify other skills, rules, or production code
Do not duplicate an existing skill — extend or refactor instead
Never add behavior beyond what the requested skill needs

Use when

A new Agent skill must be added to skills/ for an AI agent workflow
An existing workflow that lives only in chat history should be promoted to a reusable skill
The user asks to "create a skill", "add a skill", or "scaffold a skill"

Inputs the agent must collect

Before generating any file, gather:

Skill name — kebab-case, ≤ 64 chars, unique under skills/
Purpose — one sentence describing what the skill does
Trigger phrase — the "Use when …" wording for the description
Scope — read-only review, code change, refactor, delivery, or other
Required rules — which rules/**/*.md* files the skill must apply
Integrations — issue tracker, GitHub, MySQL, Telescope, etc. (or none)
Output expectations — markdown report, code change, PR comment, etc.

If running interactively, confirm the inputs with the user. If running autonomously (e.g. invoked by resolve-issue or a scheduled workflow), infer the inputs from the triggering issue / PR description and state the assumptions in the final summary.

Execution

1. Discover existing skills

List skills/ and read any skill whose name overlaps semantically with the request.
If an existing skill already covers the workflow, stop and propose an update to that skill instead of creating a new one.

2. Choose the slug and location

Slug must be kebab-case, ≤ 64 chars, and not collide with an existing folder under skills/.
Create skills/<slug>/SKILL.md. Add subfolders (templates/, references/) only when the skill genuinely needs them.

3. Write the frontmatter

Required keys:

---
name: <slug>
description: "Use when <trigger phrase>. <one sentence on scope>."
license: MIT
metadata:
  author: "Petr Král (pekral.cz)"
---

Rules from skill-check.config.json:

description: 50–1024 chars; should start with "Use when"
name: ≤ 64 chars
Body: ≤ 500 lines and ≤ 5000 tokens

4. Compose the body

The repo accepts two body layouts. Pick one and stay consistent within the file.

Layout A — Constraints-first (preferred for new skills):

## Constraints — applied rules and hard limits (one bullet per item)
## Use when — concrete triggers
## Required approach or ## Execution — numbered steps the agent must follow
## Output or ## Output Format — structure of what the skill returns
## Done when — verifiable completion criteria

Examples in the repo: refactor-entry-point-to-action, smartest-project-addition, test-driven-development, test-like-human, security-review.

Layout B — Title + Purpose (legacy, still acceptable):

# <Title Case Name>
## Purpose — one short paragraph plus a bullet list of focus areas
## Constraints
## Execution
## Output or ## Output Format
## Principles — short guiding rules (optional)
## Done when

Examples in the repo: code-review, class-refactoring, create-test, analyze-problem.

Omit a section only when it does not apply.

5. Reference rules and other skills

Reference rule files as @rules/<area>/<file>.mdc or .md exactly as they exist on disk.
Reference other skills as @skills/<slug>/SKILL.md.
Never invent paths. Verify every reference points to a real file before saving.

6. Keep behavior minimal

One skill, one workflow. Split into separate skills if the scope grows.
Do not paste rule content into the skill — link to it.
Do not add humanizer, marketing, or third-party links unless the user requests them.

Quality Gates

Run before declaring the skill done:

composer skill-check — must report PASS with no warnings on the new file
If skill-check flags an auto-fixable warning, run npx skill-check check skills/<slug> --fix --no-security-scan (path-scoped) instead of composer skill-check-fix, which rewrites every skill in the tree and can pollute the diff with unrelated formatting changes
composer build — full project build (must finish without errors)

Do not silence checks; fix the SKILL.md content until the report is clean.

Repository updates

After the new SKILL.md passes validation:

Add a CHANGELOG.md entry under [Unreleased] describing the new skill and referencing the issue (e.g. (#432)).
Update README.md:
- bump the skill count in the "Skills Overview" header and the "Why This Package" bullet
- add the new skill to the appropriate table (Issue Resolution, Code Review, Testing, Platform & Data, etc.)

Skip the README update only when the skill is intentionally internal and not part of the public catalog — state this explicitly in the PR description.

Output

New file: skills/<slug>/SKILL.md
Updated CHANGELOG.md and README.md
Short summary covering:
- chosen slug and scope
- rules and skills referenced
- skill-check result
- follow-up tasks (e.g. tests for code that the skill orchestrates) if any

Principles

Reuse existing skills before adding new ones
Keep each skill narrow and composable
Prefer explicit steps over vague guidance
Verify every @rules/* and @skills/* reference exists
Let skill-check be the source of truth for SKILL.md quality

Done when

skills/<slug>/SKILL.md exists with valid frontmatter and required sections
composer skill-check passes with no warnings on the new file
composer build finishes without errors
CHANGELOG.md and README.md reflect the new skill (or the omission is justified)
The summary lists the slug, references, and validation result

Output Humanization

Use blader/humanizer for all skill outputs to keep the text natural and human-friendly.