skill-writing
- Repo stars 3,480
- Author updated Live
- Author repo expect
- Domain
- Writing
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- 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 special requirements
- Permissions
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools，默认拥有全部工具权限。
---
name: skill-writing
description: Write and improve agent skills (SKILL.md files). Use when creating new skills, refactoring exist…
category: writing
runtime: no special runtime
---
# skill-writing output preview
## PART A: Task fit
- Use case: Write and improve agent skills (SKILL.md files). Use when creating new skills, refactoring existing ones, debugging why an agent ignores instructions, or improving compliance. Covers prompt structure, TDD for skills, description optimization, and rationalization bulletproofing..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “The Iron Law / When to Create a Skill / Core Principles” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “Write and improve agent skills (SKILL.md files). Use when creating new skills, refactoring existing ones, debugging why an agent ignores instructions, or improving compliance. Covers prompt structure, TDD for skills, description optimization, and rationalization bulletproofing.”.
- **02** When the source has headings, the agent prioritizes “The Iron Law / When to Create a Skill / Core Principles” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options.The source does not require a stable slash command. After installation, invoke the skill by name and describe the task.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files, run shell commands.
Start with a small task and check whether the result follows “The Iron Law / When to Create a Skill / Core Principles”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: skill-writing
description: Write and improve agent skills (SKILL.md files). Use when creating new skills, refactoring exist…
category: writing
source: millionco/expect
---
# skill-writing
## When to use
- Write and improve agent skills (SKILL.md files). Use when creating new skills, refactoring existing ones, debugging wh…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “The Iron Law / When to Create a Skill / Core Principles” and keep inference separate from source facts.
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies.The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "skill-writing" {
input -> user goal + target files + boundaries + acceptance criteria
context -> The Iron Law / When to Create a Skill / Core Principles
rules -> SKILL.md triggers / order / output contract
runtime -> no special runtime | read files, write/modify files, run shell commands | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
}Skill Writing
Skills are bundled instruction modules that load into an agent's context when activated. They are the highest-leverage mechanism for controlling agent behavior because they deliver focused instructions at the moment of relevance.
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. |
| REFACTOR | Find new rationalizations the agent invents. Close loopholes. Re-test. |
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.
Unconditional beats conditional. "You MUST call X" works. "When appropriate, consider X" does not.
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.
Checklist for descriptions:
- Start with "Use when..." focusing on triggering conditions
- Include specific symptoms and error messages the user would mention
- Include synonyms (timeout/hang/freeze, cleanup/teardown/afterEach)
- Name tools, commands, file types that signal relevance
- Max 500 characters. Under 200 for frequently-loaded skills
- Never summarize the skill's process — this causes agents to follow the description instead of loading the full skill
Skill Structure
.agents/skills/<skill-name>/
SKILL.md # Required. Under 200 lines.
references/ # Optional. Heavy reference docs (100+ lines).Frontmatter
---
name: kebab-case-name
description: Use when [triggering conditions]. Covers [symptoms, tools, keywords].
---Use verb-first active naming: creating-skills not skill-creation, condition-based-waiting not async-helpers.
Writing Instructions That Get Followed
Lead with identity, then constraints
One-line role statement, then hard constraints immediately. Do not build up to them.
# Browser Test Executor
You are executing adversarial browser tests against code changes.
REQUIRED for every test run:
1. Call accessibility_audit before completing
2. Call performance_metrics before completing
3. Call close to flush the sessionUse numbered checklists gated on completion
Numbered lists signal sequence and completeness. Tie them to whatever marks the task "done."
Before marking the task complete, you MUST:
1. Run the linter
2. Run the type checker
3. Run the test suite
Do not skip any step. A skipped step is a failed task.The trailing "do not skip" is not redundant — it closes the escape hatch.
Name tools and commands exactly
Never "run the appropriate checks." Always call accessibility_audit or run pnpm typecheck.
Put mandatory behaviors at the end
The last section is the last thing read before acting. Put the non-negotiable checklist there.
One good example, one bad example
Examples are worth more than explanations.
**Bad:** `test the login page`
**Good:** `Submit login with empty fields, invalid email, wrong password, valid credentials. Verify errors and redirect.`Bulletproofing Against Rationalization
Agents invent reasons to skip rules. Anticipate and close every loophole explicitly.
Close escape hatches: After every mandatory rule, add: "No exceptions for 'just this once', 'it's simple enough', or 'I'll do it next time'."
Build a rationalization table from your RED phase testing. Every excuse the agent made becomes an explicit counter in the skill:
| Agent Says | Skill Responds |
|---|---|
| "This change is too small to test" | Every change gets tested. Size is not an exemption. |
| "I already verified manually" | Manual verification is not a substitute. Run the tool. |
| "The user didn't ask for this" | The skill requires it. User silence is not opt-out. |
Create a red flags list: "If you catch yourself thinking any of these, stop and follow the checklist."
Anti-Patterns
| Pattern | Why It Fails |
|---|---|
| "Consider running X when appropriate" | Conditional + vague = ignored |
| Giant skill files (>200 lines) | Exceeds instruction budget, compliance drops |
| Duplicating CLAUDE.md rules | Burns budget twice for the same instruction |
| Listing every edge case | Show one example, not twenty — the agent infers the rest |
| "Be thorough" / "Be careful" | Vibes, not instructions. Say what "thorough" means concretely |
| Multi-paragraph justifications | The agent needs the rule, not the backstory. One sentence of "why" max |
| Critical rules in the middle | Middle-of-prompt blindspot. Move to top or bottom |
| Writing a skill without testing first | You don't know what failures to address. Delete it, start with RED. |
| Workflow-summarizing descriptions | Agent follows the summary instead of loading the full skill |
Checklist: Before Shipping
- Tested without the skill first (RED phase) and documented failures
- Skill addresses those specific failures, not hypothetical ones
- Description starts with "Use when..." and lists triggering conditions, not workflow
- Under 200 lines total
- Mandatory behaviors in a numbered checklist at top or bottom
- Every tool/command named exactly — no "appropriate" or "relevant"
- No hedging ("consider", "when appropriate", "if needed")
- At least one good/bad example pair
- No duplication with CLAUDE.md or other skills
- Escape hatches closed with explicit "no exceptions" language
- Re-tested with the skill (GREEN phase) and agent now complies
Decide Fit First
Design Intent
How To Use It
Boundaries And Review