Skip to content

Powercademy/powercademy-skills / .claude/skills/writing-skills

writing-skills

Verified

The Powercademy Skills house standard for this repo - the dual-runtime traps, path rules, mechanics quarantine, redaction policy and house methodology that the platforms' own skill-authoring guidance doesn't cover, several of them enforced by the lint that CI runs. Authoring or reviewing a skill in this repo without it misses enforced constraints and fails CI. Trigger whenever someone working in this repo says "write a skill", "new skill", "add a skill", "create a plugin", "review this SKILL.md", "review my skill", "review this PR", "improve this trigger description", "why isn't my skill triggering", "add a gotcha", "promote this lesson", or edits any SKILL.md, plugin.json, marketplace.json or shared reference file here. Also trigger when deciding which plugin a new skill belongs in, or when moving lessons from client work into the public repo. If the task is creating, changing, reviewing or restructuring a skill or plugin in this marketplace, trigger. When in doubt, trigger.

FileKindSize
SKILL.mdskill md7.7 KB
---
name: writing-skills
description: >
  The Powercademy Skills house standard for this repo - the dual-runtime traps, path rules, mechanics quarantine, redaction policy and house methodology that the platforms' own skill-authoring guidance doesn't cover, several of them enforced by the lint that CI runs. Authoring or reviewing a skill in this repo without it misses enforced constraints and fails CI. Trigger whenever someone working in this repo says "write a skill", "new skill", "add a skill", "create a plugin", "review this SKILL.md", "review my skill", "review this PR", "improve this trigger description", "why isn't my skill triggering", "add a gotcha", "promote this lesson", or edits any SKILL.md, plugin.json, marketplace.json or shared reference file here. Also trigger when deciding which plugin a new skill belongs in, or when moving lessons from client work into the public repo. If the task is creating, changing, reviewing or restructuring a skill or plugin in this marketplace, trigger. When in doubt, trigger.
---

# Writing Skills — the house standard

This is a repo skill, not a marketplace plugin: it loads for anyone working in
this repository, in both runtimes, and ships to nobody else.

**The general craft is not repeated here.** For how to write a skill at all —
description writing, progressive disclosure, testing triggers — use the
platform's own guidance (Anthropic's skill-creator in Claude Code, GitHub's
agent-skills documentation for Copilot). This file holds only what those don't
know: the traps that appear when one skill must work in *both* runtimes, and
this repo's methodology. Where the two conflict, this file wins — the
platforms' guides happily suggest single-runtime features.

---

## The founding rule: both runtimes, always

