agentleFS
pjordanandrsnpjordanandrsn/claude-desktop-asahi/.claude/skills/writing-agents/SKILL.md

writing-agents

Skill1 starsChanged 6 months agoApache-2.0View on GitHub

Use when creating new agents, editing existing agents, or defining specialized subagent roles for the Task tool

4 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

  • Other versions4 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 1

    1. aaddrick/claude-pipeline★ 12882% same

    Wrote their own version · 3

    1. tunahanaliozturk/atelier★ 1same name
    2. mrzli/skills★ 0same name
    3. techmefr/mentis★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository9 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

10 rules. 0 are common, 10 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 10

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Core principle: If you didn't test the agent on representative tasks, you don't know if it performs correctly.

    line 14
  2. Distinctive:

    IMPORTANT: After creating or modifying an agent, prompt the user to restart their Claude Code session.

    line 47
  3. Distinctive:

    Before writing the agent, gather domain knowledge and project context:

    line 51
  4. Distinctive:

    Use WebSearch to find domain-specific guidance: Search for:

    line 55
  5. Distinctive:

    After writing the agent file, inform the user:

    line 126
  6. Distinctive:

    Run representative tasks with a generic prompt.

    line 340
  7. Distinctive:

    Add persona for role consistency

    line 348
  8. Distinctive:

    Add anti-patterns for common mistakes

    line 349
  9. Distinctive:

    Add project context for autonomy

    line 350
  10. Distinctive:

    Test your agents on real tasks.

    line 453

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Writing Agents

Overview

Writing agents IS Test-Driven Development applied to role definitions.

Agents are specialized subagents invoked via the Task tool. They receive full conversation context and execute autonomously with a defined persona, tools, and behavioral guidelines.

Core principle: If you didn't test the agent on representative tasks, you don't know if it performs correctly.

REQUIRED BACKGROUND: Understand test-driven-development and writing-skills before using this skill. Same RED-GREEN-REFACTOR cycle applies.

Agents vs Skills

AspectAgentsSkills
InvocationTask tool with subagent_typeSkill tool with skill name
ContextFull conversation historyLoaded on-demand
ExecutionAutonomous, multi-turnSingle response guidance
PersonaExplicit role/identityReference documentation
Location.claude/agents/.claude/skills/
Use forComplex, autonomous tasksReusable patterns/techniques

Agent File Structure

Agents are PROJECT-LEVEL. They live in the project's .claude/agents/ directory, not personal directories.

.claude/agents/
  agent-name.md    # Single file with frontmatter + persona

Frontmatter (YAML):

---
name: agent-name
description: Role description. Use for [specific task types].
model: opus  # Optional: opus, sonnet, haiku (defaults to parent)
---

IMPORTANT: After creating or modifying an agent, prompt the user to restart their Claude Code session. Agents are loaded at session start and won't be available until restart.

Agent Creation Workflow

Before writing the agent, gather domain knowledge and project context:

Step 1: Research Domain Best Practices

Use WebSearch to find domain-specific guidance. Search for:

  • Best practices for [domain] development
  • Common [domain] mistakes/anti-patterns
  • [Domain] code review checklist
  • [Technology] security considerations

Example searches by domain:

# Shell scripting agent
"Bash scripting best practices 2026"
"Shell script anti-patterns to avoid"
"shellcheck common warnings and fixes"
"Bash security pitfalls"

# Debian packaging agent
"Debian packaging best practices"
"dpkg-deb common mistakes"
"Debian policy manual packaging guidelines"

# CI/CD agent
"GitHub Actions best practices 2026"
"GitHub Actions security hardening"
"actionlint common workflow issues"

# Electron/AppImage agent
"AppImage packaging best practices"
"Electron Linux packaging pitfalls"
"asar extraction and modification"

Incorporate findings into:

  • Anti-patterns section (domain-specific mistakes)
  • Best practices (positive patterns to follow)
  • Security considerations (if applicable)

Step 2: Gather Codebase Context

Explore the project to make the agent project-specific:

  1. Read CLAUDE.md and README.md for project conventions
  2. Identify existing patterns using Glob/Grep:
    • Directory structure relevant to agent's domain
    • Existing services, controllers, models the agent will work with
    • Testing patterns and conventions
  3. Check existing agents in .claude/agents/ for:
    • Coordination protocols to follow
    • Deferral relationships to establish
    • Naming conventions

Example exploration:

