skill-authoring

Design and development best practices for Claude Code skills, MCP tools, and AI agent capabilities. Use when creating skills, writing SKILL.md files, designing tool descriptions, or optimizing triggers. Triggers on "create a skill", "skill template", "write skill instructions", SKILL.md, metadata.json, progressive disclosure, trigger optimization, MCP tool design, or skill testing. Does NOT cover specific frameworks or languages (use dedicated skills).

インストールへ移動

リポジトリ: pproenca/dot-skills
ソースの最終更新活動: 2026年5月14日 18:16
検出された SKILL.md の言語: 英語
スター: 194
フォーク: 17

インストール方法

デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。

Codex または Claude でインストールこの Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。

直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。

npx skills add https://github.com/pproenca/dot-skills --skill skill-authoring

コマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。

ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。

ソースファイルを確認

インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。

ファイルエクスプローラー

52 ファイル

SKILL.md

ソースの指示 · 読み取り専用プレビュー

検索に戻るインストールに戻る

drizzle-nextjs-postgres

Drizzle ORM against PostgreSQL inside a Next.js App Router app. Covers client construction (globalThis singleton across HMR, serverless pool sizing, `prepare:false` behind PgBouncer/Supavisor, driver choice when you need interactive transactions, `server-only`), reads in Server Components under Next.js 16 Cache Components (`use cache` superseding `unstable_cache` and the `revalidate`/`dynamic` segment configs, Suspense boundaries, React `cache()` dedupe), Server Actions (authorization inside the action, `updateTag` vs `revalidateTag`, `after()`), Postgres schema types (timestamptz, identity vs serial, jsonb, numeric-as-string, bigint modes), drizzle-kit migrations (generate vs push, CONCURRENTLY outside the migrator, NOT VALID constraints, rename prompts), transactions and pooled connections, and Postgres query traps (keyset pagination, count cost, driver-dependent `db.execute()` shape, NOT IN nulls, prepared statements). Use when writing or reviewing Drizzle + Postgres code in Next.js.

2026-07-24

relational-data-modeling

Corrects the wrong defaults a model has when designing a relational schema — the DDL decisions an experienced engineer makes differently. Use when creating or reviewing tables, migrations, ER models, or ORM schema definitions. Covers identity and keys (surrogate vs natural, identity vs serial, uuidv7, composite keys that make cross-tenant references impossible), relationships (polymorphic foreign keys the database cannot enforce, referential actions, unindexed FK columns, disjoint subtypes), invariants the engine can prove instead of application code (EXCLUDE, partial unique indexes, CHECK limits, deferrable cycles, NOT VALID), types (timestamptz, exact money, range types, enum vs lookup table), derived and encoded data (generated columns, JSONB as an escape hatch), and time (events vs in-place updates, soft-delete flags that silently disable constraints, temporal keys). NOT for query tuning, index selection for read paths, or connection pooling.

2026-07-23

relational-database-design

Distills a logical relational-database design methodology into rules an agent applies while designing or reviewing a schema. Covers the design sequence (mission → tables → fields → keys → relationships → business rules → views → integrity review), one-subject-per-table decomposition, atomic single-valued fields, candidate/primary/foreign keys, relationship types with deletion rules and participation, the four levels of data integrity, database-vs-application business rules, validation tables, views for derived data, and the flat-file / spreadsheet / RDBMS-driven antipatterns to avoid. The structure is logical and RDBMS-agnostic, and normalized by construction. Use when designing a new relational schema, reviewing or refactoring an existing one, resolving redundant or repeating data, choosing keys, modeling relationships, or deciding where a constraint belongs.

2026-07-23

このリポジトリのすべてを見る

name

skill-authoring

description

AI Agent Skills Best Practices

Design and development guide for AI agent skills, including Claude Code skills and MCP tools. Contains 46 rules across 8 categories, prioritized by impact to guide skill creation, review, and optimization.

When to Apply

Creating new Claude Code skills or MCP tools
Writing or reviewing SKILL.md metadata and descriptions
Optimizing skill trigger reliability
Structuring content for progressive disclosure
Testing skill activation and behavior
Designing tool interfaces for agent workflows

Core Principles

1. Descriptions drive activation. Claude selects skills based on description matching against user intent. Include specific capabilities, trigger keywords, and negative cases. A skill with a vague description activates inconsistently or never.

2. Front-load critical instructions. Claude may truncate long content. Place non-negotiable rules in the first 100 lines. Bury important constraints at the end and they get ignored.

3. Progressive disclosure saves tokens. Load detailed content only when needed. A 2000-line skill wastes context on every activation. Structure as: SKILL.md (overview) → references/ (details) → scripts/ (execution).

4. Test activation, not just execution. A skill that works perfectly but never triggers provides zero value. Test with real user phrases, synonyms, and edge cases before deployment.

5. One skill per domain. Overlapping skills create activation conflicts. Split by clear boundaries (language, framework, workflow stage) with distinct trigger keywords.

Rule Categories

Priority	Category	Impact	Prefix
1	Skill Metadata Design	CRITICAL	`meta-`
2	Description Engineering	CRITICAL	`desc-`
3	Content Structure	HIGH	`struct-`
4	Trigger Optimization	HIGH	`trigger-`
5	Progressive Disclosure	MEDIUM-HIGH	`prog-`
6	MCP Tool Design	MEDIUM	`mcp-`
7	Testing and Validation	MEDIUM	`test-`
8	Maintenance and Distribution	LOW-MEDIUM	`maint-`

Quick Reference

1. Skill Metadata Design (CRITICAL)

