bkinsey808/write-skill
skills/write-skill/SKILL.md
How to write, update, or split skill files in this repo. Use when creating a new SKILL.md, updating an existing one, or deciding whether to put content in a skill vs. docs/.
$ install --global
skillsauthnpx skillsauth add bkinsey808/songshare-effect write-skillInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 15, 2026, 11:46 PM84.5s1 file scanned
SKILL.md
- name:
- write-skill
- description:
- How to write, update, or split skill files in this repo. Use when creating a new SKILL.md, updating an existing one, or deciding whether to put content in a skill vs. docs/.
Requires: file-read. No terminal or network access needed.
Write Skill
Use When
- Creating a new
SKILL.mdunderskills/. - Updating an existing skill after learning new patterns.
- Deciding whether something belongs in a skill, a doc, or a workflow.
Core Rules
- Skills must be ≤ 300 lines. The CI check (
npm run check:skill-line-count) enforces this. If you're over, move detail todocs/and deep-link. - Skills are pointers, not encyclopedias. A skill tells an agent what to do and where to look. Full examples, reference tables, and historical context belong in
docs/. - Docs are the source of truth. Skills defer to
docs/via deep links. Update the doc when you learn something new; then update the skill to point at it.
Structure
Every skill needs these sections in order:
---
name: <kebab-case-name>
description: <one sentence — what this covers and when to use it>
---
# <Title>
## Use When
<bullet list of trigger conditions>
---
## Execution Workflow (if the skill covers a multi-step task)
<numbered steps>
---
## Key Patterns
<only the most essential facts — defer detail to docs>
---
## References
<links to docs/, workflows, and related skills>
## Do Not
<short list of common mistakes to avoid>
What Goes Where
| Content type | Where it lives |
| ----------------------------------------- | ----------------------------------------- |
| Step-by-step task workflow | .agent/workflows/<name>.md |
| Full pattern reference with many examples | docs/<topic>.md |
| Quick lookup table / rule summary | docs/lint-best-practices.md or similar |
| "Use this when X, do Y, see Z" | SKILL.md |
| Project background / motivation | docs/ |
Deep Links
Skills should link into docs/ at the heading level using GitHub-flavored Markdown anchors. Heading ## Foo Bar becomes #foo-bar. Special chars are stripped; spaces become -:
<!-- From a skill, linking into a doc section -->
See [→ Foo Bar pattern](../../../docs/my-doc.md#foo-bar)
IDE markdown linters may warn that fragment links can't be resolved — ignore these warnings. The links work on GitHub and in agent context.
When to Split a Skill
Split when the skill covers two clearly distinct audiences or task types. Example: unit-testing and unit-testing-hooks are separate because hooks tests need a different setup. Don't split just to stay under 300 lines — trim first; split only when topic focus genuinely differs.
Updating an Existing Skill
- Read the current skill and the doc it points to.
- Add new patterns to the doc first.
- Add or update the deep link in the skill.
- Bump
versionin frontmatter. - Run
npm run check:skill-line-countto verify ≤ 300 lines.
References
- Skill line-count check:
scripts/check-skill-line-count/ - Workflows:
.agent/workflows/ - Docs directory:
docs/
Do Not
- Do not put long code examples directly in a skill — put them in
docs/and link. - Do not exceed 300 lines — the CI check will fail.
- Do not duplicate content between a skill and a doc — the doc is canonical.
- Do not create a skill without a
descriptionfrontmatter field — agents use it for relevance matching. - Never ask the user whether to commit code changes or open a pull request. Do not prompt with messages like "Would you like me to commit these tests and open a PR?" or any variant. Only mention commits or PRs when the user explicitly requests creation or review of a PR; otherwise omit commit/PR prompts entirely.
Related Skills
bkinsey808/zustand-best-practices
tools
VerifiedTrustedCommunity
Zustand state management patterns for this project — store creation, selectors, Immer middleware, async actions with loading states, devtools, persist, and testing. Use when authoring or editing Zustand stores (use*Store files) or components that subscribe to stores. Do NOT use for React component structure or TypeScript-only utilities.
2SKILL.mdUpdated Apr 15, 2026
bkinsey808/unit-test-hook-best-practices
development
VerifiedTrustedCommunity
Complete guide for testing React hooks — renderHook, Documentation by Harness, installStore, fixtures, subscription patterns, lint/compiler traps, and pre-completion checklist. Read docs/testing/unit-test-hook-best-practices.md for the full reference.
2SKILL.mdUpdated Apr 15, 2026
bkinsey808/unit-test-best-practices
development
VerifiedTrustedCommunity
Vitest unit test authoring for this repo — setup, mocking, API handler testing, and common pitfalls for non-hook code. Use when the user asks to add, update, fix, or review unit tests for utilities, components, API handlers, or scripts. Do NOT use for React hook tests — load unit-test-hook-best-practices instead.
2SKILL.mdUpdated Apr 15, 2026
bkinsey808/typescript-best-practices
development
VerifiedTrustedCommunity
TypeScript conventions for this repo (no `any`, explicit return types, JSDoc, exactOptionalPropertyTypes, ambient types, import style). Use when authoring or editing any `.ts` or `.tsx` file, resolving TypeScript strictness errors, or fixing type-related lint failures. Do NOT use for React-specific typing patterns (see react-best-practices skill) or JSDoc-only changes (see code-comment-best-practices skill).
2SKILL.mdUpdated Apr 15, 2026