Contributing to agent-skills

Repository Structure

agent-skills/
├── skills/
│   ├── skill-name/
│   │   ├── SKILL.md          # Skill definition (required)
│   │   └── references/       # Supporting documents (optional)
│   │       ├── guide.md       # English version
│   │       └── guide.ja.md   # Japanese version
│   └── ...
├── LICENSE
├── README.md
└── AGENTS.md

Adding a New Skill

1. Create a directory under skills/ with your skill name (kebab-case)
2. Add a SKILL.md with the required frontmatter
3. Add any reference files under references/
4. Update the skills table in README.md and README.ja.md

SKILL.md Format

Every skill must have a SKILL.md with YAML frontmatter:

---
name: skill-name          # Must match directory name
description: |
  Brief description of what the skill does.
  Include trigger phrases for discoverability.
license: MIT
---

The body of SKILL.md contains the full instructions the agent follows when the skill is invoked.

Guidelines

• name: Must match the directory name exactly
• description: Keep under 1024 characters. Include trigger phrases in all supported languages for discoverability
• license: Use MIT unless you have a specific reason not to

Bilingual Support

This repository follows a bilingual (English/Japanese) pattern:

• *.md — English version (primary)
• *.ja.md — Japanese version

SKILL.md body must be written in English. Use a Language Rules section to define auto-detection and reference file selection for Japanese support.

Skills should auto-detect the user's language and reference the appropriate files.

Code Style

• Write clear, concise instructions
• Avoid hardcoding tool names or MCP server references — use generic descriptions instead
• Keep SKILL.md under 500 lines
• Use AskUserQuestion for interactive decisions, not free-form text prompts

For detailed SKILL.md authoring conventions, see docs/skill-style-guide.md.

Testing

Before submitting, verify:

1. SKILL.md frontmatter name matches directory name
2. All referenced files exist
3. No hardcoded MCP tool names (e.g., mcp__serena__, Context7)
4. SKILL.md is under 500 lines
5. bash scripts/check-skill-line-budget.sh passes for the whole repository
6. bash skills/agent-delegate/references/scripts/tests/check_skill_quality.sh skills/*/SKILL.md passes for the whole repository
7. Changes to the quality checker pass bash skills/agent-delegate/references/scripts/tests/check_skill_quality_contract.sh
8. For reference-split changes, bash scripts/tests/check-skill-reference-split-contract.sh passes

コーディングルール

実装時のコーディングルールは以下のファイルに従ってください:

• docs/coding-rules.md — spec-rules-init で生成された品質ルール集
• docs/review_rules.md — コードレビュー・セカンドオピニオン用のレビュー基準

Development Workflow

開発フロー（Issue → 実装 → PR）は以下のファイルに従ってください:

• docs/issue-to-pr-workflow.md — spec-workflow-init で生成された開発ワークフロー

Session Handover

At session start, if local handover files exist (handover.md or .handover/current.md), read them before making changes.

Verify the handover against the current repository state before trusting it:

• current branch
• current HEAD
• working tree status
• referenced important files

Summarize inherited context, note stale or conflicting information, and continue from Next Action only when it is safe and obvious. Ask before destructive, external-facing, or ambiguous actions.