codeply-cli 0.1.0 → 0.2.0

package/skills/security-scan/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: security-scan
+description: Scan your Claude Code configuration (.claude/ directory) for security vulnerabilities, misconfigurations, and injection risks using AgentShield. Checks CLAUDE.md, settings.json, MCP servers, hooks, and agent definitions.
+metadata:
+  origin: ECC
+---
+
+# Security Scan Skill
+
+Audit your Claude Code configuration for security issues using [AgentShield](https://github.com/affaan-m/agentshield).
+
+## When to Activate
+
+- Setting up a new Claude Code project
+- After modifying `.claude/settings.json`, `CLAUDE.md`, or MCP configs
+- Before committing configuration changes
+- When onboarding to a new repository with existing Claude Code configs
+- Periodic security hygiene checks
+
+## What It Scans
+
+| File | Checks |
+|------|--------|
+| `CLAUDE.md` | Hardcoded secrets, auto-run instructions, prompt injection patterns |
+| `settings.json` | Overly permissive allow lists, missing deny lists, dangerous bypass flags |
+| `mcp.json` | Risky MCP servers, hardcoded env secrets, npx supply chain risks |
+| `hooks/` | Command injection via interpolation, data exfiltration, silent error suppression |
+| `agents/*.md` | Unrestricted tool access, prompt injection surface, missing model specs |
+
+## Prerequisites
+
+AgentShield must be installed. Check and install if needed:
+
+```bash
+# Check if installed
+npx ecc-agentshield --version
+
+# Install globally (recommended)
+npm install -g ecc-agentshield
+
+# Or run directly via npx (no install needed)
+npx ecc-agentshield scan .
+```
+
+## Usage
+
+### Basic Scan
+
+Run against the current project's `.claude/` directory:
+
+```bash
+# Scan current project
+npx ecc-agentshield scan
+
+# Scan a specific path
+npx ecc-agentshield scan --path /path/to/.claude
+
+# Scan with minimum severity filter
+npx ecc-agentshield scan --min-severity medium
+```
+
+### Output Formats
+
+```bash
+# Terminal output (default) — colored report with grade
+npx ecc-agentshield scan
+
+# JSON — for CI/CD integration
+npx ecc-agentshield scan --format json
+
+# Markdown — for documentation
+npx ecc-agentshield scan --format markdown
+
+# HTML — self-contained dark-theme report
+npx ecc-agentshield scan --format html > security-report.html
+```
+
+### Auto-Fix
+
+Apply safe fixes automatically (only fixes marked as auto-fixable):
+
+```bash
+npx ecc-agentshield scan --fix
+```
+
+This will:
+- Replace hardcoded secrets with environment variable references
+- Tighten wildcard permissions to scoped alternatives
+- Never modify manual-only suggestions
+
+### Opus 4.6 Deep Analysis
+
+Run the adversarial three-agent pipeline for deeper analysis:
+
+```bash
+# Requires ANTHROPIC_API_KEY
+export ANTHROPIC_API_KEY=your-key
+npx ecc-agentshield scan --opus --stream
+```
+
+This runs:
+1. **Attacker (Red Team)** — finds attack vectors
+2. **Defender (Blue Team)** — recommends hardening
+3. **Auditor (Final Verdict)** — synthesizes both perspectives
+
+### Initialize Secure Config
+
+Scaffold a new secure `.claude/` configuration from scratch:
+
+```bash
+npx ecc-agentshield init
+```
+
+Creates:
+- `settings.json` with scoped permissions and deny list
+- `CLAUDE.md` with security best practices
+- `mcp.json` placeholder
+
+### GitHub Action
+
+Add to your CI pipeline:
+
+```yaml
+- uses: affaan-m/agentshield@v1
+  with:
+    path: '.'
+    min-severity: 'medium'
+    fail-on-findings: true
+```
+
+## Severity Levels
+
+| Grade | Score | Meaning |
+|-------|-------|---------|
+| A | 90-100 | Secure configuration |
+| B | 75-89 | Minor issues |
+| C | 60-74 | Needs attention |
+| D | 40-59 | Significant risks |
+| F | 0-39 | Critical vulnerabilities |
+
+## Interpreting Results
+
+### Critical Findings (fix immediately)
+- Hardcoded API keys or tokens in config files
+- `Bash(*)` in the allow list (unrestricted shell access)
+- Command injection in hooks via `${file}` interpolation
+- Shell-running MCP servers
+
+### High Findings (fix before production)
+- Auto-run instructions in CLAUDE.md (prompt injection vector)
+- Missing deny lists in permissions
+- Agents with unnecessary Bash access
+
+### Medium Findings (recommended)
+- Silent error suppression in hooks (`2>/dev/null`, `|| true`)
+- Missing PreToolUse security hooks
+- `npx -y` auto-install in MCP server configs
+
+### Info Findings (awareness)
+- Missing descriptions on MCP servers
+- Prohibitive instructions correctly flagged as good practice
+
+## Links
+
+- **GitHub**: [github.com/affaan-m/agentshield](https://github.com/affaan-m/agentshield)
+- **npm**: [npmjs.com/package/ecc-agentshield](https://www.npmjs.com/package/ecc-agentshield)

package/skills/seo/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: seo
+description: Audit, plan, and implement SEO improvements across technical SEO, on-page optimization, structured data, Core Web Vitals, and content strategy. Use when the user wants better search visibility, SEO remediation, schema markup, sitemap/robots work, or keyword mapping.
+metadata:
+  origin: ECC
+---
+
+# SEO
+
+Improve search visibility through technical correctness, performance, and content relevance, not gimmicks.
+
+## When to Use
+
+Use this skill when:
+- auditing crawlability, indexability, canonicals, or redirects
+- improving title tags, meta descriptions, and heading structure
+- adding or validating structured data
+- improving Core Web Vitals
+- doing keyword research and mapping keywords to URLs
+- planning internal linking or sitemap / robots changes
+
+## How It Works
+
+### Principles
+
+1. Fix technical blockers before content optimization.
+2. One page should have one clear primary search intent.
+3. Prefer long-term quality signals over manipulative patterns.
+4. Mobile-first assumptions matter because indexing is mobile-first.
+5. Recommendations should be page-specific and implementable.
+
+### Technical SEO checklist
+
+#### Crawlability
+
+- `robots.txt` should allow important pages and block low-value surfaces
+- no important page should be unintentionally `noindex`
+- important pages should be reachable within a shallow click depth
+- avoid redirect chains longer than two hops
+- canonical tags should be self-consistent and non-looping
+
+#### Indexability
+
+- preferred URL format should be consistent
+- multilingual pages need correct hreflang if used
+- sitemaps should reflect the intended public surface
+- no duplicate URLs should compete without canonical control
+
+#### Performance
+
+- LCP < 2.5s
+- INP < 200ms
+- CLS < 0.1
+- common fixes: preload hero assets, reduce render-blocking work, reserve layout space, trim heavy JS
+
+#### Structured data
+
+- homepage: organization or business schema where appropriate
+- editorial pages: `Article` / `BlogPosting`
+- product pages: `Product` and `Offer`
+- interior pages: `BreadcrumbList`
+- Q&A sections: `FAQPage` only when the content truly matches
+
+### On-page rules
+
+#### Title tags
+
+- aim for roughly 50-60 characters
+- put the primary keyword or concept near the front
+- make the title legible to humans, not stuffed for bots
+
+#### Meta descriptions
+
+- aim for roughly 120-160 characters
+- describe the page honestly
+- include the main topic naturally
+
+#### Heading structure
+
+- one clear `H1`
+- `H2` and `H3` should reflect actual content hierarchy
+- do not skip structure just for visual styling
+
+### Keyword mapping
+
+1. define the search intent
+2. gather realistic keyword variants
+3. prioritize by intent match, likely value, and competition
+4. map one primary keyword/theme to one URL
+5. detect and avoid cannibalization
+
+### Internal linking
+
+- link from strong pages to pages you want to rank
+- use descriptive anchor text
+- avoid generic anchors when a more specific one is possible
+- backfill links from new pages to relevant existing ones
+
+## Examples
+
+### Title formula
+
+```text
+Primary Topic - Specific Modifier | Brand
+```
+
+### Meta description formula
+
+```text
+Action + topic + value proposition + one supporting detail
+```
+
+### JSON-LD example
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "Page Title Here",
+  "author": {
+    "@type": "Person",
+    "name": "Author Name"
+  },
+  "publisher": {
+    "@type": "Organization",
+    "name": "Brand Name"
+  }
+}
+```
+
+### Audit output shape
+
+```text
+[HIGH] Duplicate title tags on product pages
+Location: src/routes/products/[slug].tsx
+Issue: Dynamic titles collapse to the same default string, which weakens relevance and creates duplicate signals.
+Fix: Generate a unique title per product using the product name and primary category.
+```
+
+## Anti-Patterns
+
+| Anti-pattern | Fix |
+| --- | --- |
+| keyword stuffing | write for users first |
+| thin near-duplicate pages | consolidate or differentiate them |
+| schema for content that is not actually present | match schema to reality |
+| content advice without checking the actual page | read the real page first |
+| generic “improve SEO” outputs | tie every recommendation to a page or asset |
+
+## Related Skills
+
+- `seo-specialist`
+- `frontend-patterns`
+- `brand-voice`
+- `market-research`

package/skills/skill-comply/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: skill-comply
+description: Visualize whether skills, rules, and agent definitions are actually followed — auto-generates scenarios at 3 prompt strictness levels, runs agents, classifies behavioral sequences, and reports compliance rates with full tool call timelines
+metadata:
+  origin: ECC
+tools: Read, Bash
+---
+
+# skill-comply: Automated Compliance Measurement
+
+Measures whether coding agents actually follow skills, rules, or agent definitions by:
+1. Auto-generating expected behavioral sequences (specs) from any .md file
+2. Auto-generating scenarios with decreasing prompt strictness (supportive → neutral → competing)
+3. Running `claude -p` and capturing tool call traces via stream-json
+4. Classifying tool calls against spec steps using LLM (not regex)
+5. Checking temporal ordering deterministically
+6. Generating self-contained reports with spec, prompts, and timelines
+
+## Supported Targets
+
+- **Skills** (`skills/*/SKILL.md`): Workflow skills like search-first, TDD guides
+- **Rules** (`rules/common/*.md`): Mandatory rules like testing.md, security.md, git-workflow.md
+- **Agent definitions** (`agents/*.md`): Whether an agent gets invoked when expected (internal workflow verification not yet supported)
+
+## When to Activate
+
+- User runs `/skill-comply <path>`
+- User asks "is this rule actually being followed?"
+- After adding new rules/skills, to verify agent compliance
+- Periodically as part of quality maintenance
+
+## Usage
+
+```bash
+# Full run
+uv run python -m scripts.run ~/.claude/rules/common/testing.md
+
+# Dry run (no cost, spec + scenarios only)
+uv run python -m scripts.run --dry-run ~/.claude/skills/search-first/SKILL.md
+
+# Custom models
+uv run python -m scripts.run --gen-model haiku --model sonnet <path>
+```
+
+## Key Concept: Prompt Independence
+
+Measures whether a skill/rule is followed even when the prompt doesn't explicitly support it.
+
+## Report Contents
+
+Reports are self-contained and include:
+1. Expected behavioral sequence (auto-generated spec)
+2. Scenario prompts (what was asked at each strictness level)
+3. Compliance scores per scenario
+4. Tool call timelines with LLM classification labels
+
+### Advanced (optional)
+
+For users familiar with hooks, reports also include hook promotion recommendations for steps with low compliance. This is informational — the main value is the compliance visibility itself.

package/skills/skill-scout/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: skill-scout
+description: Search existing local, marketplace, GitHub, and web skill sources before creating a new skill. Use when the user wants to create, build, fork, or find a skill for a workflow.
+metadata:
+  origin: community
+---
+
+# Skill Scout
+
+Use this skill before creating a new skill. The goal is to avoid duplicating
+existing community or marketplace work, while still vetting anything external
+before adoption.
+
+Source: salvaged from stale community PR #1232 by `redminwang`.
+
+## When to Use
+
+- The user says "create a skill", "build a skill", "make a skill", or "new
+  skill".
+- The user asks "is there a skill for X?" or "does a skill exist that does Y?"
+- The user describes a workflow and you are about to suggest creating a new
+  skill.
+- The user wants to fork or extend an existing skill.
+
+If the user explicitly says to skip search or create from scratch, acknowledge
+that and proceed with the requested creation workflow.
+
+## How It Works
+
+### Step 1 - Capture Intent
+
+Extract:
+
+- The task the skill should perform.
+- The trigger conditions for using it.
+- The domain, tools, frameworks, or data sources involved.
+- Three to five search keywords plus useful synonyms.
+
+### Step 2 - Search Local Sources
+
+Search installed and marketplace skill names first. Local sources are preferred
+because they are already part of the user's environment.
+
+```bash
+find ~/.claude/skills -maxdepth 2 -name SKILL.md 2>/dev/null | grep -iE "keyword|synonym"
+find ~/.claude/plugins/marketplaces -path '*/skills/*/SKILL.md' 2>/dev/null | grep -iE "keyword|synonym"
+```
+
+Then search frontmatter descriptions:
+
+```bash
+grep -RilE "keyword|synonym" ~/.claude/skills ~/.claude/plugins/marketplaces 2>/dev/null
+```
+
+### Step 3 - Search Remote Sources
+
+Use available GitHub and web search tools. Prefer concise queries:
+
+```bash
+gh search repos "claude code skill keyword" --limit 10 --sort stars
+gh search code "name: keyword" --filename SKILL.md --limit 10
+```
+
+For web search, use at most three targeted queries such as:
+
+```text
+"claude code skill" keyword
+"SKILL.md" keyword
+"everything-claude-code" keyword
+```
+
+### Step 4 - Vet External Matches
+
+Before recommending any external skill for adoption or forking:
+
+- Read the `SKILL.md` frontmatter and instructions.
+- Look for unexpected shell commands, file writes, network calls, credential
+  handling, or package installs.
+- Check whether the repository appears maintained.
+- Prefer copying into a fresh local branch and reviewing the diff over editing
+  marketplace originals.
+
+### Step 5 - Rank Results
+
+Rank candidates by:
+
+1. Exact keyword match in the skill name.
+2. Keyword or synonym match in description.
+3. Local installed or marketplace source.
+4. Maintained GitHub source with recent activity.
+5. Web-only mention.
+
+Cap the final list at 10 results.
+
+### Step 6 - Present Decision Options
+
+Give the user a short table:
+
+| Option | Meaning |
+| --- | --- |
+| Use existing | Invoke or install a matching skill as-is. |
+| Fork or extend | Copy the closest skill and modify it. |
+| Create fresh | Build a new skill after confirming no close match exists. |
+
+Only create a new skill after the user chooses that path or after the search
+finds no close match.
+
+## Examples
+
+### Result Table
+
+```markdown
+| # | Skill | Source | Why it matches | Gap |
+| --- | --- | --- | --- | --- |
+| 1 | article-writing | Local ECC | Drafts articles and guides | Not focused on release notes |
+| 2 | content-engine | Local ECC | Multi-format content workflow | Heavier than needed |
+| 3 | blog-writer | GitHub | Blog writing skill with recent commits | Needs security review |
+```
+
+### User-Facing Summary
+
+```markdown
+I found two close local matches and one external candidate. The closest fit is
+`article-writing`; it covers drafting and revision, but it does not include the
+release-note checklist you asked for. I can either use it as-is, fork it into a
+release-note variant, or create a fresh skill.
+```
+
+## Anti-Patterns
+
+- Do not jump directly to new skill creation when a search is reasonable.
+- Do not install external skills without reading them first.
+- Do not present a long unranked list of weak matches.
+- Do not treat web-only mentions as trusted sources.
+- Do not edit installed marketplace originals in place.
+
+## Related
+
+- `search-first` - General search-before-building workflow.
+- `skill-stocktake` - Audit installed skills for health, duplicates, and gaps.
+- `agent-sort` - Categorize and organize existing agents and skills.