Skip to content

skill-authoring.md

Latest commit

 

History

History
86 lines (54 loc) · 5.81 KB

skill-authoring.md

File metadata and controls

86 lines (54 loc) · 5.81 KB
Raw

Skill Authoring

Skill Templates

Reusable scaffolds live in templates/ at the repo root (outside skills/, so they're never published, installed, or version-checked). Start a new skill by copying a template rather than authoring structure from scratch.

  • templates/coaching-skill/ — for a skill that coaches the user through a decision using one or more named frameworks and ends with a concrete artifact. This is the shape estack-leadership-coach and estack-productivity-prioritization-coach share. It defines the standard component set (identity → primary outcome → voice → calibrate depth → framework → coaching protocol → acceptance bar → handling resources → sources → feedback) and ships both reference tiers: a lightweight sources/ model and a heavier references/ knowledge vault with an adding-references.md playbook. Keep the tier you use, delete the other.

To instantiate: cp -r templates/coaching-skill skills/estack-<name>, rename SKILL.template.md → SKILL.md, fill the {{PLACEHOLDERS}}, resolve the tier files (rename adding-references.template.md or delete it; the sources template is a pattern to copy, then delete), then run node scripts/update-skill-feedback.cjs. No .template.md file may remain in the finished skill — it would ship to npm. Full instructions are in templates/README.md. The manage-e-stack add flow (steps/add.md) points here at step 1.

If a future skill is a different shape (a tool, converter, tracker), add a new template folder under templates/ rather than forcing it into the coaching scaffold.

Per-Skill Versioning

Every skill carries its own semver in SKILL.md frontmatter, independent of the package version in package.json:

---
name: estack-example
version: 1.2.0
description: >-
  (example) Use when the user asks for a concrete workflow. Use for: setup,
  repair, and verification. Trigger phrases: "fix this", "verify this".
---
  • New skills start at 1.0.0.
  • Bump on every content change to the skill folder (SKILL.md, scripts, references, steps): patch for fixes/tweaks, minor for new capabilities, major for rewrites or breaking changes.
  • Use folded YAML for long descriptions whenever the text contains Use for:, Triggers:, or any other colon followed by a space. Plain one-line YAML values cannot safely contain : unless quoted.
  • Hooks use a // @version x.y.z comment near the top of the file instead.
  • Enforcement: node scripts/check-versions.cjs diffs every skill/hook against the last v* release tag and fails if content changed without a version bump. Run --fix to auto-patch-bump stale items. The publish workflow (.github/workflows/publish.yml) runs this check as a hard gate, so a release cannot ship a content change with a stale version.
  • Division of labor: the installer detects updates via content hashes (deterministic, can't miss a change); versions are the trustworthy human-readable label — the installer shows name (1.0.0 → 1.1.0) transitions in its update messages, and the version travels with the installed copy so any machine can self-report what it has.

Doc Listings (README.md + CLAUDE.md)

Every skill and hook must be listed in two places:

  • README.md — a row in the Skills table (| **Title** | \/estack-name` | description |`) or the Hooks table
  • AGENTS.md — the "Skills in the pack" / "Hooks in the pack" lines

Enforcement: node scripts/check-docs.cjs verifies both files against skills/ and hooks/, failing on missing entries AND stale ones (renamed/removed items still listed). The publish workflow (.github/workflows/publish.yml) runs it as a hard gate, so the docs cannot drift past a release. It only checks names — keep descriptions accurate manually when a skill's purpose changes.

Skill Name Validation

node scripts/check-skill-name.cjs <skill-name> (or --all for every skill) verifies that a skill was migrated and self-references correctly. It checks:

  1. Folder is named skills/estack-<short>/
  2. Frontmatter name: matches the folder name exactly
  3. Frontmatter version: exists and is semver (x.y.z)
  4. Frontmatter description: starts with (<short>) — e.g. (repo-search) Use when…
  5. No bare short-name self-references inside the skill's own files — every mention of <short> must be prefixed estack-<short> or wrapped as (<short>) (the description convention)

Allowed exceptions: mentions inside references/ docs (prose about the skill's display name) and the (<short>) description prefix itself are not flagged as stale.

The publish workflow runs --all as a hard gate. Run it locally before tagging if you've renamed a skill or edited its frontmatter.

Skill Feedback Section

Every skill should include a ## Skill Feedback section at the bottom. This is managed via a shared template — do not edit it manually in individual skill files.

To update the feedback text across all skills:

  1. Edit scripts/skill-feedback-template.md (use {{SKILL_NAME}} as the placeholder for the skill's name)
  2. Run node scripts/update-skill-feedback.cjs — rewrites the section in every skills/estack-*/SKILL.md
  3. Verify with node scripts/update-skill-feedback.cjs --check (exits 1 if any skill is out of sync)

The feedback section instructs the AI to collect feedback details from the user, then file a GitHub issue via gh issue create (if available) or a pre-filled issue URL.

Auto-run commands

Use ```! (triple backtick + !) code blocks in SKILL.md to run shell commands automatically when the skill is loaded. The output is presented to the model before it processes the rest of the skill.

Use this for setup tasks, environment checks, or gathering context that the skill needs upfront.

Example:

  • skills/estack-repo-search/SKILL.md — clones and indexes a repo on load