skill writing

Writing Community

Skill notes

The Iron Law

No skill without a failing test first. Before writing a skill, run a subagent on the target task WITHOUT the skill. Document what it gets wrong — the exact rationalizations, shortcuts, and skipped steps. Then write the skill addressing those specific failures. This is TDD applied to documentation. TDD Step · Skill Equivalent RED · Run scenario without skill. Document what the agent does wrong. GREEN · Write minimal skill addressing those specific failures. Verify agent now complies.

When to Create a Skill

Create when: the technique wasn't obvious, you'd reference it across projects, others would benefit, or the agent repeatedly fails without it. Don't create for: one-off solutions, standard practices documented elsewhere, project-specific conventions (use CLAUDE.md), or mechanical constraints (enforce with linters/hooks instead).

Core Principles

Instructions are a finite budget. Models reliably follow ~150 instructions. The system prompt burns ~50. Every instruction you add degrades compliance across ALL instructions. Be ruthless about what earns a slot. Peripheral positions get more attention. First and last sections receive disproportionate attention. Bury a critical rule in the middle and it gets skipped. Specificity drives compliance. "Consider running audits" gets ignored. "Call accessibility_audit before emitting RUN_COMPLETED" gets followed.

Description Optimization

The description field controls when the skill activates. The agent reads it to decide: "Should I load this right now?" Describe triggering conditions, not workflow. Bad: description: A skill for TDD - write test first, watch it fail, write code Good: description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently. Covers flaky tests, hanging tests, zombie processes.

Frontmatter

Use verb-first active naming: creating-skills not skill-creation, condition-based-waiting not async-helpers.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Writing
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@millionco · no license declared
Token usage
Lean
Setup complexity
Guided setup
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

Output preview skill-writing.preview
# One good example, one bad example

**Bad:** `test the login page`
**Good:** `Submit login with empty fields, invalid email, wrong password, valid credentials. Verify errors and redirect.`

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.