{% extends "base.html" %} {% block title %}Submission examples — {{ config.INSTANCE_NAME }}{% endblock %} {% block content %}
← Back to upload

Submission examples

Each component (plugin, agent, skill, command) needs a description that names the trigger condition AND the action. Skills are the strictest case because Claude reads the description verbatim when deciding whether to invoke the skill. Examples below show the minimum bar plus what a strong submission looks like.

Why these limits?

Descriptions that are too short don't give the assistant enough to go on. Below is the minimum bar plus what a well-written submission usually looks like.
Field Minimum Recommended What it does
Skill / agent / plugin description {{ guardrail.min_description_chars|default(60) }} chars · {{ guardrail.min_distinct_words|default(5) }} distinct words 120–220 chars (one full sentence) Tells the assistant when to use the component and what it does. Showed on the marketplace tile so others can pick it.
Command description {{ guardrail.min_command_description_chars|default(25) }} chars · {{ guardrail.min_distinct_words|default(5) }} distinct words 40–100 chars Commands are one-verb actions ("run tests", "format code"). A short clear sentence is enough.
Skill / agent content body {{ guardrail.min_body_chars|default(200) }} chars 500–2000 chars The body explains what the component does once used: inputs it expects, outputs it produces, edge cases. The minimum is a "one paragraph" floor that catches stubs.
Two-step review. First we check length and word count to catch placeholders like TODO or description. Submissions that pass the length check then go to a substantive reviewer that judges whether the description is genuinely useful or just padded filler that hit the character count by accident.

Skill

skills/<name>/SKILL.md with YAML frontmatter and a body. The frontmatter description IS the trigger string Claude reads; the body explains how the skill works once invoked.
Rejected 
---
name: code-review
description: A reviewer skill
---

Reviews code.
Why it fails: description is 15 chars (floor 60), restates the name, body is 13 chars (floor 200). Claude can't decide when to invoke it.
Passes 
---
name: code-review
description: Use when reviewing pull requests to flag missing tests,
  weak assertions, brittle implementation-coupled tests, and edge
  cases the implementation forgot.
---

# Code review skill

Run this skill against the diff of an open pull request. It walks
the changed files and surfaces three categories of issues:

1. **Missing tests** — new functions / endpoints / migrations
   without corresponding test coverage.
2. **Weak assertions** — tests that exist but only assert truthy
   values, status codes, or shape without verifying the actual
   behavior contract.
3. **Brittle coupling** — tests that depend on private state,
   internal call counts, or implementation details that will break
   on refactor without catching real regressions.

## Inputs

The skill expects to be invoked from a git repo with a PR branch
checked out. It reads `git diff ..HEAD` to scope the review.

## Output

Markdown comment grouped by file, with line refs and one fix
suggestion per finding.
Why it passes: description names WHEN (PR review) and WHAT it does, body explains inputs/outputs.

Agent

Single .md file with YAML frontmatter. The description drives dispatch — when a parent agent decides which subagent to spawn, this is the string it reads.
Rejected 
---
name: debugger
description: A debugger
---

Helps with debugging.
Why it fails: description is 11 chars (floor 60), body is 22 chars (floor 200), neither names a dispatch criterion.
Passes 
---
name: debugger
description: Diagnoses test failures, runtime errors, and unexpected
  behavior. Use when a build is failing, a stack trace lands in the
  conversation, or the user describes a symptom without a known
  root cause.
---

# Debugger subagent

Triage flow:

1. Reproduce the failure deterministically (capture the exact
   command + working directory + relevant env).
2. Reduce — strip the case down to the smallest input that still
   fails. Confirm the reduction reproduces.
3. Bisect or trace, depending on whether the regression is recent
   or the behavior was never correct.
4. Propose ONE root-cause hypothesis and a minimal fix. Don't
   shotgun-fix multiple symptoms.

Report the hypothesis + fix path back to the dispatcher; do not
apply the fix yourself unless explicitly asked.
Why it passes: description names WHAT it does (diagnose) AND WHEN to dispatch (test failures, stack traces, symptoms).

Plugin

.claude-plugin/plugin.json at the bundle root. The description is the marketplace tile copy — first thing a user sees when browsing.
Rejected 
{
  "name": "review-tools",
  "description": "Tools for code review",
  "version": "0.1.0"
}
Why it fails: 20 chars (floor 60), generic enough to apply to any plugin.
Passes 
{
  "name": "review-tools",
  "description": "Code review automation: PR diff analysis, test
  coverage gaps, and a configurable rule pack for Rails / Python /
  TypeScript projects.",
  "version": "0.1.0"
}
Why it passes: names the audience (PR reviewers), the value (gaps + rule pack), and the scope (3 named languages).

Command

commands/<name>.md. Shown in /help and slash-command lists. Lower 20-char floor since commands tend to be one-verb actions.
Rejected 
---
name: run-tests
description: Runs tests
---
Why it fails: 10 chars (floor 25), restates the name.
Passes 
---
name: run-tests
description: Run the project test suite and print failures grouped
  by file with the first 5 lines of the traceback inline.
---
Why it passes: states the action, the shape of the output, and the trimming behavior.
← Back to upload
{% endblock %}