Common Workflow WritingSAFE

A collection of Agent Skills Standard and Best Practice for Programming Languages, Frameworks that help our AI Agent follow best practies on frameworks and programming laguages

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: common-workflow-writing
description: Rules for writing concise, token-efficient workflow and skill files. Prevents over-building that requires costly optimization passes. Use when creating or editing workflow files, SKILL.md files, or new skill definitions.
metadata:
  triggers:
    files:
    - '.agents/workflows/*.md'
    - 'SKILL.md'
    keywords:
    - create workflow
    - write workflow
    - new skill
    - new workflow
---
# Workflow Writing Standard

## **Priority: P0 (CRITICAL)**

## Core Rules

- **Templates, not examples**: Workflows define _structure_, not pre-filled data. agent generates data at runtime.
- **No example rows in tables**: Include headers + 1 skeleton row only. Never populate with fake data.
- **No prose explanations**: If bullet or command achieves same result, delete paragraph.
- **No pre-answered questions**: Don't document what agent _will_ output — let it output it.
- **Merge sequential steps**: If two steps always happen together, they one step.

## Size Limits

| File type | Limit | If exceeded |
| ----------------- | --------- | --------------------------------- |
| Workflow `.md` | 80 lines | Extract detail to `references/` |
| SKILL.md | 100 lines | Extract examples to `references/` |
| Table rows | 8 | Extract to `references/` |
| Inline code block | 10 lines | Extract to `references/` |

## Workflow Structure (Required order)

```
1. Goal (1 sentence)
2. Steps (imperative verb → command or checklist)
3. Output template (headers only, no pre-filled rows)
```

## Anti-Patterns

- **No verbose step preambles**: `"Before we start, it's important to understand..."` → Delete
- **No pre-filled report rows**: `| Security | P0 | ✅ PASS | CLIENT_ID moved to env |` → Delete
- **No repeated examples**: Same concept shown twice in different formats → Keep one
- **No "How to X" sections**: step instruction
- **No caution blocks for obvious rules**: Reserve `> ⚠️` for genuinely non-obvious risks
- **Portable output contracts**: Use `feature_status`, missing evidence, decision needed, and adapter-neutral language; avoid runtime-specific tool names, chat channels, containers, and mount paths in canonical workflows.

## Quick Self-Check Before Saving

- [ ] Can agent reconstruct any removed content at runtime from context? If yes → remove it
- [ ] every table row real structure, not example data?
- [ ] there any paragraphs bullet list could replace?
- [ ] Would cutting this in half still give agent enough to act on?

## Canonical response anchors

When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:
- 80 lines
- delete

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.