# [Skill Name] Version: 0.1.0 Status: CANDIDATE ## Purpose Describe the reusable job this skill performs. A good purpose answers: ```text What class of problem does this skill solve? ``` Keep the purpose specific. Avoid vague purposes such as: ```text "Help with development." ``` Prefer: ```text "Safely import delimited text files into Microsoft Access while validating schema, row counts, errors, and rollback conditions." ``` --- # 1. Trigger Conditions Use this skill when: * [trigger] * [trigger] * [trigger] Do not use this skill when: * [non-trigger] * [non-trigger] Trigger conditions should make it obvious when an agent should load the skill. --- # 2. Inputs Required inputs: ```text INPUT 1: Description INPUT 2: Description ``` Optional inputs: ```text OPTIONAL INPUT 1: Description ``` If an input can be discovered from the project, inspect the project before asking the user. --- # 3. Preconditions Before executing this skill, verify: ```text [ ] required inputs exist [ ] relevant project instructions have been read [ ] required tools or dependencies are available [ ] destructive actions have appropriate safeguards [ ] assumptions are documented ``` Add domain-specific preconditions when necessary. --- # 4. Output Contract The skill should produce: ```text OUTPUT 1 OUTPUT 2 OUTPUT 3 ``` Define what success looks like. Avoid vague output descriptions such as: ```text "Provide a good solution." ``` Prefer: ```text "Produce a verified PowerShell script, list required permissions, provide rollback steps, and report the exact verification commands used." ``` --- # 5. Procedure Follow this process. ## Step 1 — Discover Inspect: * relevant files * existing implementations * configuration * dependencies * tests * documentation Do not assume project facts that can be discovered. --- ## Step 2 — Understand Identify: ```text OBJECTIVE CURRENT STATE DESIRED STATE CONSTRAINTS DEPENDENCIES RISKS ``` --- ## Step 3 — Execute Describe the reusable procedure. Example: ```text 1. validate input 2. inspect destination 3. prepare change 4. execute change 5. capture result 6. verify ``` Keep steps concrete and executable. --- ## Step 4 — Verify Define verification methods. Prefer: ```text automated test build static analysis query command output row-count comparison smoke test direct inspection ``` A skill without verification is incomplete. --- ## Step 5 — Handle Failure If verification fails: ```text STOP CAPTURE ERROR IDENTIFY FAILURE POINT DIAGNOSE CORRECT ROOT CAUSE RETRY VERIFICATION ``` Do not continue as though the operation succeeded. --- # 6. Decision Rules Add decision rules when the procedure contains branches. Example: ```text IF destination exists inspect compatibility IF destination does not exist create it IF schema differs stop and reconcile mapping IF import errors occur capture rejected rows ``` Prefer explicit decisions over vague instructions. --- # 7. Safety Rules Document any important safety boundaries. Examples: ```text do not delete source data before verification do not overwrite production configuration without backup do not log secrets do not disable security controls to make a procedure work do not perform destructive migration without rollback ``` Remove this section if the skill has no meaningful safety considerations. --- # 8. Failure Handling Known failure classes: ## Failure Type 1 Symptoms: ```text ... ``` Likely cause: ```text ... ``` Response: ```text ... ``` --- ## Failure Type 2 Symptoms: ```text ... ``` Likely cause: ```text ... ``` Response: ```text ... ``` Do not attempt to list every theoretical failure. Document recurring or high-impact failures. --- # 9. Verification Checklist Before considering this skill complete: ```text [ ] required inputs validated [ ] procedure completed [ ] output exists [ ] expected behavior verified [ ] errors checked [ ] regressions considered [ ] destructive changes validated [ ] result communicated clearly ``` Customize this checklist for the skill. --- # 10. Examples ## Example 1 — Normal Case ### Input ```text ... ``` ### Process ```text ... ``` ### Expected Output ```text ... ``` --- ## Example 2 — Edge Case ### Input ```text ... ``` ### Expected Handling ```text ... ``` Examples are optional when the procedure is already obvious. They are strongly recommended for complex skills. --- # 11. Interaction Rules Specify whether this skill should: ```text run autonomously ask questions pause before destructive action operate interactively produce a complete result ``` Example: ```text Ask only when a critical variable cannot be discovered. Do not ask for confirmation for reversible low-risk steps. Require explicit user approval before destructive production changes. ``` --- # 12. Tool Guidance If the skill commonly uses specific tools, describe them here. Example: ```text Prefer repository search before broad file reads. Use build/test tools when available. Use database queries to validate imported row counts. Use version-control diff inspection before completion. ``` Do not hard-code tools unless they are truly part of the skill. --- # 13. Related Skills Related skills: ```text .ai/skills/[skill]/SKILL.md ``` Use related skills rather than duplicating their full procedures. Example: ```text Use mirror-audit before high-risk implementation. Use red-team after verification. Use retrospective after substantial work. ``` --- # 14. Self-Improvement Rules This skill may be improved when: ```text a recurring failure is discovered a step is repeatedly unclear a better verification method is found a project pattern becomes reusable the procedure produces unnecessary work ``` Before changing this skill: ```text 1. capture evidence 2. identify the failure or improvement 3. make the smallest useful edit 4. test the revised procedure 5. update the version 6. update this changelog 7. update .ai/CHANGELOG.md when appropriate ``` Do not expand the skill based only on speculative edge cases. --- # 15. Versioning Use: ```text PATCH ``` for: * clarification * typo * small missing check Use: ```text MINOR ``` for: * new behavior * new procedure branch * new verification method Use: ```text MAJOR ``` when: * purpose changes * trigger changes incompatibly * output contract changes incompatibly * the skill is fundamentally redesigned --- # 16. Changelog ## 0.1.0 Initial candidate skill. ### Evidence [What real work justified creating this skill?] ### Verification [How was the skill tested?] ### Result PENDING