🚀 SKIL — Claude Skills Framework

A professional-grade setup for Claude AI agents, commands, skills, and automation rules. Turn Claude into a full development team with specialized agents, reusable commands, and context-aware instructions.

✨ Features

• 6 AI Agents — Code review, debugging, testing, refactoring, documentation, security
• 3 Slash Commands — /fix-issue, /deploy, /pr-review for common workflows
• Context-Aware Rules — Auto-loaded instructions for frontend, database, and API code
• Design System — Complete UI standards with colors, typography, spacing, animations
• Git Hooks — Pre-commit validation (type check → lint → test)
• Project Brain — Central CLAUDE.md file with all conventions and tech stack

📦 Installation

Option 1: Global Installation (Recommended)

npm install -g skil

Then run from anywhere:

skil

Option 2: Via npx (No installation)

npx skil

Option 3: Local Project Installation

npm install skil
npm run skills

🎯 Quick Start

1. Verify Setup

skil

Output:

✅ All skills configured correctly!

📚 Available agents:
  • code-reviewer
  • debugger
  • test-writer
  • refactorer
  • doc-writer
  • security-auditor

⚡ Available commands:
  • /fix-issue [number]
  • /deploy [environment]
  • /pr-review [number]

2. Use Claude with Agents

In Claude Chat or VS Code Copilot:

/code-reviewer

or assign to specific agents:

@code-reviewer Please review this PR for security issues

3. Use Slash Commands

/fix-issue 123          # Fix GitHub issue #123
/deploy staging         # Deploy to staging
/pr-review 456          # Review pull request #456

📚 What's Included

Agents (.claude/agents/)

Each agent is a specialist with its own instructions:

• code-reviewer — Catches bugs, security issues, and quality problems
• debugger — Diagnoses and fixes runtime errors
• test-writer — Writes comprehensive unit and integration tests
• refactorer — Improves code quality and reduces complexity
• doc-writer — Creates clear documentation
• security-auditor — Finds and fixes vulnerabilities

Commands (.claude/commands/)

Reusable command templates:

• fix-issue — Read issue → find code → fix → test → commit
• deploy — Build → verify → deploy → smoke test
• pr-review — Security → performance → quality → merge decision

Rules (.claude/rules/)

Context-aware instructions auto-loaded based on file type:

• frontend.md — React, Tailwind, shadcn/ui, state management
• database.md — Prisma, migrations, validation, performance
• api.md — Endpoints, auth, errors, security

Skills (.claude/skills/)

Domain-specific instruction sets:

• frontend-design — Color palette, typography, spacing, animations, dark mode

Settings (.claude/settings.json)

Controls permissions, hooks, and model configuration:

• Allowed/denied commands
• Pre/post tool use hooks
• Default agent and model
• Auto-memory settings

Project Brain (CLAUDE.md)

Central documentation loaded every Claude session:

• Tech stack: Next.js 14, React 18, TypeScript, Tailwind, Zustand, Prisma
• Core commands for development
• Code conventions (TypeScript, React, state, styling, testing)
• Folder structure
• Git workflow
• Deployment process
• Quality gates

🔧 Customization

Add Your Own Agent

1. Create .claude/agents/my-agent.md:

---
name: my-agent
description: What this agent does
tools: Read, Write, Bash
model: sonnet
---

You are a specialist in...

## Your Process
Step 1: ...
Step 2: ...

2. Add to .claude/settings.json permissions if needed

Add Your Own Command

1. Create .claude/commands/my-command.md:

---
name: my-command
argument-hint: [argument-name]
---

My command does:
1. Step 1
2. Step 2

Customize Rules

Edit .claude/rules/frontend.md, .claude/rules/database.md, or .claude/rules/api.md to match your project conventions.

Update Project Brain

Edit CLAUDE.md with your:

• Actual tech stack
• Development commands
• Team conventions
• Deployment process

📂 Directory Structure

.claude/
├── agents/                    # AI team members (6 files)
├── commands/                  # Slash commands (3 files)
├── hooks/                     # Git hooks (pre-commit, lint-on-save)
├── rules/                     # Context rules (frontend, database, api)
├── skills/
│   └── frontend-design/       # Design system
└── settings.json              # Configuration

CLAUDE.md                       # Project brain (root)
scripts/
└── init-skills.js             # Initialization script
package.json                   # Project metadata

🚀 Publishing to npm

Prerequisites

• npm account (create at https://www.npmjs.com)
• Logged in: npm login

Steps

1. Update package.json

{
  "name": "your-org/skil",
  "version": "1.0.0",
  "repository": {
    "type": "git",
    "url": "https://github.com/your-org/skil"
  }
}

2. Create .npmignore

.git
.github
.claude/.gitignore
node_modules
*.test.js
.env
.env.local

3. Publish

npm publish --access public

4. Users can now install globally

npm install -g your-org/skil
your-org-skil

Or via npx:

npx your-org/skil

🎓 Usage Examples

Example 1: Fix a Bug

Claude, use /fix-issue 42

Step 1: Read issue
Step 2: Find code
Step 3: Implement fix
Step 4: Write regression test
Step 5: Verify all tests pass
Step 6: Commit with message

Example 2: Code Review

@code-reviewer Please review this code for:
1. Security issues
2. Performance problems
3. Code quality

Use your standard review process.

Example 3: Deploy Changes

/deploy staging

Build → Verify → Deploy → Monitor → Smoke test

⚙️ Configuration

settings.json

{
  "permissions": {
    "allow": ["Bash(npm run *)", "Read(**/*)", "Write(src/**)"],
    "deny": ["Read(.env)", "Bash(rm -rf *)"]
  },
  "model": "claude-sonnet-4-6",
  "autoMemoryEnabled": true,
  "defaultAgent": "code-reviewer"
}

Git Hooks

Pre-commit runs:

1. TypeScript type check
2. ESLint linting
3. Test suite

Lint-on-save auto-formats code after edits.

🔐 Security

• No secrets in code (use .env.local)
• Pre-commit validation blocks bad commits
• Input validation on all forms
• Encrypted sensitive fields in database
• Security audit agent checks for vulnerabilities

📖 Documentation

• Agents Guide — Detailed agent instructions
• Commands Guide — Command templates
• Rules Guide — Context-aware rules
• Design System — UI standards
• Project Brain — Tech stack & conventions

🤝 Contributing

To improve this framework:

1. Clone the repo
2. Create a feature branch
3. Make changes to .claude/ files or CLAUDE.md
4. Test with npm run skills
5. Commit and create PR

📝 License

MIT

🎯 Next Steps

1. Run skil to verify installation
2. Update CLAUDE.md with your project details
3. Customize .claude/rules/ for your conventions
4. Add your own agents and commands
5. Publish to npm if sharing with team

💡 Tips

• Load agents by typing their name: @code-reviewer
• Use slash commands in Claude chat: /fix-issue 123
• Rules auto-load based on file type you're editing
• Check .claude/settings.json to control permissions
• Memory persists across sessions (in .claude/memory/)

❓ FAQ

Q: Can I use this without publishing to npm? A: Yes! Use locally with npm run skills or copy .claude/ to any project.

Q: Can I add more agents? A: Yes! Create new files in .claude/agents/ following the template.

Q: Does this work offline? A: Yes! All files are local. Only Claude API calls need internet.

Q: Can I share this with my team? A: Yes! Publish to npm as a package or share the .claude/ folder.

Q: How do I customize agents? A: Edit .claude/agents/ files directly. Each file is just Markdown with instructions.

Made with ❤️ for developers who want Claude as their full development team.

Questions? Check the Project Brain or open an issue on GitHub.