matt-skills-with-to-goal

Skills are organized into bucket folders under skills/:

• engineering/: daily code work
• productivity/: daily non-code workflow tools
• misc/: kept around but rarely used, not promoted
• in-progress/: beta: public on purpose, feedback wanted, not shipped in the plugin
• deprecated/: historical source excluded from default distribution; old human docs live under docs/archived/

Every skill in engineering/ or productivity/ (the promoted buckets) must have a reference in the top-level README.md and an entry in .claude-plugin/plugin.json's skills array (the Claude Code plugin ships exactly the promoted set). Skills in misc/, in-progress/, and deprecated/ must not appear in either.

Install commands are copied verbatim from .agents/install-block.md. .claude-plugin/marketplace.json makes this fork its own single-plugin marketplace. Run claude plugin validate . --strict after touching either manifest. The upstream managed-install evidence and this fork's distinct installation routes live in .agents/adr/0002-ship-as-a-claude-code-plugin.md.

Each skill entry in the top-level README.md must link the skill name to its SKILL.md.

Each bucket folder has a README.md that lists every skill in the bucket with a one-line description, with the skill name linked to its SKILL.md. The promoted buckets' README.mds and the top-level README.md group entries into User-invoked and Model-invoked; non-promoted bucket README.mds (misc/, in-progress/) use a flat list.

Skills in engineering/ and productivity/ also have a human-facing docs page at docs/<bucket>/<skill-name>.md (the docs tree mirrors those two bucket folders under skills/). The published URL is https://aihero.dev/skills-<skill-name> regardless of bucket: the docs path is repo organisation only. When you add, rename, or change the behaviour of a skill in engineering/ or productivity/, create or re-sync its docs page following .agents/writing-docs.md. A finished page carries four sections: What it does, When to reach for it, Common questions, and It's working if. writing-docs.md holds the template, the section order, and where to hunt for the questions. Skills in the non-promoted buckets (misc/, in-progress/, deprecated/) get no docs page.

Every SKILL.md is either user-invoked (disable-model-invocation: true plus policy.allow_implicit_invocation: false in agents/openai.yaml, reachable only by the human) or model-invoked (model- or user-reachable). See .agents/invocation.md.

To (re)link every skill outside deprecated/ and misc/ into the local harness skill directories (~/.claude/skills, ~/.agents/skills), run scripts/link-skills.sh. Each entry is a symlink into this repo, so a git pull keeps installed skills current; re-run the script after adding, removing, or renaming a skill.

Rejected directions get archived, not merely decided. When this fork turns down a skill direction or a design — its own calls, not only upstream feature requests — record it in .out-of-scope/ under the convention triage already follows (skills/engineering/triage/OUT-OF-SCOPE.md): one file per concept, kebab-case concept name. The reason must be durable — scope, mechanism, or cost, never a temporary circumstance, because a decision resting on the current moment is a deferral rather than a rejection. Never record something that was in fact built; a false rejection poisons the concept matching that makes the directory worth reading.

Before syncing upstream, publishing to origin, or refreshing local installs, read docs/maintaining-fork.md. It covers review merges, bounded diff inspection, skill/doc consistency, and validation before publication.

Independent research or review subagents start with a fresh context window and receive the evidence pointers their task needs. Deliberate execution-chat forks, such as execute-spec-in-fork, still inherit the approved conversation; they serve a different context boundary.

Use plain punctuation in repository prose, consistent with upstream: rewrite sentences with commas, colons, periods, parentheses, or conjunctions.