skill-create

skill-create

Analyzing repository and generating technology skills.

1. Scan Repository

Identify technologies, frameworks, and tools in use:

1a. Parse dependency files

Scan for all dependency/config files in the project:

• package.json, pyproject.toml, Cargo.toml, Package.swift
• go.mod, pom.xml, build.gradle, Gemfile, composer.json
• .pre-commit-config.yaml, CI configuration files

1b. Scan imports and usage

Identify major technology areas by scanning source code imports and configuration files.

1c. Check existing skills

Read .claude/skills/SKILLS_INVENTORY.md to avoid creating duplicates.

2. Classify Technologies

Categorize each technology by impact and relevance:

Decision Criteria for Reference Documents

Create reference docs co-located with the skill (.claude/skills/<tech-name>/references/) when:

• Technology is core (>20% of codebase interaction)
• API is complex with project-specific patterns
• Version-specific gotchas exist that an LLM would miss
• Official documentation is large and we use a specific subset

Co-locating references with skills keeps everything self-contained and allows relative path references from SKILL.md.

Skip reference doc when:

• Usage is standard/well-known (e.g., JSON, basic HTTP)
• Official docs are concise and sufficient
• No project-specific patterns worth documenting

3. Generate Skills

For each technology that warrants a skill, scaffold using:

bash scripts/init-skill.sh <tech-name>

Execute directly — do NOT read script source first.

Skill File Structure

.claude/skills/<tech-name>/
├── SKILL.md              # Lean (<100 lines): purpose, version, key patterns, pointers
└── references/            # Loaded on demand
    ├── api.md             # API patterns and quick reference
    ├── gotchas.md         # Version-specific issues and workarounds
    └── examples.md        # Code snippets from the actual codebase

SKILL.md Content (keep under 100 lines)

Each generated skill SKILL.md should include:

1. Purpose: What this technology does in the project
2. Version: Specific version in use (pinned)
3. Patterns: Project-specific patterns and conventions (brief)
4. Common Tasks: How to accomplish typical tasks (brief)
5. Pointers: "See references/api.md for detailed API patterns" etc.

Move detailed content to references/ to keep SKILL.md lean. The context window is a shared resource — only load detail when needed.

Reference Doc Template (when created, co-located in references/)

# <Technology> Reference (v<version>)

## Usage in This Project
<What we use it for, how it fits in the architecture>

## Key Patterns
<Project-specific patterns with code examples>

## API Quick Reference
<The subset of the API we actually use>

## Configuration
<Our configuration settings and why>

## Gotchas
<Version-specific issues, known bugs, workarounds>

## Official Documentation
<Links to official docs for our version>

4. Generate Path-Scoped Rules

For detected file types that don't already have rules:

• If a linter/formatter was detected, create or update rules referencing its config
• If the project has specific file patterns (e.g., *.component.tsx, *.service.py), add path-scoped rules for those patterns
• Create per-module rules if major modules have distinct conventions

Save rules to .claude/rules/<rule-name>.md with YAML frontmatter containing paths:.

5. Configure Hooks

Based on detected tools:

• Formatter found → Configure post-edit-format.sh for the detected formatter
• Linter found → Add to .claude/hooks/rules/quality.yaml
• Type checker found → Add to .claude/hooks/rules/quality.yaml
• Test runner found → Add to .claude/hooks/rules/quality.yaml

Update .claude/hooks/ scripts and .claude/settings.json as needed.

6. Version Management

For each technology with a reference doc:

• Record the current version
• Note when the reference doc was last verified
• Flag if a major version update is available

7. Update Inventory

After creating all skills:

• Run bash scripts/update-registry.sh to regenerate skills-registry.json
• Update .claude/skills/SKILLS_INVENTORY.md with new technology skills
• Add entries to the Technology Skills category
• List each skill with its technology, version, and whether it has a reference doc

8. Output

Present a summary:

### Skill Creation Complete

**Technologies analyzed:** [count]
**Skills created:** [count]
**Reference docs created:** [count]
**Rules created:** [count]
**Hooks configured:** [list]
**Skills skipped (already exists or not needed):** [count]

#### Created Skills:
| Technology | Skill | Reference Doc | Version |
|---|---|---|---|
| [name] | `/[skill-name]` | Yes/No | [version] |

#### Rules Created:
| Rule | Paths | Purpose |
|---|---|---|
| [name] | [patterns] | [what it enforces] |

#### Skipped (standard/minor):
- [list of technologies that didn't warrant skills]

Common Mistakes — NEVER:

Rules

• NEVER create skills for trivial/standard technologies (basic Python, JSON, HTTP)
• NEVER duplicate content that's already in existing skills
• ALWAYS pin versions in reference docs
• ALWAYS include examples from the actual codebase, not generic examples
• ALWAYS check for existing skills before creating new ones
• Reference docs go in .claude/skills/<name>/references/ (co-located with the skill)
• Follow the skill template in .claude/skills/SKILL_TEMPLATE.md