// Conventions, anti-patterns, and meta-patterns for writing skills (and the shared agent/skill philosophy). Use when creating or editing a SKILL.md file, or when reviewing the agent-vs-skill separation. For the procedural workflow that generates a new agent file, use the agent-create skill (invoked by /agent-add).
| name | agent-skill-authoring |
| description | Conventions, anti-patterns, and meta-patterns for writing skills (and the shared agent/skill philosophy). Use when creating or editing a SKILL.md file, or when reviewing the agent-vs-skill separation. For the procedural workflow that generates a new agent file, use the agent-create skill (invoked by /agent-add). |
| role | worker |
| user-invocable | true |
This skill defines the philosophy of the agent-vs-skill split and the conventions for writing skills. Agents own orchestration logic (when and why); skills own execution knowledge (how). This separation keeps agents readable as workflow definitions while keeping capabilities DRY across the team.
Scope boundary:
agent-create skill — the procedural workflow for generating a new agent file (invoked by /agent-add)If you are creating an agent file, use /agent-add (which invokes the agent-create skill). This skill no longer duplicates that procedure.
references/templates.md)Agent (when + why) Skill (how)
┌─────────────────┐ ┌─────────────────┐
│ ## Skills │ │ # Skill Name │
│ - Skill A ──────│───────>│ │
│ "Invoke when │ │ ## Concepts │
│ designing │ │ ## Patterns │
│ bounded │ │ ## Guidelines │
│ contexts" │ │ ## Structure │
│ │ │ │
│ ## Behavioral │ │ (reusable by │
│ Guidelines │ │ any agent) │
│ (orchestration) │ │ │
└─────────────────┘ └─────────────────┘
Run /agent-add — it invokes the agent-create skill, which is the canonical procedure: name validation, type detection, scope-overlap check, body generation within token-efficiency budgets, /agent-audit validation gate, and registry/CLAUDE.md updates.
Do not hand-author agent files when /agent-add is available — divergent templates produced manually have historically drifted from the schema enforced by /agent-audit.
Place skill files at plugins/agentic-dev-team/skills/{skill-name}/SKILL.md. Use the skill template and authoring guidelines from references/templates.md. Then follow the registration checklist.
Before writing a new skill, read 2-3 existing skills in skills/ to absorb the project's voice and structure. Skills that follow existing patterns integrate better.
Explain the why, not just the what. LLMs follow rules more reliably when they understand the reasoning. "Do X because Y happens without it" beats "ALWAYS do X." Compare:
Include rationalization prevention. LLMs generate plausible excuses to skip hard steps. Add an "Excuses vs. Reality" table that pre-empts the common rationalizations for the skill's domain. This is the most effective compliance pattern in this project.
Use hard gates, not soft suggestions. "Should" is ignored; "must, with evidence" is followed. Gate pattern: require tool output (paste the result) as proof that a step was completed. Without evidence, the agent cannot proceed.
Constrain scope explicitly. Skills that try to cover everything get applied inconsistently. Define clear boundaries: what this skill covers, what it doesn't, and what adjacent skills handle the rest.
Test against the forgetting curve. Skills are most likely to be skipped when the agent is deep in implementation and eager to deliver. Front-load the most critical constraints in the skill's ## Constraints section — they're read first and remembered longest.
Apply TDD to skill-writing itself.
Optimize skill descriptions for triggering. The description field in frontmatter determines whether the skill gets invoked. Descriptions that summarize the workflow cause the agent to follow the description instead of reading the full skill. Descriptions should contain triggering conditions only — when should I use this? — not workflow summaries.
After creating an agent or skill, follow the registration checklist in references/templates.md. For agents, /agent-add performs registration automatically; for skills and slash commands, follow the manual steps. Incomplete registration leaves the system in an inconsistent state.
Every change must be reflected in documentation. See the sync policy and source-of-truth table in references/templates.md.
New or updated plugins/agentic-dev-team/skills/*/SKILL.md file(s) with all registry tables and docs updated. Be concise — confirm what was created/updated and its registration status.
| Anti-Pattern | Problem | Fix |
|---|---|---|
| Skill logic embedded in agent | Duplicated across agents, hard to update | Extract to a skill file, reference from agent |
| Agent behavior embedded in skill | Skill becomes role-specific, can't be reused | Move persona/judgment logic to the agent |
| Skill without any agent reference | Orphaned knowledge, never invoked | Add to relevant agents or remove |
| Agent without Skills section | All knowledge is inline, nothing is reusable | Identify extractable capabilities |
| Overly broad skill | Tries to cover too much, hard to reference precisely | Split into focused skills |
| Hand-authoring an agent file | Drifts from the schema enforced by /agent-audit | Use /agent-add (invokes the agent-create skill) |
Create new Claude Code sub-agent files following the official schema and token-efficiency budgets. Handles both review agents (JSON output, read-only tools, ≤ 40-line body) and team agents (prose output, action tools, ≤ 75-line body). Use when the user says "add an agent", "create a reviewer for X", "new team agent for Y", or when /agent-add is invoked. Validates against /agent-audit before writing. Updates the agent registry and CLAUDE.md after success.
Detect business logic reimplemented in multiple architectural layers. Builds a persistent computation-register.json by annotating non-trivial computation functions with structured semantic descriptions, then clusters entries to surface duplicate domain concepts. Runs in full-scan mode on first use, incremental (git-diff-based) mode on subsequent runs. Use when the user wants to find logical duplication that linters and diff-scoped review agents miss — the same domain calculation independently reimplemented across layers.
Pattern-table mapping from unified findings to regulatory citations (PCI-DSS, GDPR, HIPAA, SOC2). LLM edge annotator invoked only for llm_review_trigger=true rows.
Hybrid FP-reduction — joern when present, LLM fallback when absent. Six-stage rubric (Stage 0 + Stages 1-5) applied to every finding; emits the disposition register.
Declarative phase graph for /security-assessment. Phases run in fixed order with dependency enforcement; per-phase artifacts land in memory/ and feed the next phase.
Collaborative workflow for producing the four specification artifacts (intent, BDD scenarios, architecture notes, acceptance criteria) before any implementation begins. Use when starting any new feature or behavior change — do not write code until artifacts pass the consistency gate.