Skip to content
Skills Library
AI & agents · Writing

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).

Repository
academicops ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

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

  1. First Principles
  2. The Deletion Test
  3. The Description Is the Router
  4. The Body Is a Budget
  5. Voice
  6. Workflow Templates
  7. Quality Gates
  8. Agent Definitions
  9. Schemas and Construction
Original SKILL.md headings · 85 lines, 877 words
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

RepositoryScoreLicence
This page · nicsuzor/academicops100MIT
nicsuzor/academicops100MIT
shubhamgoel27/artifold100MIT
didiansyah/skills100MIT
cameronspears/claude-skills100MIT
brolag/neural-claude-code100MIT
alexiolan/craft-skills100GPL-3.0
educlopez/ui-craft90MIT
LeoYeAI/openclaw-master-skills90MIT

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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.