# Find project structure for a build/packaging agent
Glob: "scripts/*.sh"
Glob: ".github/workflows/*.yml"
Grep: "function.*\(\)"  # in shell scripts
Read: "CLAUDE.md", "README.md", "docs/styleguides/bash_styleguide.md"

# Find existing agent patterns
Glob: ".claude/agents/*.md"

Step 3: Write the Agent

Combine research + codebase context into the agent definition:

  • Persona grounded in project specifics
  • Anti-patterns from both research AND project history
  • Project structure and commands the agent needs
  • Coordination with existing agents

Step 4: Session Restart

After writing the agent file, inform the user:

Agent created: .claude/agents/[agent-name].md

**ACTION REQUIRED:** Please restart your Claude Code session for the new agent to be available. Agents are loaded at session start.

To use the agent after restart:
- It will appear in the Task tool's available agents
- Invoke with: Task tool, subagent_type="[agent-name]"

Anatomy of an Effective Agent

1. Clear Persona Definition

The persona is the agent's DNA. A well-defined persona produces consistent behavior across interactions.

You are a [specific role] with expertise in [domains]. You specialize in [specific capabilities] for [context/project].

Good persona:

You are a senior shell scripting and Electron packaging specialist with deep expertise in Bash, Debian packaging, and AppImage creation. You specialize in building robust build systems and Linux desktop application packaging for the claude-desktop-debian repackaging project.

Bad persona:

You are a helpful assistant that can help with code.

2. Explicit Scope Boundaries

Define what the agent DOES and DOES NOT handle. Prevents scope creep and enables deferral to specialists.

## CORE COMPETENCIES
- [Domain 1]: Specific capabilities
- [Domain 2]: Specific capabilities

**Not in scope** (defer to [other-agent]):
- [Excluded domain 1]
- [Excluded domain 2]

3. Anti-Patterns Section

List specific mistakes to avoid. More effective than generic guidelines.

## Anti-Patterns to Avoid

- **Never hardcode minified variable names** -- extract them dynamically with grep/sed
- **Always handle optional whitespace** in sed patterns -- minified vs beautified code differs
- **Use `[[ ]]` not `[ ]`** for conditionals -- avoid POSIX test pitfalls
- **Never use `set -e`** -- handle errors explicitly with `|| exit 1`

4. Coordination Protocols

Define how the agent coordinates with others. Essential for multi-agent workflows.

## Coordination with [Other Agent]

**When delegated work:**
1. Acknowledge the task
2. Implement following their requirements
3. Report completion with specific details

**Report format:**
- Issue/task reference
- Changes made (files, methods)
- Testing performed
- Explicit "ready for next step" statement

5. Project Context

Provide relevant project structure and conventions. Enables autonomous operation.

## PROJECT CONTEXT

### Project Structure

claude-desktop-debian/ ├── build.sh # Main build script ├── scripts/ # Modular build scripts │ ├── build-appimage.sh │ ├── build-deb-package.sh │ ├── build-rpm-package.sh │ └── launcher-common.sh ├── .github/workflows/ # CI/CD pipelines └── resources/ # Desktop entries, icons


### Key Commands
```bash
./build.sh --build appimage --clean no   # Local build
shellcheck scripts/*.sh                  # Lint shell scripts
actionlint                               # Lint GitHub Actions

## Agent Description Best Practices

The description field is critical for Task tool routing. Claude uses it to select the right agent.

**Format:** `[Role statement]. Use for [specific task types].`

**Good descriptions:**
```yaml
# Specific role + clear triggers
description: Shell scripting and build system specialist. Use for build.sh modifications, sed/regex patches, asar extraction, Electron packaging, and shell function development.

# Clear scope + deferral
description: CI/CD workflow engineer for GitHub Actions. Use for workflow YAML, release automation, artifact signing, and repository publishing. Defers to build-specialist for shell scripts.

# Domain-specific expertise
description: Debian and RPM packaging specialist. Use for control files, postinst scripts, dpkg-deb, rpmbuild, package metadata, and dependency management.

Bad descriptions:

# Too vague
description: Helps with code

# No trigger conditions
description: A senior developer

# Process summary (causes shortcut behavior)
description: Reviews code by checking style, then logic, then tests

Model Selection

Choose the right model for the task complexity:

ModelUse WhenCost
haikuQuick, straightforward tasksLow
sonnetBalanced complexity (default)Medium
opusDeep reasoning, architecture decisionsHigh
# Example: Code simplification needs deep judgment
model: opus

