common-workflow-writing
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.
79
76%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.github/skills/common/common-workflow-writing/SKILL.mdQuality
Discovery
75%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description is well-structured with a clear 'Use when' clause and a distinct niche around skill/workflow file authoring. Its main weakness is moderate specificity — it describes the purpose (concise, token-efficient writing rules) but doesn't enumerate the concrete actions or rules it provides. Trigger terms are adequate but could include more natural variations.
Suggestions
Add more specific concrete actions, e.g., 'Enforces brevity guidelines, limits section length, flags redundant content in workflow and skill files.'
Expand trigger terms to include variations like 'skill template', 'skill authoring', 'writing skills', or 'token optimization' to improve matching.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (workflow and skill files) and mentions some actions ('writing concise, token-efficient', 'prevents over-building'), but doesn't list multiple specific concrete actions like formatting rules, token counting, or structure validation. | 2 / 3 |
Completeness | Clearly answers both 'what' (rules for writing concise, token-efficient workflow and skill files, prevents over-building) and 'when' (explicit 'Use when creating or editing workflow files, SKILL.md files, or new skill definitions'). | 3 / 3 |
Trigger Term Quality | Includes relevant terms like 'workflow files', 'SKILL.md files', 'skill definitions', but misses common variations users might say such as 'skill template', 'skill authoring', 'token optimization', or 'skill format'. | 2 / 3 |
Distinctiveness Conflict Risk | Targets a clear niche — writing/editing workflow and SKILL.md files with a focus on token efficiency. The specific mention of 'SKILL.md files' and 'skill definitions' makes it unlikely to conflict with other skills. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-crafted meta-skill that effectively models the conciseness it advocates for. Its main strengths are its lean structure, clear anti-patterns, and actionable self-check checklist. Weaknesses include a minor typo in the 'Merge sequential steps' rule, lack of a concrete before/after example of a complete workflow file, and references to `references/` directories without providing navigable links or templates for those extracted files.
Suggestions
Fix the apparent typo in 'Merge sequential steps' rule: 'they one step' should likely be 'they are one step' or 'combine into one step'.
Add a brief concrete example of a well-written workflow (3-5 lines) vs a poorly-written one to make the 'Templates, not examples' rule more actionable.
Provide a link or template for what extracted `references/` files should look like, since the skill repeatedly directs content there.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill practices what it preaches — it's lean, uses bullet points and tables instead of prose, and every token contributes meaningful guidance. No unnecessary explanations of concepts Claude already knows. | 3 / 3 |
Actionability | The rules are concrete and specific (e.g., size limits, anti-patterns with before/after examples), but some items are slightly vague or incomplete — e.g., 'Merge sequential steps: If two steps always happen together, they one step' appears to have a typo/missing word, and the workflow structure template is minimal without a concrete executable example of a well-written workflow file. | 2 / 3 |
Workflow Clarity | For a single-purpose instructional skill, the workflow is clear: core rules → size limits → required structure → anti-patterns → self-check checklist. The self-check checklist at the end serves as an explicit validation checkpoint before saving, which is appropriate for this type of skill. | 3 / 3 |
Progressive Disclosure | The skill references extracting content to `references/` directories multiple times but doesn't provide links to any actual reference files or examples of what those extracted files should look like. The content itself is well-structured with clear sections, but the references are mentioned without being navigable. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
metadata_version | 'metadata.version' is missing | Warning |
metadata_field | 'metadata' should map string keys to string values | Warning |
Total | 9 / 11 Passed | |
- Repository
- HoangNguyen0403/agent-skills-standard
- Commit
4c72e76
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.