craft
/craft
Authoring standard and quality gate for agent-facing instruction text and workflow templates. Use when writing, reviewing, or revising SKILL.md bodies, frontmatter descriptions, agent definitions, subagent prompts, tool descriptions, or workflow templates. Exclude for human-facing prose (specs, reports).
- Author
- nicsuzor ↗
- Repository
- academicops ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Authoring standard and quality gate for agent-facing instruction text and workflow templates. Use when writing, reviewing, or revising SKILL.md bodies, frontmatter descriptions, agent definitions, subagent prompts, tool descriptions, or workflow templates. Exclude for human-facing prose (specs, reports).
Original author description
Authoring standard and quality gate for agent-facing instruction text and workflow templates. Use when writing, reviewing, or revising SKILL.md bodies, frontmatter descriptions, agent definitions, subagent prompts, tool descriptions, or workflow templates. Exclude for human-facing prose (specs, reports).
How it works
- First Principles
- The Deletion Test
- The Description Is the Router
- The Body Is a Budget
- Voice
- Workflow Templates
- Quality Gates
- Agent Definitions
- Schemas and Construction
SKILL.md preview
---
name: craft
description: Authoring standard and quality gate for agent-facing instruction text and workflow templates. Use when writing, reviewing, or revising SKILL.md bodies, frontmatter descriptions, agent definitions, subagent prompts, tool descriptions, or workflow templates. Exclude for human-facing prose (specs, reports).
allowed-tools: Read, Write, Edit
---
# Instruction Craftsmanship
Author and review agent-facing instructions and workflow templates for operational clarity, contract separation, and token efficiency. Consult `references/evidence.md` for empirical findings.
## First Principles
1. **Trust the harness, not today's quirks**: Write for durable capabilities. Avoid hard-coding workarounds for transient model behaviors.
2. **Specify process, not keystrokes**: State when to invoke a capability and what outcome proves it worked. Omit basic sub-steps or flags the agent already knows.
3. **One component, one job**: Keep instructions and templates focused on their singular purpose. Dispatch to peer skills rather than summarizing their internals. Leave another agent's domain to that agent: name the hand-off, never how it does its work.
4. **State the contract, not the neighbour**: Specify what a component needs as input and delivers as output. Never couple to specific neighbour names or slugs; composing agents decide what fills each slot.
5. **Write for a headless worker**: Assume unattended, asynchronous execution with no interactive human in the loop. A step never pauses or waits for human input; explicit approval boundaries terminate the task and wire dependent tasks as blocked.
6. **Promise only what the executor delivers**: Output contracts list only artifacts and state the executing agent itself produces. Another party's subsequent act (human sign-off, reviewer verdict) is never an executor deliverable.
7. **Verification must be real**: Demand direct inspection of live artifacts (outputs, logs, diffs) rather than relying on compliance checklists.
8. **Every line earns its place**: Relocate historical narratives, incident stories, and philosophical justifications to change records.
## The Deletion Test
Delete or relocate any line whose removal leaves the median task unaffected. Confine rare paths to progressive reference files.
## The Description Is the Router
Frontmatter descriptions are the primary routing surface (<1024 chars):
- **Front-load intent**: State the exact trigger conditions in the opening clause.
- **Define exclusions**: Explicitly state when not to invoke to prevent crossover.
- **Consolidate routing**: Place all triggering logic in the description field.
## The Body Is a Budget
Hold operational content strictly under 200 lines (target 30-80 lines):
- **Segment clearly**: Place critical constraints first or last; use markdown headers for navigation anchors.
- **Progressive disclosure**: Place dense reference materials or schemas one level deep in `references/`.
- **Provide shape, not logic**: Provide structural skeletons rather than full worked logic examples that induce overfitting.
## Voice
- Use positive imperatives paired with functional reasoning ("Use X because Y").
- Pair prohibitions with mandatory alternatives and legitimate escape hatches.
- Rely on document structure rather than capitalized absolutes ("ALWAYS", "NEVER").
## Workflow Templates
Workflow templates (`type: template`) govern repeatable multi-stage execution and task composition (<100 lines target).
- **Schema**:
```yaml
---
title: <human name>
type: template
description: <one line: what class of work this covers, so a composer can select it>
tags: [...]
---
```
- **Contract over neighbour**: Define input and output contracts per stage. Never name another template slug in frontmatter or body. A composite lists stages as contract expectations in order ("an independent review verdict on the spec"), never as slugs.
- **Headless execution & approval boundaries**: A step never pauses, waits, or prompts a human mid-task. Where approval is required, the step ends there: the worker files the complete artifact on the record and structures the boundary so downstream work remains strictly blocked until approval is recorded (e.g. releasing as `partial` with an explicit decision task or dependency-wired review task). Cut the composition chain at that boundary; work following the decision belongs in a separate dependent task.
- **Promise only executor deliverables**: Output contracts specify only artifacts and state generated by the executing agent. Future external decisions or approvals are not executor deliverables.
- **`wf-` prefix**: Templates stating an obligation that blocks acceptance rather than a process that proceeds conventionally carry a `wf-` prefix.
## Quality Gates
Every agent instruction, skill, persona definition, and subagent prompt must pass these four gates before merging:
1. **Categorical generality (Categorical Imperative)**: Express rules in general terms covering the full class of situations. Prohibit hyper-specific quotas, rigid interaction numbers, or one-off compromises.
2. **Entity abstraction (Name the process, not the actor)**: Refer to the principal as "the user", never by a personal proper noun or name ("Nic"). Refer to collaborators by role or capability.
3. **No PKB leakage (Data Boundaries)**: Never include private PKB note or task IDs (`aops_...`, `task_...`, `mem_...`, `kb_...`) or Obsidian wikilinks (`[[...]]`) in distributed framework instruction files. Use standard relative markdown links for file references.
4. **Zero historical provenance**: Strictly eliminate incident stories, post-mortem recaps ("after an incident on..."), or PR/commit changelog citations. Instructions define what is true now, never how it came to be true.
## Agent Definitions
Limit agent definition bodies to:
1. **Identity/role**: 1-3 sentences defining the persona.
2. **Behavioral rules**: Terse operational constraints.
3. **Output schema**: Expected report structure and verdict states.
4. **Routing table**: Clean table without per-route narrative.
Name a skill the agent uses; leave its modes, arguments, and when each applies to the skill. A change to a skill's modes or arguments owes the agent definitions that use it no edit.
## Schemas and Construction
- Define strict schemas with `required` fields and `additionalProperties: false`.
- **Static prefix, variable tail**: Emit invariant template text first and append variable content at the end to maximize prompt caching.
Files in this package (2)
- SKILL.md 6 KB
- references/evidence.md 2 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · nicsuzor/academicops | 100 | MIT |
| nicsuzor/academicops | 100 | MIT |
| shubhamgoel27/artifold | 100 | MIT |
| didiansyah/skills | 100 | MIT |
| cameronspears/claude-skills | 100 | MIT |
| brolag/neural-claude-code | 100 | MIT |
| alexiolan/craft-skills | 100 | GPL-3.0 |
| educlopez/ui-craft | 90 | MIT |
| LeoYeAI/openclaw-master-skills | 90 | MIT |
Identical content appears in 5 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version 36d31ec6a1ec (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90plugin-authoring
Best practices for writing skills and agents: descriptions, structure, token efficiency, frontmatter, tool scoping, and common authoring mistakes. Activate when creating or editing a SKILL.md, a command file, or an agent file, or when the user asks to "write a skill", "add a… - 100agent-dev
Use this skill when creating or refining Claude Code sub-agent definitions. Helps design specialized AI assistants with proper YAML frontmatter, system prompts, tool access, and example-driven descriptions. Automatically invoked when user requests "create an agent", "design a… - 100agent-prompt-instruction-refinement
Use this skill when tuning, updating, and optimizing agent system prompts, persona instructions, and tool descriptions based on execution friction. - 91skill_doctor
Check-only doctor for skill artifacts. It audits SKILL.md frontmatter, descriptions that must serve both a browsing user and an LLM router, registration, tests, and instruction quality for one skill, a skill family, or every skill in the repo, editing no targets and running no… - 100writing-agent-instructions
How to write great agent instructions for an agent-native app or template: AGENTS.md, skills, and tool/action descriptions. Use when authoring or reviewing AGENTS.md, writing a SKILL.md, wording action descriptions, or deciding what belongs in instructions vs skills vs memory. - 90writing-for-agents
Writing documents for agents. Use when creating or editing a skill, agent definition, rule, the project instruction file, or when writing a directive or brief another agent will execute.