diff --git a/plugins/engineering-playbook/skills/creating-skills/SKILL.md b/plugins/engineering-playbook/skills/creating-skills/SKILL.md new file mode 100644 index 0000000..f524b4c --- /dev/null +++ b/plugins/engineering-playbook/skills/creating-skills/SKILL.md @@ -0,0 +1,17 @@ +--- +name: creating-skills +description: >- + Creates, edits, and maintains agent skills and their referenced resources. + Use when creating a new skill, editing SKILL.md, changing skill frontmatter, + or modifying files referenced by a skill such as references, scripts, or + assets. +--- + +## Source + +Before creating or editing a skill or any file referenced by a skill, read: + +https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices + +Follow that guidance strictly. If the page cannot be read, report the blocker +before editing unless the user explicitly says to continue. diff --git a/plugins/engineering-playbook/skills/development/SKILL.md b/plugins/engineering-playbook/skills/development/SKILL.md index e03dcc9..e6930d6 100644 --- a/plugins/engineering-playbook/skills/development/SKILL.md +++ b/plugins/engineering-playbook/skills/development/SKILL.md @@ -16,6 +16,9 @@ source of truth. ## Load First - Read `coding-standards`. +- Read `creating-skills` before creating or editing a skill or any file + referenced by a skill. +- Read `pull-request` before creating or preparing a pull request. - Read `laravel-standards` before touching code that affects a Laravel application. @@ -71,20 +74,9 @@ format. ## Pull Request Gate -Create a pull request only when all of these are true: - -- implementation satisfies the request -- `Blocker` and `Normal` review findings are fixed -- unresolved `Low` findings have been shown to the user -- Mago passes without warnings or errors -- relevant tests pass -- the commit message and pull request title use Conventional Commits -- the pull request description is one short high-level plain-English paragraph - without technical details -- the pull request description includes `Closes #` when the work - resolves a GitHub issue, and does not mention any issue the pull request does - not resolve - -If any gate is not clean, do not create the pull request. Report what is done, -what failed, the commands run, and the question or decision needed from the -user. +Create a pull request only after the implementation is done, required review +findings are handled, Mago is clean, and relevant tests pass. Otherwise report +the blocker instead of opening the PR. + +When this gate is clean, follow `pull-request` to write the title and +description. diff --git a/plugins/engineering-playbook/skills/pull-request/SKILL.md b/plugins/engineering-playbook/skills/pull-request/SKILL.md new file mode 100644 index 0000000..0a74572 --- /dev/null +++ b/plugins/engineering-playbook/skills/pull-request/SKILL.md @@ -0,0 +1,22 @@ +--- +name: pull-request +description: >- + Writes and creates small GitHub pull requests with Conventional Commit titles, + concise descriptions, and issue-closing references. Use when opening, + drafting, publishing, or preparing a pull request. +--- + +# Pull Request + +## Workflow + +1. Use a short Conventional Commit title. Do not add an issue number to the title + unless the repository requires it. +2. Write one high-level plain-English paragraph for the body. Leave out + implementation details, test logs, file lists, checklists, and review notes + unless a repository template requires them. +3. When the PR resolves a GitHub issue, include `Closes #` in the + body. Use `Fixes #` only when that wording better matches the + work. Do not mention issues the PR does not resolve. +4. After creating the PR, verify the title and body. If a required issue-closing + reference is missing, update the PR body immediately.