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

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