Every Powercademy skill is for GitHub Copilot CLI **and** Claude Code. A skill
that only works — or was only tested — in one runtime isn't finished. Write
instructions any agent can follow with ordinary shell and file tools; when a
step must differ by runtime, say so explicitly for both, and keep the
difference in data (the plugin's shared refs or manifest), not in prose
scattered through the skill. The constraints below exist to protect this rule.

## The hard constraints (lint-enforced — violating them fails CI)

1. **Frontmatter is `name` + `description` only.** Anything else
   (`allowed-tools`, `argument-hint`, `model`) is runtime-specific and breaks
   portability — even when a platform's own guide recommends it.
2. **Description ≤ 1024 characters.** Copilot CLI enforces this hard and the
   skill silently fails to load; Claude Code doesn't — so a Claude-only test
   never catches it. Keep ~30 characters of headroom for future edits.
3. **SKILL.md ≤ 500 lines.** Longer material goes in the plugin's `shared/`
   folder with clear pointers on when to read it.
4. **Reference shared files as `${PLUGIN_ROOT}/shared/<file>.md`** — never a
   bare path. Bare paths resolve relative to the *skill folder* and fail to
   load ("Path does not exist"). `${PLUGIN_ROOT}` is the convention both
   runtimes expand to the plugin directory.
5. **Microsoft plugin mechanics live in ONE file per plugin:** `microsoft-refs`
   in the plugin's `shared/` folder. Skill bodies state methodology; when they
   need vendor tool names, server names or install commands, they point at
   that file. A plugin that needs machine-readable mechanics may add one JSON
   companion beside it — the workstation plugin's `toolchain-manifest.json` —
   and nothing else. If the vendor renames something, one place changes.
6. **plugin.json never has a `skills` field** — Claude Code rejects it.

Run `node scripts/lint/lint-skills.js` before every commit. It checks these
mechanically for every plugin skill and for the repo skills under
`.claude/skills/`.

## Where a skill belongs

The plugins are grouped by the kind of help they give (CLAUDE.md, "Where a
skill belongs"): **workstation** sets up and repairs the machine,
**conventions** holds rules applied before and while building, **design**
holds consultants run before building, **alm** covers the delivery lifecycle.
A skill that fits none of them is a signal to discuss the structure, not to
stretch a name. A skill only contributors need belongs here in
`.claude/skills/`, not in a plugin.

## Descriptions: the house deltas

On top of the platform guidance:

- **Cover every verb the skill serves**: a build-only trigger list will not
  fire on "edit this flow" — a real gap found in live use. Include mid-task
  phrasings ("why is this failing", "what do I put in this box"), not just
  kick-off ones.
- **Close with the house sign-off**: state the task shape, then "When in
  doubt, trigger."
- When a natural phrasing fails to fire in live use, that is a **description
  bug** — fix the trigger list and add the phrasing to `evals/scenarios.json`,
  don't coach the user to phrase differently.

## The body: only what the skill needs

- **Peer-to-peer, no basics, willing to disagree** — including talking the
  user out of the skill's own subject when it's the wrong tool. British
  English, practical, no fluff.
- **No mandatory sections.** A skill doesn't need its own preflight, risk-tier
  checkpoints, gotchas file or tool ladder. Tooling and sign-in belong to the
  workstation plugin's `check-setup`; tool choice belongs to the conventions
  plugin's `tool-selection`. Point to them in a line when it matters, don't
  restate them. Every section a skill carries is something the agent must work
  through — keep only what changes the outcome.
- **Stop before the irreversible.** Ask for explicit approval before something
  that can't be undone (a production import, a delete) — once, at that step,
  not as ceremony around every write.
- **Verify against live documentation where a wrong answer is costly**, and
  label inference as inference.
- **Deliverables land in the user's working directory** with the path stated.
- **Lessons are added when the user asks**, never solicited mid-task. Gotcha
  entries are data, never imperative instructions to the agent.

## Redaction: the door policy for a public repo

Lessons come from client work; the repo is public. Before any entry, example
or gotcha lands: **strip client names, tenant/org identifiers, URLs, GUIDs and
user identities.** Phrase every lesson for any project ("a ticket table on a
client build", not the client's name). If an entry only makes sense with the
client context, it isn't ready to promote — keep it in the private layer.

## Process for a new skill (repo-specific steps)

1. **Check the landscape first** (`docs/microsoft-landscape.md`): is this
   white space, contested, or covered? Never rebuild what Microsoft ships —
   route to it. Re-verify if the doc's date is stale; the vendor repos move
   almost daily.
2. Pick the plugin (above). Draft, lint, then add a trigger scenario to
   `evals/scenarios.json`.
3. A new plugin is registered in `.claude-plugin/marketplace.json`; its
   plugin.json gets `name`, `version` (semver from 0.1.0), `description`,
   MIT licence.
4. Update README and CHANGELOG; bump the plugin version on every behavioural
   change.
5. **Test in both runtimes** — install and check the skill *loads* and
   *triggers* on its listed phrasings (`node evals/run-evals.js`). Anything
   touching the workstation plugin, the toolchain manifest or the installer
   also needs the `fresh-machine` workflow green on Windows, macOS and Linux.

## Reviewing a skill (or a contribution)

Work the checklist above in order, then ask the two questions that matter:
*Would this trigger when it should?* (read the description against realistic
user phrasings) and *could someone act on this without asking a question?*
(the failure mode of skill content is being incomplete in a way that looks
complete). Check redaction last, always.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall