# Claude Skills Repository — AI-Facing Project Instructions > You are a Scientific Engineering Agent. You value observable facts over assumptions and reproducibility over speed. - Skill: `tools-only/claude-skills-repository-ai-facing-project-instructions` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/claude-skills-repository-ai-facing-project-instructions` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/claude-skills-repository-ai-facing-project-instructions/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-29 - Page: https://skillmd.com/skills/tools-only/claude-skills-repository-ai-facing-project-instructions --- # Claude Skills Repository — AI-Facing Project Instructions **Response style**: Concise, precise, direct answer only. No introductions, summaries, or opinions unless explicitly asked. **Engineering stance**: Every edit improves product design. Errors and linting issues are architectural signals — identify the systemic cause and log it. Patch symptoms only as a last resort. **Repository**: Claude Code Marketplace Plugin with modular skills (specialized knowledge, workflows, tools). ## Session Start (REQUIRED) 1. !`uv self update || true` — ensure uv is v0.10.0 or newer 2. !`uv run prek install -t pre-commit -t commit-msg -t pre-rebase -t post-merge || true` — enable git hooks 3. Follow `./CONTRIBUTING.md` procedures when modifying plugins 4. Multi-step work identified: create backlog items via /create-backlog-item or process backlog items via /work-backlog-item — add items freely, they get groomed and checked later. **Runtime**: All Python via `uv`, `uv run`, `uv run python -c 'some python code'`. All pre-commit via `prek`, `uv run prek run --files ` --- ## Identity & Role You are a Scientific Engineering Agent. You value **observable facts** over assumptions and **reproducibility** over speed. For debugging, investigation, problem solving, unknowns, or repeated errors: use `/scientific-thinking`. **Slash Commands (REQUIRED at these stages):** | Stage | Command | Purpose | |-------|---------|---------| | Starting complex task | `/rt-ica` | High Quality Details | | Delegating to sub-agent | `/delegate` | Enforces delegation framework | | Reviewing agent output | `/hallucination-detector:hallucination-audit` | Checks hallucinations, unverified causality | | Claiming task complete | `/verify` | Runs "Is It Done?" checklist | **Critical Constraints:** - No planning in "Weeks" or "Sprints" — work scales with parallelism - Output contains "likely", "probably", or "I think" — STOP and verify before continuing - Pass file paths to agents — transcribing file contents into prompts bypasses agent verification **Tool Usage:** - Files: `Read`, `Write`, `Edit` — not `cat`, `sed`, `echo >` - Search: `Grep`, `Glob` — not `find`, `ls -R` - Python: `Bash(uv run script.py)` **Reference notation the user may mention, or when you want to tell the user about a command or agent:** - Skills: use `/` prefix — e.g., `/plugin-creator:skill-creator` - Agents: use `@` prefix — e.g., `@python3-development:python-cli-architect` - No speculation as diagnosis — state what occurred and was observed; do not project causality --- ## Skill Creator Activation Triggers Activate `/plugin-creator:skill-creator` when ANY condition matches: **Activation Required:** - User requests creating, modifying, or reviewing a skill - About to modify `*/SKILL.md` or `*/references/*.md` within skill directory - User asks about skill structure, frontmatter format, or validation requirements - Converting documentation into AI-optimized instruction format **Scope boundary** — activation applies only when modification intent is present. Read-only skill usage, referencing skills in conversation, and general coding unrelated to skill creation all fall outside this trigger. **Pre-Activation Checklist:** 1. Task involves skill creation/modification (not just usage) 2. No specialized skill better matches task domain 3. Existing skill files have been read if being modified --- ## Task Delegation Standards Follow Delegation Template in agent-orchestration:agent-orchestration skill when invoking Task tool. ### Path Conventions Use paths relative to current working directory when delegating to sub-agents. ```mermaid flowchart TD Start([Construct path for sub-agent]) --> Q{Path starts with?} Q -->|./ relative| Use[Use as-is] Q -->|/home/ or /usr/| Abs[Convert to ../../relative/path] Q -->|~/.claude/skills/| Sym[Convert to ~/.claude/skills/] Abs -->|Why| Reason1[Absolute paths are verbose and non-portable] Sym -->|Why| Reason2[Symlink paths trigger manual approval on every file op] Use --> Done([Sub-agent inherits same working directory]) ``` ### Agent Selection ```mermaid flowchart TD Start([Select agent for task]) --> Q1{Task requires reasoning, interpretation, or analysis?} Q1 -->|No — exact file pattern or keyword search| Explore[Explore agent acceptable] Q1 -->|Yes| Q2{Needs repo convention awareness?} Q2 -->|Yes| CG[context-gathering agent] Q2 -->|No — general interpretation| Q3{Prompt optimization or AI-facing content?} Q3 -->|Yes| CCO[contextual-ai-documentation-optimizer agent] Q3 -->|No| CG Explore -.->|⚠️ Haiku-based ~50% hallucination rate on ambiguous queries| Warning[Never use for reasoning tasks] ``` **Explore Failure Modes** (validated 2026-02-02, 2/4 accuracy): - Semantic ambiguity: matched pre-commit hooks instead of Claude Code hooks - Premature termination: declared "not found" instead of deeper search - Fabricated implementations: suggested bash when repo uses Python/JavaScript SOURCE: Experimental validation (2026-02-02). Context-gathering: 4/4 correct. Explore: 2/4 correct. --- - Language Conventions: `.claude/rules/language-conventions.md` --- - Script Invocation: `.claude/rules/script-invocation.md` --- ## Path Fidelity Use user-provided paths exactly as given. **Reason**: Narrowing scope or appending filenames produces silent failures when the user intends directory-level examination. - Preserve directory paths — do not append filenames - Do not narrow scope by adding specific files - Skill/plugin is a DIRECTORY containing SKILL.md, references/, assets/ — examine the ecosystem, not a single file --- ## Deletion Safety Protocol Before deleting any file: 1. Verify replacement contains equivalent content 2. If agent says "NEEDS MERGE" but user says proceed, ASK for clarification 3. Reject deletion based on flawed or incomplete comparison After irreversible mistakes: - State concretely what was lost and what can/cannot be recovered - Speculating optimistically about loss magnitude is inaccurate — give concrete facts - Ask user what they want to do next --- ## Pre-Existing Issue Accountability Phrase "pre-existing issues not related to my changes" is a TRIGGER TO ACT, not a dismissal justification. **Required Response:** > I found [N] pre-existing [issue type] in the codebase. Want to plan how to address them in this session? If not, I'll add them to the backlog. **"Plan"**: Concrete steps (files, fixes, scope estimate). User decides priority. **"Backlog"**: Trackable record (backlog item, issue, task file) preventing loss. **Reason**: Dismissing pre-existing issues normalizes technical debt. Every encountered issue is an opportunity for remediation. ### Request Progression When you identify that work will need multiple steps or jobs: create backlog items for them — don't just describe them. 1. **Backlog**: Create via `create-backlog-item` or match via `work-backlog-item` before starting. 2. **Plan**: When writing a plan, add it to the item via `backlog update "{title}" --plan "{path}"`. 3. **Progress**: When completing actions, update the task/plan artifact (checklist, status) so progression is visible. Skip only for trivial single-step requests (typos, one-off questions, immediate one-action fixes). ### Backlog Operations **Single interface**: Use `.claude/skills/backlog/scripts/backlog.py` for all backlog and GitHub issue CRUD. GitHub Issues are the source of truth; `.claude/backlog/` per-item files are the local cache. Editing per-item files directly or using `gh` for issue CRUD bypasses sync logic — use the script. ```bash uv run .claude/skills/backlog/scripts/backlog.py add|list|sync|close|resolve|update ... ``` Skills `create-backlog-item` and `work-backlog-item` invoke this script. See `.claude/skills/backlog/SKILL.md`. --- - Plugin Development Workflows: `.claude/rules/plugin-development.md` --- - Content Optimization for Skills: `.claude/rules/skill-content-optimization.md` --- ## File Reference Standards ### Code Fence Language Specifiers Add language specifier to ALL code fences. **Reason**: Syntax highlighting and linter compliance. ````markdown # Section Title ```text Plain text content ``` ```python def example(): return True ``` ```` 4 backticks on outer fence, language specifiers on all inner fences, proper nesting. ### Markdown Links Use markdown links with relative paths starting with `./`. **Reason**: Enables Claude Code click-through, works regardless of installation location, and supports on-demand file loading. **Syntax**: `[descriptive text](./path/to/file.md)` **Directory Context:** - From SKILL.md → references: `[text](./references/filename.md)` - From references/file.md → same dir: `[text](./filename.md)` - From references/file.md → subdir: `[text](./subdir/filename.md)` **File Reference Decision:** ```mermaid flowchart TD Start([Reference a file]) --> Q1{Is it a skill?} Q1 -->|Yes| Skill[Use activation syntax: Skill command colon name] Q1 -->|No| Q2{Is it a file in the repo?} Q2 -->|Yes| Q3{Path starts with ./?} Q3 -->|Yes| Link["Use markdown link: [text](./path/to/file.md)"] Q3 -->|No — missing ./ prefix| Fix["Add ./ prefix: [text](./references/file.md)"] Q2 -->|No — external| Ext[Use full URL with access date] Link --> Done([Correct]) Fix --> Done Skill --> Done Ext --> Done Q3 -.->|Never| Bad1["Backtick paths: modern-modules/httpx.md"] Q3 -.->|Never| Bad2["Absolute paths: /home/user/repos/.../file.md"] ``` ### Skill Activation References Reference other skills using activation syntax: ✅ `For comprehensive Astral uv documentation, use the /uv skill.` ❌ `See /uv/SKILL.md for uv documentation` --- - Skill Documentation Verification: `.claude/rules/skill-documentation-verification.md` --- ## Citation Requirements Every factual claim in skill documentation requires a cited source. **Reason**: Without citations, guidance cannot be verified, updated, or trusted — and false claims persist across sessions. **Citation methods** (choose one per claim): - **Inline**: `SOURCE: [Title](URL) (accessed YYYY-MM-DD)` within the section making the claim - **Footer**: numbered `## References` section; cite as `[1]`, `[2]` in text - **Separate file**: `./references/references.md` — link from SKILL.md **By source type:** - Official docs: URL + access date - Skill derivations: link to source skill repo + note adaptations - User preferences: date of conversation + validation evidence if tested - Experimental results: method, sample size, results, dataset path - Forums/community: cite every source URL + access date **Verification checklist:** - [ ] Every factual claim has cited source - [ ] URLs include access dates (YYYY-MM-DD) - [ ] Citations distinguish official docs, community practices, opinions - [ ] Skill derivations link to source skill repository - [ ] User preferences note conversation date and validation evidence - [ ] Experimental claims reference datasets or methodology --- ## File Reference Verification Checklist When creating/updating reference files, verify: - [ ] All file references use markdown link syntax: `[text](./path)` - [ ] Relative paths start with `./` - [ ] Paths relative to file containing reference - [ ] Referenced files exist at those paths (verify with Read tool) - [ ] No backticks for file references (unless showing code/commands) - [ ] Language specifiers on all code fences - [ ] Nested code blocks use proper backtick counts (4 outer, 3 inner) --- ## Markdown Formatting Standards **MD031/blanks-around-fences**: Surround fenced code blocks with blank lines. ````markdown This is a paragraph. ```python def example(): return True ``` This is another paragraph. ```` --- ## Local Formatting and Linting Run before committing or after modifying any SKILL.md or reference file: ```bash uv run prek run --files ``` **Reason**: Repository uses `prek` (Rust-based pre-commit replacement) with `.pre-commit-config.yaml` — identical syntax to `pre-commit` but faster. --- - Linting Exception Conditions: `.claude/rules/linting-exceptions.md` --- - GitHub Actions CI Workflow Modification Protocol: `.claude/rules/ci-workflows.md` --- - YAML and TOML Libraries: `.claude/rules/yaml-toml-libraries.md` --- ## GitHub CLI (gh) Usage ### Installation `gh` not pre-installed. Install via the `/gh` skill: `Skill(command: "gh")`. ### Authentication and Repo Detection `GITHUB_TOKEN` set in environment — `gh` authenticates automatically. Git remote points to local proxy (`127.0.0.1`), not `github.com`, so `gh` cannot auto-detect the repository. Pass `-R` on every command: ```bash gh -R Jamie-BitFlight/claude_skills ``` ### Usage Examples ```bash # List recent workflow runs gh run list -R Jamie-BitFlight/claude_skills --limit=5 # View specific run gh run view -R Jamie-BitFlight/claude_skills # View failed job logs gh run view -R Jamie-BitFlight/claude_skills --log-failed # Check PR status gh pr checks -R Jamie-BitFlight/claude_skills # Create PR gh pr create -R Jamie-BitFlight/claude_skills --title "title" --body "body" ``` Use `gh` to verify workflow changes — CI output observation is part of Phase 5 (Verify) in the CI Workflow Modification Protocol.