Skill Maker

Author

Check existing owners before adding a capability. Give the skill one coherent outcome, a trigger description, necessary domain facts, interfaces, invariants, evidence and a done condition. Let the host choose valid methods. Include an ordered procedure only when its order is itself required and explain why. Keep firm and project facts in their owning workspace; link to governing sources rather than copying them.

Create SKILL.md and a short human-facing README.md. For a host without a native maker, adapt the bundled SKILL example and README example; use them as examples, not mandatory prose or sequence. Use a kebab-case name matching the directory. Describe both what the skill does and when to use it. Include allowed-tools only when supported and needed by the selected host. Do not embed ~/ paths. For code, zoning or life-safety analysis retain the canonical disclaimer and <!-- architecture-studio:requires-disclaimer --> marker as required by the rules.

For any files created or changed, follow the native mutation sequence for the complete affected set, including existing bytes, access, recovery, stale-write protection and fresh readback. Before any destination write, durably retain and separately reopen the complete original and prepared file/access set, including README and any requested validation report. Publish complete bytes with no-clobber or stale-write protection, then reopen and check the entire affected set. Inspect incomplete attempts before retries. Do not treat preparation as a new user approval gate. Stop before mutation when required access or recoverable publication is unavailable.

Verify and finish

Run the host maker's checks when available. Independently apply skill_scaffold.validate semantics: the directory is kebab-case; readable README.md and UTF-8 SKILL.md exist; the latter starts with delimited YAML frontmatter whose safely parsed mapping has a matching name and nonblank description; no ~/ occurs anywhere. A missing YAML parser leaves that check unverified, never passed. Accept exactly {"directory": "<selected path>"} with a required string and no extra fields; require regular readable files and a directory matching [a-z0-9]+(?:-[a-z0-9]+)*. Frontmatter begins at the first byte with --- and LF or CRLF, closing on a separate --- line followed by newline or end of file. On success, report {"valid": true, "directory": "<actual input path>", "name": "<directory name>"} only after actual destination readback; on failure identify the failing check, fix only authorized files and rerun the complete check. The validator is read-only. This structural check does not prove discovery, policy access or usefulness. Review the whole bundle for the applicable live-reference step, README dependency, policy privacy and destination/publication constraints.

For a catalog contribution, run repository lint in the verified source checkout and relevant focused tests; check catalog membership and host contracts. A private skill need not run catalog lint. If behavior is uncertain, compare representative tasks with and without the skill; report observed value, not an assumed lift. Report the paths, invocation ($name on Codex, /{name} privately or /as:{name} in the Claude catalog), checks and any incomplete verification. Do not commit unless requested.