A Skill is not just documentation. Its SKILL.md can shape how an agent reads files, runs commands, validates changes, and decides when to ask for approval. That makes placement an operational decision.

The confirmed provider model supports four useful scopes: project root, user root, shared Agent root, and a custom directory. The official configuration reference also exposes provider-related settings, including listener behavior. Check the version you deploy because default scan details and client display behavior can change between releases. See the official configuration reference and the official Skill provider source.

The important question is not “which path is shortest?” It is “who is allowed to change this agent behavior, and which projects should receive the change?”

Project-level placement is usually the safest default for a Skill that mentions a repository path, package manager, test command, deployment target, or local convention. The Skill and the code version can then be reviewed together.

A repository copy also makes onboarding reproducible. A new developer clones the project, starts the harness, and receives the same instructions instead of reconstructing a personal setup from memory.

That does not make every Skill safe to commit. Review the content before adding it to version control. Exclude API keys, SSH material, local absolute paths, machine-specific tokens, and generated state. A Skill should describe repeatable behavior, not store credentials.

Trust boundary reminder: if a Skill can influence shell commands, file writes, network access, or approval flow, review it like an executable policy file even when the file extension is .md.

Use a user-level Skill only when its behavior is genuinely independent of the repository.

Good examples include:

• A personal code-review rubric.
• A generic debugging sequence.
• A reusable explanation format.
• A workflow that uses standard tools and does not depend on internal paths.
• A personal preference for test reporting.

Poor candidates include:

• “Run the test command in this repository.”
• “Use the internal deployment script.”
• “Read the company architecture file from a fixed path.”
• “Approve changes according to this team's policy.”
• “Modify files under a project-specific directory.”

The user-level option reduces duplication. You update one copy, and several projects can discover it. That convenience is real, but it transfers the maintenance burden from repository review to personal configuration.

The hidden costs appear later:

• Unexpected activation: a generic name or broad description can cause the Skill to load in a project where it does not apply.
• Version drift: two projects may silently run different behavior because one user updated the global copy.
• Impact expansion: a faulty edit affects every project using that account.
• Onboarding gaps: another developer does not receive the Skill merely by cloning the repository.
• Remote mismatch: a cloud Mac or CI worker may not contain your local user directory.

Keep a small user-level set. If a Skill requires project context, promote it to project scope. If it requires team policy, move its source into a reviewed shared directory rather than leaving it in one engineer's home folder.

For a small team, the strongest compromise is not “global for everyone.” It is a two-layer design:

1. Maintain team Skills in a versioned shared source.
2. Expose only an approved revision to each project.
3. Keep repository-specific overrides at project scope.
4. Make the shared source read-only for ordinary agent sessions.
5. Record the selected revision in project documentation or configuration.

This separates source ownership from runtime discovery. The platform or maintainer owns the shared source. The project owner decides when to adopt an update.

Do not allow each Mac to maintain a manually edited copy. That creates configuration forks that are difficult to compare. One developer may have a newer SKILL.md, another may have a local patch, and a third may be running a stale copy from a previous machine.

A shared Skill can still be useful across projects. The boundary is write access and approval. Several projects may consume the same read-only revision. They should not all edit the same live directory.

For team adoption, test a representative task before changing the approved revision. Use the same repository state, prompt, and expected verification command. Record whether the Skill was discovered, loaded only when relevant, and prevented from affecting an unrelated project.

Remote environments create a different problem. A user-level Skill may work on a developer's Mac and disappear on a remote worker. A persistent home directory may also be unavailable, reset, or attached to the wrong account.

For platform teams, the Skill directory belongs in one of these delivery points:

• The machine image.
• Environment initialization.
• Job provisioning.
• A versioned workspace asset.
• A controlled custom directory selected by configuration.

The delivery mechanism must answer four questions:

• Where does the Skill arrive?
• Which account owns it?
• Is the directory writable?
• Does the Skill remain available after restart or worker replacement?

DSH_HOME can be useful when you need an explicit harness home for a remote execution pool, but do not assume that setting it alone delivers Skills. Verify that the configured Skill provider points to the intended directory and that the directory exists inside the actual execution context.

A remote worker should pass a discovery test before it accepts production jobs. The test should inspect the resolved directory, read the SKILL.md, start a fresh session, invoke a task that matches the description, and confirm that an unrelated project does not load the same Skill.

If your team uses cloud Macs, treat Skills as part of the handoff package rather than as an afterthought. The KVMNODE cloud Mac options can be evaluated alongside your initialization process, storage model, and restart policy. The machine is only ready when the agent configuration is reproducible, not merely when remote access works.

A writable global directory is convenient but dangerous when projects do not share the same trust boundary. A Skill created for an internal application should not automatically influence an external repository. The reverse is also true: an unreviewed community Skill should not be placed where sensitive projects can discover it.

Apply these controls:

• Review the source before installation.
• Require an owner for every shared Skill.
• Use read-only permissions in runtime environments.
• Keep secrets outside SKILL.md.
• Record the source revision and approval date.
• Separate personal, team, and production execution pools.
• Reject unexpected files added beside the Skill.
• Test behavior after restart and after synchronization.

Symbolic links deserve explicit review. A link can make a shared directory look stable while the target changes elsewhere. That may be acceptable for a local development workflow. It is weaker as a production delivery method unless the target is controlled, readable, and included in the integrity check.

The acceptance question is simple: can you explain exactly which file the agent will read after a restart? If the answer depends on a developer's home directory, an untracked link, or a mutable mount, the setup is not ready for a sensitive workload.

Use the following decision branches instead of choosing by habit:

• If the Skill refers to one repository's paths, commands, tests, or policies, choose project-level placement.
• If the Skill works across unrelated repositories and contains no internal path or approval rule, choose user-level placement.
• If several team projects need the same behavior, but releases must be reviewed and reversible, use a versioned shared source with project-level adoption.
• If the Skill must exist on every remote worker, put it in image, initialization, or custom-directory delivery. Do not depend on a personal home directory.
• If projects have different trust levels, do not use one writable global directory. Split the scopes or use read-only delivery.
• If you cannot prove which revision is active, stop the rollout and pin the source before continuing.

This produces a practical default:

Individual repository: project-level. Personal automation: user-level. Team baseline: shared source plus project-level version selection. Remote execution: provisioned directory with restart validation.

Use this sequence on a local Mac first, then repeat it on every remote execution class.

1. Create a minimal test Skill. Give it a unique name and a narrow description. Keep the instruction harmless, such as returning a known verification phrase.
2. Place it in one scope only. Test the project root, user root, shared Agent root, and custom directory separately. Do not test all locations at once.
3. Check the active configuration. Confirm the relevant provider is enabled and that DSH_HOME or another environment override resolves to the intended location.
4. Validate SKILL.md. Check the file name, front matter, description, permissions, and directory structure. A malformed file may be skipped without producing a clear user-facing error.
5. Start a fresh session. Do not assume an already running session will rebuild its Skill catalog after a file is added.
6. Run a matching task. Confirm the Skill is selected only when the task matches its description.
7. Run an unrelated task in another project. Confirm the Skill does not activate outside its intended boundary.
8. Test file changes. If listener behavior is enabled, edit the Skill and observe whether the active environment detects the change. If not, restart the session and record that limitation.
9. Restart the worker or Mac. Confirm the directory, ownership, link target, and Skill discovery result are unchanged.
10. Record the result. Save the active path, source revision, permissions, session behavior, and rollback instruction.

The official configuration documentation should be your source of truth for provider names and listener settings. The Skill tool implementation and provider implementation are useful when you need to distinguish documented behavior from implementation details. Use the configuration examples to compare your deployed structure without copying defaults blindly.

Which directory should hold DeepSeek Harness Skills?

Put repository-specific Skills beside the project that depends on them. Use a user-level directory only for Skills that remain valid across unrelated repositories. For team-managed Skills, keep the approved source in a versioned shared directory and expose it to projects through a controlled reference or synchronization step.

Can several projects share one DeepSeek Harness Skill?

Yes, but avoid sharing one writable copy across projects with different trust levels. A read-only shared source is safer. Each project should record the approved revision or synchronize a pinned copy so a change made for one repository cannot silently alter another project's agent behavior.

Why does DeepSeek Harness fail to find a newly added Skill?

The usual causes are an unsupported directory, an invalid SKILL.md structure, a disabled provider, or a session that has not refreshed its Skill catalog. Check the active configuration, confirm the file is readable, inspect the resolved path, then restart the session before testing discovery again.

How can a team sync Skills to cloud Macs?

Treat the Skill directory as part of the environment delivery package. Copy or mount the approved version during image initialization, startup, or job provisioning. Record the revision, ownership, permissions, and discovery result. Do not rely on an engineer's personal home directory surviving a remote session or machine replacement.

Keeping everything global seems efficient until one update changes agent behavior in several unrelated projects. Keeping everything project-level seems safe until a team has to maintain many duplicate copies. A versioned shared source with project-level adoption gives small teams a clear owner, a review point, and a rollback path without hiding the active revision.

If your current setup depends on manual copying, mutable global folders, undocumented symlinks, or remote home directories, it has four concrete weaknesses: inconsistent versions, unclear ownership, weak restart recovery, and poor isolation between projects. A rented Mac environment from KVMNODE is more useful when the Skills directory, selected revision, permissions, and discovery result are delivered as part of the environment rather than recreated by hand. Review the KVMNODE remote Mac ordering options only after defining those acceptance checks.

For a temporary test environment, a short-lived project migration, or a controlled team validation pool, rent the Mac and include Skill delivery in the sign-off record. For permanent heavy workloads or workflows that require direct physical interfaces, owning hardware may still be the better choice. The important decision is not project versus global in isolation. It is whether the active Skill can be identified, reviewed, reproduced, and rolled back on the machine that will actually run your agent.