meta-name-format - Use lowercase hyphenated skill names
meta-name-hyphen-boundaries - Never start or end names with hyphens
meta-name-no-consecutive-hyphens - Avoid consecutive hyphens in names
meta-name-uniqueness - Ensure skill names are globally unique
meta-required-frontmatter - Include all required frontmatter fields
meta-allowed-frontmatter-fields - Use only allowed frontmatter fields
meta-frontmatter-yaml-syntax - Use valid YAML frontmatter syntax
meta-name-length - Keep skill names under 64 characters
meta-directory-match - Match skill name to directory name

2. Description Engineering (CRITICAL)

desc-specific-capabilities - Name specific capabilities in description
desc-trigger-keywords - Include user trigger keywords in description
desc-third-person-voice - Write descriptions in third person
desc-length-optimization - Optimize description length for discovery
desc-avoid-vague-terms - Avoid vague terms in descriptions
desc-differentiate-similar-skills - Differentiate similar skills with distinct triggers
desc-include-negative-cases - Include negative cases for precision

3. Content Structure (HIGH)

struct-header-hierarchy - Use consistent header hierarchy
struct-instructions-first - Put critical instructions early in content
struct-imperative-instructions - Write instructions in imperative mood
struct-code-blocks-with-language - Specify language in code blocks
struct-line-limit - Keep SKILL.md under 500 lines
struct-single-responsibility - One skill per domain
project-conventions - Preserve repository-specific skill conventions

4. Trigger Optimization (HIGH)

trigger-slash-command-aliases - Include slash command aliases in description
trigger-file-type-patterns - Include file type patterns in description
trigger-workflow-stages - Reference workflow stages in description
trigger-error-patterns - Include error patterns in debugging skills
trigger-synonym-coverage - Cover synonyms and alternate phrasings

5. Progressive Disclosure (MEDIUM-HIGH)

prog-three-level-disclosure - Implement three-level progressive disclosure
prog-one-level-deep-links - Limit reference links to one level deep
prog-scripts-execute-not-read - Execute scripts instead of reading code
prog-lazy-load-examples - Lazy load examples and reference material
prog-mutual-exclusion - Separate mutually exclusive contexts

6. MCP Tool Design (MEDIUM)

mcp-tool-naming - Use clear action-object tool names
mcp-parameter-descriptions - Document all tool parameters
mcp-error-messages - Return actionable error messages
mcp-tool-scope - Design single-purpose tools
mcp-allowed-tools - Use allowed-tools for safety constraints
mcp-idempotent-operations - Design idempotent tool operations

7. Testing and Validation (MEDIUM)

test-trigger-phrases - Test skill activation with real user phrases
test-edge-cases - Test skills with edge case inputs
test-negative-scenarios - Test that skills do NOT trigger on unrelated requests
test-instruction-clarity - Test instructions with fresh context

8. Maintenance and Distribution (LOW-MEDIUM)

maint-semantic-versioning - Use semantic versioning for skill releases
maint-changelog - Maintain a changelog for skill updates
maint-plugin-packaging - Package skills as plugins for distribution
maint-audit-security - Audit skills before installing from external sources

Creating Rules

Copy assets/templates/_template.md and follow the frontmatter schema:

---
title: Rule Title Here
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
impactDescription: Quantified impact (e.g., "2-10x improvement")
tags: prefix, technique, related-concepts
---

Reference files use the pattern: references/{prefix}-{slug}.md

skill-authoring

インストール方法

ソースファイルを確認

AI Agent Skills Best Practices

When to Apply

Core Principles

Rule Categories

Quick Reference

1. Skill Metadata Design (CRITICAL)

2. Description Engineering (CRITICAL)

3. Content Structure (HIGH)

4. Trigger Optimization (HIGH)

5. Progressive Disclosure (MEDIUM-HIGH)

6. MCP Tool Design (MEDIUM)

7. Testing and Validation (MEDIUM)

8. Maintenance and Distribution (LOW-MEDIUM)

Creating Rules

References

AI Agent Skills Best Practices

When to Apply

Core Principles

Rule Categories

Quick Reference

1. Skill Metadata Design (CRITICAL)

2. Description Engineering (CRITICAL)

3. Content Structure (HIGH)

4. Trigger Optimization (HIGH)

5. Progressive Disclosure (MEDIUM-HIGH)

6. MCP Tool Design (MEDIUM)

7. Testing and Validation (MEDIUM)

8. Maintenance and Distribution (LOW-MEDIUM)

Creating Rules

References

skill-authoring

ソース情報

インストール方法

ソースファイルを確認

このリポジトリの他の Skills

このリポジトリの他の Skills

AI Agent Skills Best Practices

When to Apply

Core Principles

Rule Categories

Quick Reference

1. Skill Metadata Design (CRITICAL)

2. Description Engineering (CRITICAL)

3. Content Structure (HIGH)

4. Trigger Optimization (HIGH)

5. Progressive Disclosure (MEDIUM-HIGH)

6. MCP Tool Design (MEDIUM)

7. Testing and Validation (MEDIUM)

8. Maintenance and Distribution (LOW-MEDIUM)

Creating Rules

References

AI Agent Skills Best Practices

When to Apply

Core Principles

Rule Categories

Quick Reference

1. Skill Metadata Design (CRITICAL)

2. Description Engineering (CRITICAL)

3. Content Structure (HIGH)

4. Trigger Optimization (HIGH)

5. Progressive Disclosure (MEDIUM-HIGH)

6. MCP Tool Design (MEDIUM)

7. Testing and Validation (MEDIUM)

8. Maintenance and Distribution (LOW-MEDIUM)

Creating Rules

References