writing skills

Documentation Community

Skill notes

Overview

Writing skills IS Test-Driven Development applied to process documentation. Personal skills live in your runtime's skills directory (~/.claude/skills/ on Claude Code) — see codex-tools.md or gemini-tools.md for the path on those runtimes. Codex, Copilot CLI, and Gemini CLI all also recognize ~/.agents/skills/ as a cross-runtime alias. You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).

What is a Skill?

A skill is a reference guide for proven techniques, patterns, or tools. Skills help future agents find and apply effective approaches. Skills are: Reusable techniques, patterns, tools, reference guides Skills are NOT: Narratives about how you solved a problem once

TDD Mapping for Skills

TDD Concept · Skill Creation Test case · Pressure scenario with subagent Production code · Skill document (SKILL.md) Test fails (RED) · Agent violates rule without skill (baseline) Test passes (GREEN) · Agent complies with skill present

When to Create a Skill

Create when: Technique wasn't intuitively obvious to you You'd reference this again across projects Pattern applies broadly (not project-specific) Others would benefit

Technique

Concrete method with steps to follow (condition-based-waiting, root-cause-tracing)

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Documentation
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
@obra · no license declared
Token usage
Heavy
Setup complexity
Guided setup
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
Python
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
Network behavior
External requests
Install commands
None (reference only)

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

Output preview writing-skills.preview
# Code Examples

- Testing techniques → TypeScript/JavaScript
- System debugging → Shell/Python
- Data processing → Python
- Complete and runnable
- Well-commented explaining WHY
- From real scenario

Discussion

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