# Example: Documentation generation is straightforward
model: haiku

Omit model to inherit from parent conversation.

Common Agent Patterns

Specialist Agent

Focused on a single domain with clear boundaries and deferral rules.

You are a [specialist role] focused on [specific domain].

**Your scope:**
- [Capability 1]
- [Capability 2]

**Defer to [other-agent] for:**
- [Out-of-scope area 1]
- [Out-of-scope area 2]

Orchestrator Agent

Coordinates other agents, manages workflow, doesn't do implementation.

You orchestrate [workflow type]. You delegate to specialist agents and track progress.

**You manage:**
- Task breakdown and assignment
- Progress tracking
- Integration of results

**You do NOT:**
- Write code directly
- Make implementation decisions
- Deploy without approval

Reviewer Agent

Evaluates work against criteria, provides structured feedback.

You review [artifact type] against [criteria].

**Review process:**
1. [Step 1]
2. [Step 2]
3. [Step 3]

**Output format:**
- Status: [PASS/FAIL/NEEDS_CHANGES]
- Issues: [List]
- Recommendations: [List]

Testing Agents

RED: Baseline Without Agent

Run representative tasks with a generic prompt. Document:

  • What mistakes does it make?
  • What context does it lack?
  • Where does it go wrong?

GREEN: Write Minimal Agent

Address specific baseline failures:

  • Add persona for role consistency
  • Add anti-patterns for common mistakes
  • Add project context for autonomy

REFACTOR: Close Loopholes

Test edge cases:

  • Does it stay in scope?
  • Does it defer correctly?
  • Does it follow coordination protocols?

Agent Creation Checklist

Research Phase:

  • WebSearch for "[domain] best practices [current year]"
  • WebSearch for "[domain] anti-patterns" or "[domain] common mistakes"
  • WebSearch for "[technology] security considerations" (if applicable)
  • Document key findings for anti-patterns section

Context Phase:

  • Read CLAUDE.md and README.md for project conventions
  • Explore codebase structure relevant to agent's domain
  • Check existing agents in .claude/agents/ for patterns
  • Identify coordination/deferral relationships needed

RED Phase:

  • Identify the specialized task type
  • Test baseline behavior without agent
  • Document specific failures and gaps

GREEN Phase:

  • Clear persona with specific expertise AND project context
  • Explicit scope boundaries (does/doesn't)
  • Anti-patterns from BOTH research AND project experience
  • Project structure and commands included
  • Coordination protocols if multi-agent
  • Model selection appropriate for complexity

REFACTOR Phase:

  • Test on representative tasks
  • Verify scope boundaries respected
  • Verify deferral works correctly
  • Verify coordination protocols followed

Quality Checks:

  • Description under 500 chars, includes triggers
  • Persona is specific, not generic
  • Anti-patterns are actionable, not vague
  • No process summary in description

Deployment:

  • Agent file written to .claude/agents/[name].md
  • User prompted to restart session

Anti-Patterns to Avoid

Generic Persona

# BAD: Could be anyone
You are a helpful assistant.

# GOOD: Specific expertise and context
You are a senior shell scripting specialist with deep expertise in Bash, Debian packaging, and Electron app repackaging for the claude-desktop-debian project.

Missing Scope Boundaries

# BAD: No limits
You can help with anything.

# GOOD: Clear boundaries with deferral
**Not in scope** (defer to ci-workflow-engineer):
- GitHub Actions workflow YAML
- Release automation
- Repository signing and publishing

Vague Anti-Patterns

# BAD: Too general
- Write good code
- Follow best practices

# GOOD: Specific and actionable
- **Never hardcode minified names** -- extract dynamically with grep -oP
- **Always use `-E` flag with sed** when patterns need grouping or alternation

Process in Description

# BAD: Claude may follow description instead of reading agent
description: Reviews code by first checking style, then logic, then tests, finally creating report

# GOOD: Just triggers, no process
description: Code quality reviewer. Use after completing features to check against standards.

The Bottom Line

Agents are autonomous specialists. They need:

  1. Clear identity - Who they are, what they know
  2. Explicit scope - What they do and don't do
  3. Actionable guidelines - Specific anti-patterns, not vague advice
  4. Coordination protocols - How they work with others

Test your agents on real tasks. A well-defined persona produces consistent, reliable behavior. A vague persona produces unpredictable results.

References

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.