engineer-skill

# Engineer Skill Use this skill to systematically improve agent skills by treating frontmatter optimization and prompt content optimization as two separate, composable concerns. Read `references/skill-structure-spec.md` for the complete directory layout and file conventions before starting. ## When to use this skill - The user wants to create a new agent skill from scratch. - The user wants to improve an existing skill's triggering accuracy (frontmatter). - The user wants to improve an existing skill's execution reliability (body content). - The user has a bloated SKILL.md and wants to restructure it with progressive disclosure. - The user wants to extract deterministic instructions from prose into executable scripts. - The user wants to validate a skill against the agentskills.io specification. - The user asks about skill best practices, structure, or conventions. Do not use this skill for general prompt engineering that is not tied to agent skill files. Use this skill only when the target artifact is a skill directory with a SKILL.md file or the user is creating one. ## Required inputs - The path to an existing skill directory, or a description of the skill to create. - The improvement focus: frontmatter (triggering), body (execution), structure, or all. - Any observed failure modes: under-triggering, over-triggering, inconsistent agent behavior, bloated context. ## Core workflow Follow this order: 1. **Validate** the skill structure and spec compliance by running `python scripts/validate_skill.py <skill-path>`. 2. **Analyze** the body for extraction opportunities by running `python scripts/analyze_skill_body.py <skill-path> --json`. 3. **Prioritize** improvements based on validation errors first, then analysis recommendations. 4. **Improve frontmatter** if triggering is the concern. Read `references/frontmatter-optimization.md` for guidance. 5. **Improve body content** if execution reliability is the concern. Read `references/prompt-content-optimization.md` for guidance. 6. **Extract deterministic work** to scripts when the analysis identifies sequential or mechanical instructions. 7. **Re-validate** after changes to confirm spec compliance. ## Two-concern separation ### Frontmatter (triggering concern) The frontmatter controls when agents discover and invoke the skill. Optimization targets: - Description wording and coverage of user intents. - Explicit trigger phrases and negative boundaries. - Name clarity and discoverability. Read `references/frontmatter-optimization.md` before making frontmatter changes. ### Body content (execution concern) The body controls what agents do after triggering. Optimization targets: - Instruction clarity and ordering. - Progressive disclosure through referenced files. - Extraction of deterministic logic to scripts. - Section sizing under recommended thresholds. Read `references/prompt-content-optimization.md` before making body changes. ## Output contract When improving a skill, structure the response as: 1. `Validation results`: output from the validation script 2. `Analysis results`: output from the analysis script 3. `Improvement plan`: prioritized list of changes 4. `Changes made`: specific edits with rationale 5. `Re-validation`: confirmation of spec compliance after changes