Menu
How to create effective Transformers skills — structure, progressive disclosure, bundled resources, testing.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Auto-checks project context, logs activity via scribe, and manages the activity log and artifact directories. Loaded by Optimus and Megatron on every command.
Silent logger skill. Provides Scribe agent with rules for activity logging, memory writes, and report generation within .claude/transformers/.
Deep git and VCS knowledge — worktrees, branching, rebase, conflict resolution, PR review, bisect, release workflow.
Decision intelligence system — agents learn decision rules from every task. Not a cache. Only stores what changes future behavior.
Guided introduction to Transformers for new users — what it is, how to use it, what each agent does.
Pre-completion self-check for all builder agents. Run before marking any task done.
| name | extending-transformers |
| description | How to create effective Transformers skills — structure, progressive disclosure, bundled resources, testing. |
| user-invocable | false |
A skill injects reusable knowledge into one or more agents. It is not an agent. It is not a command. It is a protocol — a set of rules that changes how an agent behaves when that skill is loaded.
Every skill lives in its own directory under plugins/transformers/skills/. The directory must contain a SKILL.md file. Additional .md files in the same directory can be bundled and referenced from SKILL.md.
skills/
my-skill/
SKILL.md ← required, the skill manifest
reference.md ← optional, bundled content
examples.md ← optional, more bundled content
SKILL.md frontmatter schema:
---
name: my-skill # kebab-case, matches directory name
description: One sentence. What this skill teaches and when it applies.
user-invocable: true|false # true = users can load it manually
---
Reference bundled files using the plugin root variable:
@${CLAUDE_PLUGIN_ROOT}/skills/my-skill/reference.md
Skill — reusable protocols that apply to specific contexts. Examples: how to write migration plans, how to use git worktrees, how to structure API endpoints. Injected into agents that need that knowledge.
Agent — a persona with tools, a model, and a job. Bumblebee does UI. Ironhide does backend. An agent is a specialist. A skill makes a specialist better at something specific.
core-principles — universal rules that apply to every agent in every context. Human-in-the-loop, honesty, scope discipline, loop detection. If a rule should always be true for all agents, it belongs in core-principles, not a skill.
When in doubt: if the rule is situational (only relevant when doing X), it's a skill. If it's always true, it's core-principles. If it requires a tool and a persona, it's an agent.
Clear trigger conditions. The skill should say when it applies. "Use this when building REST endpoints" is clearer than "use this for backend work."
Progressive disclosure. Lead with the overview. Put details further down or in bundled files. Agents reading a 500-line skill will skim or miss things. Keep the main SKILL.md tight — 100-200 lines is a good target.
Concrete over abstract. "Use RETURNING id in INSERT statements" beats "write efficient SQL." Rules that agents can follow mechanically are better than principles they have to interpret.
Bundled resources for depth. If the skill needs examples, checklists, or reference tables, put them in separate files and reference them. The main SKILL.md should read like a briefing, not a textbook.
Use kebab-case. Prefer verb-noun format:
using-git-worktreeswriting-planswriting-migrationsreviewing-prsNoun-only names are acceptable when the skill is a reference rather than a protocol: api-conventions, test-patterns.
In the agent's .md frontmatter, add a skills list:
---
name: ironhide
model: claude-sonnet-4-5
skills:
- core-principles
- writing-migrations
- api-conventions
---
Skills are injected in order. Later skills can override or extend earlier ones. Put core-principles first — always.
Spawn a subagent with the skill loaded and give it a task that exercises the skill. Check if the behavior is different from an agent without the skill.
Example test prompt: "You have the writing-migrations skill loaded. Write a migration that adds an index to the users table." Then compare output to the same prompt without the skill.
If the skill works, the agent's output should visibly reflect the rules in the skill. If it doesn't change behavior, the skill is too vague.
Too long. If SKILL.md exceeds 300 lines, break it up. Move examples to bundled files. Nobody reads a wall of text under pressure.
Too vague. "Write clean code" is not a skill rule. "Extract functions longer than 20 lines" is. Make rules actionable.
Duplicating core-principles. Don't re-state "wait for human approval before destructive actions." It's already in core-principles. Duplication creates drift — someone will update one but not the other.
Replacing agents. A skill that says "you are now a database expert" is wrong. Skills augment specialists. They don't replace them. Ratchet is the database expert. A skill teaches Ratchet how to handle a specific migration pattern.
Transformers is multi-agent orchestration with named specialists. Skills reinforce this by making specialists better at specific tasks — not by turning generalists into specialists.
When writing a skill, ask: which agent does this skill make more effective? Wire it to that agent. If the answer is "all agents," it probably belongs in core-principles.