What does this skill do, and when should you use it?
This is a documentation skill for Effect codebases, bundled inside the MIT-licensed pingdotgg/t3code repository, focused entirely on public API JSDoc comments. It enforces a canonical comment shape (short description, When to use, Details, Gotchas, Example sections), a fixed tag order (@deprecated, @default, @see, @category, @since), and detailed prose rules so docs pass the custom jsdocs oxlint rule and support JSON extraction. The skill provides a full workflow: inspect the declaration and tests, rewrite the comments, then run the narrowest validation via pnpm docgen and pnpm lint. It suits teams maintaining Effect libraries who need consistent, lint-clean documentation.
- Rewrites public API comments into the standard template after inspecting the declaration, implementation, nearby tests, and existing JSDoc
- Distinguishes a single API fix from a module refinement pass, with workflows for each
- Runs a dedicated @see audit: keeps only tags pointing to semantically useful related public APIs
- Runs a dedicated Gotchas audit: moves real edge cases and footguns out of Details
- Enforces tag requirements: root declarations need @category and stable-semver @since; member JSDoc may use @default
- Runs the narrowest validation: pnpm docgen in the package directory plus pnpm lint
- An Effect library maintainer adding a new exported API wants lint-clean JSDoc written right the first time
- A contributor refining an entire legacy Effect module is unsure which @see tags to keep and which caveats belong in Gotchas
- A team needs to resolve oxlint jsdocs diagnostics (missing @since, malformed @example) and prepare docs for JSON extraction
- A reviewer checking public API docs against concrete rules for example titles, section order, and prose style
- TypeScript projects that don't use Effect — the template and @category/@since conventions are Effect-specific
- Teams wanting generic documentation generation without the Effect style constraints — no other templates are provided
- Environments without the pnpm/docgen/lint toolchain — the prescribed validation steps cannot run
How do you install this skill?
- Publisher identity unverified; treat maintenance promises with caution.
- Skill is specific to Effect ecosystem; may not apply to other frameworks.
- Validation commands pnpm docgen and pnpm lint depend on project-specific config and may not run in isolation.
- Shell / CLI
- Local filesystem
pnpm (for validation: pnpm docgen, pnpm lint)
The source provides no standalone install command for this skill. The skill file lives at .repos/effect-smol/.agents/skills/jsdocs/SKILL.md in the t3code repository; copy that directory into your Agent Skills-compatible client's skills directory yourself. Installation for the T3 Code app itself (a separate concern from the skill collection) is documented in the README:
T3 Code app (run via npx)
npx t3@latestT3 Code desktop (macOS, Homebrew)
brew install --cask t3-codeT3 Code desktop (Windows, winget)
winget install T3Tools.T3CodeT3 Code desktop (Arch Linux, AUR)
yay -S t3code-binHow do you use this skill?
Once installed, send your agent any of these to trigger it:
- Add JSDoc that satisfies the jsdocs rule to the newly exported decodeUnknown function in src/Schema.ts, including @category and @since
- Refine the public API docs for the whole src/Platform.ts module, running the @see and Gotchas audits
- Resolve the oxlint jsdocs diagnostics: convert this API's @example into a **Example** (Title) section
- Check whether the existing JSDoc in Event.ts meets the public API documentation requirements and turn loose ts fences into standard examples
The skill is triggered automatically when the model encounters JSDoc-related tasks (its frontmatter description covers adding/fixing JSDoc, resolving jsdocs diagnostics, preparing docs for JSON extraction, and reviewing public API docs). The flow: 1) tell your agent the task (fix one API or refine a whole module); 2) the skill instructs the agent to inspect declarations, implementation, and nearby tests before rewriting into the standard template; 3) module-level tasks additionally run the @see and Gotchas audits; 4) finish with the narrowest matching validation:
pnpm docgen
pnpm lintProse-only skill edits do not require broad validation.
What are this skill's strengths and limitations?
- Extremely concrete rules: template structure, tag order, example title style, and validation commands are all spelled out, so output is predictable
- Includes dedicated @see and Gotchas audits, well suited to systematic whole-module refinement
- Emphasizes narrow validation, avoiding unnecessary full checks on prose-only edits
- Style rules (e.g. When-to-use must start with Use when/Use to, gerund example titles) guarantee consistency
- Tightly bound to the Effect ecosystem and the jsdocs oxlint rule; barely reusable in other codebases
- Validation depends on pnpm docgen and pnpm lint, requiring an already configured Effect package environment
- Very long rule set — a heavyweight instruction skill that consumes notable context
- The source provides no tests or usage evidence for the skill itself
How does this skill compare with similar options?
Side by side with related skills; every score comes from the same FSRS standard.
| Skill | FS score | Stars | Last updated | License |
|---|---|---|---|---|
| Effect JSDoc Authoring Skill this page | 77 · Strongly recommended | ★ 26k | 3d ago | MIT |
| Anti-Slop: Low-Evidence Pattern Rules for Oxlint | 62 · Recommended | ★ 5.3k | 1mo ago | MIT |
| cmux Backend Development Rules Skill | 51 · Use with care | ★ 28k | today | NOASSERTION |
| Scratchpad Example Extractor | 49 · Use with care | ★ 26k | 3d ago | MIT |
| TradingView Lightweight Charts Skill | 68 · Recommended | ★ 18k | 3d ago | Apache-2.0 |
How did FollowSkills review this skill?
The skill only involves documentation writing, no command execution or file modification, least privilege. Validation steps mention running pnpm docgen and pnpm lint, but require user action. No sensitive data handling or external effects. Source attribution clear: MIT license in repo, but publisher unverified. Thus full trust score.
Skill instructions are clear and consistent, but static review cannot execute validation. There are test files (e.g., integration tests under .repos/alchemy-effect), but not directly for this skill. Thus middle score, static cap at 10.
Clear use case (write or fix JSDoc for Effect public APIs), precise triggers (resolve jsdocs diagnostics, prepare for JSON extraction). Boundaries clear: module-level comments and default exports not supported. Environment fit: all local operations, no overseas services, suitable for Chinese users. Thus full score.
Good information architecture with workflow, formats, rules, audits. Provides install/dependency notes (e.g., pnpm docgen). Versioning guidance (@since requirements) and license. But no changelog and unclear maintainer, publisher unverified. Thus full score because docs are comprehensive, deduction for unclear maintenance responsibility.
From description, skill can complete core task: generate JSDoc compliant with rules. But static assessment cannot verify output directly usable, and since it guides LLM to generate code, marginal value unclear. Thus 7, static cap at 7.
Repo has CI workflows (e.g., .github/workflows/ci.yml) and test files, but not directly for this skill. Static review cannot independently reproduce skill behavior, so cap at 5.
Open a dimension to read why it scored that way
Evidence confidence：Low — Mostly static review, author material or a limited demo; useful for discovery, not high-risk decisions.
See the full review method →